User AD attributes & Tokens

CodeTwo Email Signatures for Office 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.

The Placeholder menu allows you to insert AD attributes to signatures.
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, log in to the CodeTwo Admin Panel, open the Dashboard or Tenants tab and click the Manage tenant (ESIG for O365 settings button2 13px) button next to your tenant's name. This page is divided into several sections. Use the links below to learn about each section.

The User AD attributes & tokens page in CodeTwo Admin Panel.
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.).

The Azure AD cache section.
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.

Important

Your credentials are completely safe as they are passed directly and only to Microsoft servers, which is ensured by the Azure's OAuth 2.0 authorization. CodeTwo does not store, copy or have access to your global admin credentials.

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:

  • log in to app.codetwo.com (or the Manage Signatures App) as global admin, click the ESIG for O365 More button button in the upper-right corner and select Settings (Admin Panel), as shown in Fig. 4., or
  • log in directly to the CodeTwo Admin Panel, go to the Dashboard or Tenants tab, and click the Manage tenant (ESIG for O365 settings button2 13px) button next to the name of your tenant.

Accessing the tenant settings while managing email signatures.
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 log in. Be sure to select the work account that belongs to a global admin of this tenant.

The OAuth 2.0 tokens section in CodeTwo Admin Panel.
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 (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.

Exchange Online (Microsoft 365) custom attributes 1-15 available under the Placeholder menu.
Fig. 6. Exchange Online (Microsoft 365) custom attributes 1-15 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
Exchange Online (Microsoft 365) additional attributes: Initials, Notes, P.O. Box, Pager, Web page, Home phone Yes (additional synchronization required) No
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)

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

Important

Custom attributes and additional attributes can only be used in email signatures. These attributes are not available when defining conditions of an email signature rule.

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 (ESIG for O365 settings button2 13px) 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.).

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

Info

If you work in a non-hybrid environment but the Synchronize attributes button is not displayed, contact CodeTwo Support.

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

The attribute synchronization wizard.
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.

Synchronization of additional attributes in 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.

Important

Shared mailboxes are not supported by this synchronization.

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 (ESIG for O365 settings button2 13px) 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.

ESIG 365 Additional attributes - hybrid configured
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.

ESIG 365 Additional attributes - hybrid unconfig
Fig. 11. This is how the section looks like when local attributes are not synced.

Info

If you have a hybrid environment, but you do not see the Additional attributes section as shown above, contact CodeTwo Support.

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.

Configuration of Azure AD Connect, step 1.
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.

Configuration of Azure AD Connect, step 2.
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.

Why sometimes you can see both Microsoft 365 (Office 365) custom attributes 1-15 and local Extension attributes 1-15 in the signature template editor

If you're synchronizing the extensionAttribute1-15 from your local AD via Azure AD Connect, their values will overwrite the values of your Microsoft 365 custom attributes 1-15. Both sets of attributes will be displayed in the editor's Placeholder > Message Sender > Custom AD attributes menu and even though they have the same values, we recommend using the Microsoft 365 custom attributes in your signatures.

See also

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

Was this information useful?