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.
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.
Fig. 2. The User AD attributes & tokens page in CodeTwo Admin Panel.
Admin roles in CodeTwo Email Signatures for Office 365
Read this article to find out who can perform the actions discussed further in the article.
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.
The first synchronization (after you registered a new tenant) might take longer and depends on the size and structure of your Azure Active Directory. It usually takes a few minutes to complete if you have less than a thousand users. It may take even a few hours if you have thousands of users.
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.
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:
- 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.
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.
|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.
Exchange Online additional attributes can be used in the template editor only. On the other hand, you can use common attributes, Exchange Online custom attributes, attributes synced from on-prem Exchange Server, and CodeTwo custom attributes also when defining conditions of an email signature rule or an autoresponder rule (the Azure AD filter option).
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.
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.).
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.
Shared mailboxes are not supported by this synchronization. However, if you need an extra set of additional attributes e.g. to use in an email signature for a shared mailbox, you can take advantage of our User attributes manager to create custom attributes and apply them in your signature template. Learn more
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.
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.
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.
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, you need to use the Microsoft 365 custom attributes in your signatures.
How to use AD attributes (placeholders) in the signature template editor