Certificate user IDs

Users in Azure AD can have a multivalued attribute named certificateUserIds. The attribute allows up to four values, and each value can be of 120-character length. It can store any value, and doesn't require email ID format. It can store non-routable User Principal Names (UPNs) like bob@woodgrove or bob@local.

Supported patterns for certificate user IDs

The values stored in certificateUserIds should be in the format described in the following table.

Certificate mapping Field	Examples of values in CertificateUserIds
PrincipalName	“X509:<PN>bob@woodgrove.com”
PrincipalName	“X509:<PN>bob@woodgrove”
RFC822Name	“X509:<RFC822>user@woodgrove.com”
X509SKI	“X509:<SKI>123456789abcdef”
X509SHA1PublicKey	“X509:<SHA1-PUKEY>123456789abcdef”

Roles to update certificateUserIds

For cloud only users, only users with roles Global Administrators, Privileged Authentication Administrator can write into certificateUserIds. For sync'd users, AD users with role Hybrid Identity Administrator can write into the attribute.

Note

Active Directory Administrators (including accounts with delegated administrative privilege over sync'd user accounts as well as administrative rights over the Azure >AD Connect Servers) can make changes that impact the certificateUserIds value in Azure AD for any sync'd accounts.

Update certificate user IDs in the Azure portal

Tenant admins can use the following steps Azure portal to update certificate user IDs for a user account:

1. In the Azure portal, click All users (preview).

   

2. Click a user, and click Edit Properties.

3. Next to Authorization info, click View.

   

4. Click Edit certificate user IDs.

   

5. Click Add.

   

6. Enter the value and click Save. You can add up to four values, each of 120 characters.

   

Update certificate user IDs using Azure AD Connect

To update certificate user IDs for federated users, configure Azure AD Connect to sync userPrincipalName to certificateUserIds.

1. On the Azure AD Connect server, find and start the Synchronization Rules Editor.

   

2. Click Direction, and click Outbound.

   

3. Find the rule Out to AAD – User Identity, click Edit, and click Yes to confirm.

   

4. Enter a high number in the Precedence field, and then click Next.

   

5. Click Transformations > Add transformation. You may need to scroll down the list of transformations before you can create a new one.

Synchronize X509:<PN>PrincipalNameValue

To synchronize X509:<PN>PrincipalNameValue, create an outbound synchronization rule, and choose Expression in the flow type. Choose the target attribute as <certificateUserIds>, and in the source field, add the expression <"X509:<PN>"&[userPrincipalName]>. If your source attribute isn't userPrincipalName, you can change the expression accordingly.

Synchronize X509:<RFC822>RFC822Name

To synchronize X509:<RFC822>RFC822Name, create an outbound synchronization rule, choose Expression in the flow type. Choose the target attribute as <certificateUserIds>, and in the source field, add the expression <"X509:<RFC822>"&[userPrincipalName]>. If your source attribute isn't userPrincipalName, you can change the expression accordingly.

1. Click Target Attribute, select CertificateUserIds, click Source, select UserPrincipalName, and then click Save.

   

2. Click OK to confirm.

Note

Make sure you use the latest version of Azure AD Connect.

For more information about declarative provisioning expressions, see Azure AD Connect: Declarative Provisioning Expressions.

Synchronize alternativeSecurityId attribute from AD to Azure AD CBA CertificateUserIds

AlternativeSecurityId isn't part of the default attributes. An administrator needs to add the attribute to the person object, and then create the appropriate synchronization rules.

1. Open Metaverse Designer, and select alternativeSecurityId to add it to the person object.

   

2. Create an inbound synchronization rule to transform from altSecurityIdentities to alternateSecurityId attribute.

   

3. Create an outbound synchronization rule to transform from alternateSecurityId attribute to certificateUserIds alt-security-identity-add.

   

To map the pattern supported by certificateUserIds, administrators must use expressions to set the correct value.

You can use the following expression for mapping to SKI and SHA1-PUKEY:

IIF(IsPresent([alternativeSecurityId]),
                Where($item,[alternativeSecurityId],BitOr(InStr($item, "x509:<SKI>"),InStr($item, "x509:<SHA1-PUKEY>"))>0),[alternativeSecurityId]
)

Look up certificateUserIds using Microsoft Graph queries

Authorized callers can run Microsoft Graph queries to find all the users with a given certificateUserId value. On the Microsoft Graph user object, the collection of certificateUserIds are stored in the authorizationInfo property.

To retrieve all user objects that have the value 'bob@contoso.com' in certificateUserIds:

GET https://graph.microsoft.com/v1.0/users?$filter=authorizationInfo/certificateUserIds/any(x:x eq 'bob@contoso.com')&$count=true
ConsistencyLevel: eventual

You can also use the not and startsWith operators to match the filter condition. To filter against the certificateUserIds object, the request must include the $count=true query string and the ConsistencyLevel header set to eventual.

Update certificateUserIds using Microsoft Graph queries

Run a PATCH request to update the certificateUserIds for a given user.

Request body:

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-Type: application/json

{
    "authorizationInfo": {
        "certificateUserIds": [
            "X509:<PN>123456789098765@mil"
        ]
    }
}

Next steps

• Overview of Azure AD CBA
• Technical deep dive for Azure AD CBA
• How to configure Azure AD CBA
• Azure AD CBA on iOS devices
• Azure AD CBA on Android devices
• Windows smart card logon using Azure AD CBA
• How to migrate federated users
• FAQ