Get-EntraUserCertificateUserIdsFromCertificate

Reference

Module:: Microsoft.Entra

Returns an object with the certificate values needed to configure CertificateUserIDs for Certificate-Based Authentication in Microsoft Entra ID.

Syntax

Get-EntraUserCertificateUserIdsFromCertificate
   [-Path] <string>
   [[-Certificate] <System.Security.Cryptography.X509Certificates.X509Certificate2>
   [-CertificateMapping] <string>]
   [<CommonParameters>]

Description

The Get-EntraUserCertificateUserIdsFromCertificate returns an object with certificateUserIDs values derived from the provided certificate file, following the format required by Microsoft Entra ID for Certificate-Based Authentication, as described in the official documentation.

In delegated scenarios using work or school accounts, the signed-in user must have a Microsoft Entra role or custom role with the necessary permissions. The following least privileged roles support this operation:

Privileged Authentication Administrator (for Cloud-only users)
Hybrid Identity Administrator (for synchronized users)

Examples

Example 1: Retrieve certificate object from a certificate path

Get-EntraUserCertificateUserIdsFromCertificate -Path 'C:\path\to\certificate.cer'

Name                           Value
----                           -----
Subject                        X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest
IssuerAndSerialNumber          X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>eF3gH4iJ5kL6mN7oP8qR9sT0uV
RFC822Name                     X509:<RFC822>[email protected]
SHA1PublicKey                  X509:<SHA1-PUKEY>cD2eF3gH4iJ5kL6mN7oP8qR9sT
IssuerAndSubject               X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest
SKI                            X509:<SKI>aB1cD2eF3gH4iJ5kL6mN7oP8qR
PrincipalName                  X509:<PN>[email protected]

This example shows how to get all possible certificate mappings as an object.

Example 2: Retrieve certificate object from a certificate path and certificate mapping

Get-EntraUserCertificateUserIdsFromCertificate -Path 'C:\path\to\certificate.cer' -CertificateMapping 'Subject'

X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest

This command returns the PrincipalName property.

Example 3: Retrieve certificate object from a certificate

$text = "-----BEGIN CERTIFICATE-----
MIIDiz...=
-----END CERTIFICATE-----"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($text)
$certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes)
Get-EntraUserCertificateUserIdsFromCertificate -Certificate $certificate -CertificateMapping 'Subject'

X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest

This command returns the PrincipalName property.

Parameters

-Certificate

Certificate from which the certificateUserIDs mappings will be extracted

Type:	System.Security.Cryptography.X509Certificates.X509Certificate2
Aliases:	CertificateObject, Cert
Position:	2
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-CertificateMapping

One of the values PrincipalName, RFC822Name, IssuerAndSubject, Subject, SKI, SHA1PublicKey, and IssuerAndSerialNumber. The meaning of each value is describe in the official documentation of certificateUserIds.

Type:	System.String
Position:	3
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Path

Path to the certificate file, it can be either a cer or pem file.

Type:	System.String
Position:	1
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

Share via