Edit

Certificate user IDs

  • Article

Users in Microsoft Entra ID 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. Cloud-only users can use both UX and MSGraph to write into certificateUserIds. For synched users, AD users with role Hybrid Identity Administrator can write into the attribute. Only Azure ADConnect can be used to update CertificateUserIds by syncing the value from on-prem for synched users.

Note

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

Update certificate user IDs

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

  1. Sign in to the Microsoft Entra admin center as at least a User Administrator. Search for and select All users.

    Screenshot of test user account.

  2. Click a user, and click Edit Properties.

  3. Next to Authorization info, click View.

    Screenshot of View authorization info.

  4. Click Edit certificate user IDs.

    Screenshot of Edit certificate user IDs.

  5. Click Add.

    Screenshot of how to add a CertificateUserID.

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

    Screenshot of a value to enter for CertificateUserId.

Update certificateUserIds using Microsoft Graph queries

Look up certificateUserIds

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 is 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

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"
        ]
    }
}

Update certificateUserIds using PowerShell commands

For the configuration, you can use the Azure Active Directory PowerShell Version 2:

  1. Start PowerShell with administrator privileges.

  2. Install and Import the Microsoft Graph PowerShell SDK

        Install-Module Microsoft.Graph -Scope AllUsers
    Import-Module Microsoft.Graph.Authentication
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  3. Connect to the tenant and accept all

       Connect-MGGraph -Scopes "Directory.ReadWrite.All", "User.ReadWrite.All" -TenantId <tenantId>

  4. List CertificateUserIds attribute of a given user

      $results = Invoke-MGGraphRequest -Method get -Uri 'https://graph.microsoft.com/v1.0/users/<userId>?$select=authorizationinfo' -OutputType PSObject -Headers @{'ConsistencyLevel' = 'eventual' }
  #list certificateUserIds
  $results.authorizationInfo

  5. Create a variable with CertificateUserIds values

      #Create a new variable to prepare the change. Ensure that you list any existing values you want to keep as this operation will overwrite the existing value
  $params = @{
        authorizationInfo = @{
              certificateUserIds = @(
              "X509:<SKI>eec6b88788d2770a01e01775ce71f1125cd6ad0f", 
              "X509:<PN>user@contoso.com"
              )
        }
  }

  6. Update CertificateUserIds attribute

       $results = Invoke-MGGraphRequest -Method patch -Uri 'https://graph.microsoft.com/v1.0/users/<UserId>/?$select=authorizationinfo' -OutputType PSObject -Headers @{'ConsistencyLevel' = 'eventual' } -Body $params

Update CertificateUserIds using user object

  1. Get the user object

      $userObjectId = "6b2d3bd3-b078-4f46-ac53-f862f35e10b6"
  $user = get-mguser -UserId $userObjectId -Property AuthorizationInfo

  2. Update the CertificateUserIds attribute of the user object

       $user.AuthorizationInfo.certificateUserIds = @("X509:<SKI>eec6b88788d2770a01e01775ce71f1125cd6ad0f", "X509:<PN>user1@contoso.com") 
   Update-MgUser -UserId $userObjectId -AuthorizationInfo $user.AuthorizationInfo

Update certificate user IDs using Microsoft Entra Connect

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

  1. On the Microsoft Entra Connect server, find and start the Synchronization Rules Editor.

    Screenshot of Synchronization Rules Editor.

  2. Click Direction, and click Outbound.

    Screenshot of outbound synchronization rule.

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

    Screenshot of user identity.

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

    Screenshot of a precedence value.

  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 following expression. If your source attribute isn't userPrincipalName, you can change the expression accordingly.

"X509:\<PN>"&[userPrincipalName]

Screenshot of how to sync x509.

Synchronize X509:<RFC822>RFC822Name

To synchronize X509:<RFC822>RFC822Name, 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 following expression. If your source attribute isn't userPrincipalName, you can change the expression accordingly.

"X509:\<RFC822>"&[userPrincipalName]

Screenshot of how to sync RFC822Name.

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

    Screenshot of how to save a rule.

  2. Click OK to confirm.

Note

Make sure you use the latest version of Microsoft Entra Connect.

For more information about declarative provisioning expressions, see Microsoft Entra Connect: Declarative Provisioning Expressions.

Synchronize alternativeSecurityId attribute from AD to Microsoft Entra 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.

    Screenshot of how to add alternativeSecurityId to the person object

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

    In the inbound rule, use the following options.

    Option Value
    Name Descriptive name of the rule, such as: In from AD - altSecurityIdentities
    Connected System Your on-premises AD domain
    Connected System Object Type user
    Metaverse Object Type person
    Precedence Choose a random high number not currently used

    Then proceed to the Transformations tab and do a direct mapping of the target attribute of alternativeSecurityId to altSecurityIdentities as shown below.

    Screenshot of how to transform from altSecurityIdentities to alternateSecurityId attribute

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

    Option Value
    Name Descriptive name of the rule, such as: Out to Microsoft Entra ID - certificateUserIds
    Connected System Your Microsoft Entra domain
    Connected System Object Type user
    Metaverse Object Type person
    Precedence Choose a random high number not currently used

    Then proceed to the Transformations tab and change your FlowType option to Expression, the target attribute to certificateUserIds and then input the below expression in to the Source field.

    Screenshot of outbound synchronization rule to transform from alternateSecurityId attribute to certificateUserIds

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]
)

Next steps