User AD attributes & tokens

CodeTwo Email Signatures 365 allows you to add Active Directory attributes of your users to their email signatures. The program supports all the single-value attributes available in Microsoft 365 (Azure AD) and Azure AD Graph API. Multivalue attributes are not supported (learn more).

By default, the most common attributes related to message sender and message properties are available in the signature template editor (Fig. 1.). Additional attributes (such as extension attributes or user-defined attributes) may require further configuration to be accessible, as described later in this article.

Fig. 1. The Placeholder menu allows you to insert AD attributes to signatures.

You can manage attribute related options on the User AD attributes & tokens page of your tenant (Fig. 2.). To access it, sign in to the CodeTwo Admin Panel, open the Dashboard or Tenants tab and click the Manage tenant () button next to your tenant's name. This page is divided into several sections. Use the links below to learn about each section.

• Azure AD cache
• OAuth 2.0 tokens
• Additional attributes

Fig. 2. The User AD attributes & tokens page in CodeTwo Admin Panel.

Azure AD cache

The application stores required user attributes in an internal cache and automatically synchronizes them with your tenant's Azure Active Directory every 20 minutes. This is necessary both to quickly add signatures with placeholders to emails sent by specific users based on current rules, and to keep Azure AD load at a minimum. If necessary, you can manually update the Azure AD cache via the Update cache manually now button (Fig. 3.).

Fig. 3. The Azure AD cache section.

OAuth 2.0 tokens

To read users' Active Directory attributes, the program accesses them via OAuth 2.0 access tokens. These tokens are generated by Microsoft’s trusted OAuth servers. By default, these tokens are generated for the global admin account used to register your Microsoft 365 (Office 365) tenant in the CodeTwo Admin Panel, but you can use other global admin accounts within the same tenant to refresh them.

When tokens expire

Access tokens are set to not expire, but there are some exceptions. Tokens can expire if you change:

• the password of the global admin account that was used to generate (or previously refresh) these tokens. This is usually the admin account that manages your tenant in the CodeTwo Admin Panel;
• the authentication method of that admin account, e.g. enable/disable multi-factor authentication (MFA);
• the security settings in your organization;
• the MFA service settings for trusted devices (learn more).

If the tokens expired, you need to refresh them or the application won't be able to read the values of user AD attributes. This may lead to outdated user information appearing in your signatures.

How to refresh the OAuth 2.0 tokens

You will receive an email notification after your tokens expire. This message will contain a link to a website that allows you to refresh your tokens.

You can also refresh the tokens at any time directly on the Manage tenant page in the CodeTwo Admin Panel. To access that page:

• sign in to app.codetwo.com as global admin, click the user icon in the upper-right corner and select Settings (Admin Panel), as shown in Fig. 4., or
• sign in directly to the CodeTwo Admin Panel, go to the Dashboard or Tenants tab, and click the Manage tenant () button next to the name of your tenant.

Fig. 4. Accessing the tenant settings while managing email signatures.

Either way, once you are on the Manage Tenant page, click User AD attributes & tokens in the left menu and use the Refresh tokens button located in the OAuth 2.0 tokens section (Fig. 5.).

When refreshing tokens, the Microsoft sign-in screen appears, and you need to sign in. Be sure to select the work account that belongs to a global admin of this tenant.

Fig. 5. The OAuth 2.0 tokens section in CodeTwo Admin Panel.

Additional attributes

The most common Azure AD attributes, including Exchange Online (Microsoft 365) custom attributes 1-15, as well as CodeTwo custom attributes (Fig. 6.) are available in the signature template editor and can be inserted to email signatures as placeholders. Depending on your environment, you can also use additional attributes, as shown in the table below.

Fig. 6. Exchange Online (Microsoft 365) custom attributes 1-15 and CodeTwo custom attributes available under the Placeholder menu.

Attributes	Are these attributes available in the signature editor?
	Cloud (non-hybrid) environments	Hybrid environments
Common AD/AAD attributes related to message sender (see full list here)	Yes	Yes
Exchange Online (Microsoft 365) custom attributes 1-15	Yes	Yes
CodeTwo custom attributes (learn more)	Yes	Yes
Exchange Online (Microsoft 365) additional attributes: Initials, Notes, P.O. Box, Pager, Web page, Home phone	Yes (additional synchronization required)	Yes* (additional synchronization required)
Exchange Server custom attributes (extension attributes) 1-15; other local single-value attributes such as homePhone, info, etc.; non-standard attributes created in AD and synced to Azure AD	No	Yes (additional synchronization required)

* The listed Exchange Online additional attributes have their on-premises Exchange Server counterparts. Some of them can be used in email signatures in a hybrid environment only after performing an additional synchronization by using the Azure AD Connect tool (for more information, refer to this section). In such case, on-premises attributes’ values will be mapped to Exchange Online ones (e.g. wWWHomePage will be mapped to Web page). At the same time, Exchange Online attribute names will be displayed in the signature template editor. Keep in mind that multivalue on-premises attributes (such as postOfficeBox) are not supported.

Choose your environment type to learn more about the available additional attributes.

• Cloud (non-hybrid) environments
• Hybrid environments

Cloud (non-hybrid) environments

The following additional attributes: Initials, HomePhone, Notes, Pager, PostOfficeBox and WebPage are managed in the Exchange Online admin center. They are not automatically synced to CodeTwo and PowerShell commands need to be used to access them. If you want to use them in email signatures in the same way as other generally available placeholders (see details earlier in the article), you need to synchronize them with our service.

You can do that directly in the CodeTwo Admin Panel: go to the Dashboard or Tenants tab and click the Manage tenant () button next to the tenant name. Select User AD attributes & tokens from the left menu and click the Synchronize attributes button located in the Additional attributes section (Fig. 7.).

Fig. 7. The Additional attributes section before the synchronization of additional attributes.

The Synchronize additional attributes wizard opens (Fig. 8.).

Fig. 8. The attribute synchronization wizard.

We need your authorization to sync your additional attributes. Copy the temporary authorization code provided and click Authorize to open the Microsoft sign-in page in a new window (or new tab in your browser). Paste the code and click Next. Sign in as a global admin of your Microsoft 365 tenant to proceed with the synchronization. Note that CodeTwo does not store, copy or have access to your admin credentials in the process.

When you're successfully signed in, close the sign-in page to get back to the User AD attributes & tokens page in the Admin Panel. Your additional attributes are now being synchronized. It might take a while depending on the size of your organization. The progress is shown in the Additional attributes section (Fig. 9.) - refresh the page to check the progress.

Fig. 9. Synchronization of additional attributes in progress.

When the status changes to Synchronized, you can start using the additional attributes in email signatures - they are now available in the signature template editor in the Placeholder > Message Sender menu (see Fig. 1.).

You need to run the synchronization wizard each time you make changes to these attributes in Exchange Online. Otherwise, outdated information will appear in your signatures.

Hybrid environments

Hybrid Exchange & Microsoft 365 (Office 365) organizations can use on-premises directory extension attributes (such as homePhone, info, extensionAttribute1-15 and other single-value attributes from local AD) in email signatures, in the same way as other generally available placeholders (see attribute availability). But to be able to do so, these attributes need to be synchronized from on-premises Active Directory to Azure AD (Microsoft 365) using Microsoft's Azure Active Directory Connect tool.

CodeTwo Admin Panel lets you verify if such synchronization is enabled in your organization. To check that, open CodeTwo Admin Panel, enter the management pages of a chosen tenant by clicking the Manage tenant () button next to the tenant's name, then select User AD attributes & tokens from the left menu and scroll down to the Additional attributes section.

If your local AD attributes are correctly synced, the Additional attributes section looks as in Fig. 10. This means that all is set up and you can use them in email signatures - see guidelines.

Fig. 10. This is how the Additional attributes section looks like when local attributes are synced.

If your local AD attributes are not synced, the Additional attributes section looks as in Fig. 11.

Fig. 11. This is how the section looks like when local attributes are not synced.

To synchronize these additional AD attributes, open your Azure AD Connect. Then, enable the Directory extension attribute sync feature in the Sync > Optional Features section, as shown in Fig. 12.

Fig. 12. Configuration of Azure AD Connect, step 1.

Click Next to navigate to the Directory Extensions section (Fig. 13.). Select your attributes from the list on the left (you can choose any attributes from the list but they need to be single-valued to work) and move them to the list on the right. Complete the wizard by clicking Next.

Fig. 13. Configuration of Azure AD Connect, step 2.

When you finish the configuration, the AD attributes you selected will be synchronized to Azure AD. The Additional attributes section in the CodeTwo Admin Panel will confirm their availability (it will look like in Fig. 10.).

The additional on-premises directory extension attributes can now be used in email signatures - they are available in the Placeholder > Message Sender menu in the signature template editor (see Fig. 1.). ExtensionAttribute1-15 and less common AD attributes are available under Message Sender > Custom AD attributes, as show in Fig. 6. or this example. Check out this article to learn how to use placeholders.

See also

How to use AD attributes (placeholders) in the signature template editor