Microsoft 标识平台应用程序身份验证证书凭据Microsoft identity platform application authentication certificate credentials

Microsoft 标识平台允许应用程序在任何可以使用客户端机密的地方使用其自己的凭据进行身份验证,例如,在 OAuth 2.0 客户端凭据授权流和代理 (OBO) 流中。Microsoft identity platform allows an application to use its own credentials for authentication anywhere a client secret could be used, for example, in the OAuth 2.0 client credentials grant flow and the on-behalf-of (OBO) flow.

应用程序可用于身份验证的一种凭据形式是使用应用程序拥有的证书签名的 JSON Web 令牌 (JWT) 断言。One form of credential that an application can use for authentication is a JSON Web Token (JWT) assertion signed with a certificate that the application owns.

断言格式Assertion format

若要计算断言,可以使用所选语言的多个 JWT 库之一 - MSAL 使用 .WithCertificate() 对此提供支持。To compute the assertion, you can use one of the many JWT libraries in the language of your choice - MSAL supports this using .WithCertificate(). 令牌在其标头声明签名中携带相关信息。The information is carried by the token in its Header, Claims, and Signature.

参数Parameter 备注Remark
alg 应为 RS256Should be RS256
typ 应为 JWTShould be JWT
x5t 编码为 Base64url 字符串值的 x.509 证书哈希(也称为证书的 SHA-1 指纹)的十六进制表示形式。The X.509 certificate hash's (also known as the cert's SHA-1 thumbprint) Hex representation encoded as a Base64url string value. 例如,如果 x.509 证书哈希为 84E05C1D98BCE3A5421D225B140B36E86A3D5534(十六进制),x5t 声明就会是 hOBcHZi846VCHSJbFAs26Go9VTQ= (Base64url)。For example, given an X.509 certificate hash of 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hex), the x5t claim would be hOBcHZi846VCHSJbFAs26Go9VTQ= (Base64url).

声明(有效负载)Claims (payload)

声明类型Claim type Value 说明Description
audaud https://login.partner.microsoftonline.cn/{tenantId}/v2.0 “aud”(受众)声明标识 JWT 预期的收件人(在这里为 Azure AD)。请参阅 RFC 7519 的 4.1.3 节The "aud" (audience) claim identifies the recipients that the JWT is intended for (here Azure AD) See RFC 7519, Section 4.1.3. 在本例中,该收件人为登录服务器 (login.partner.microsoftonline.cn)。In this case, that recipient is the login server (login.partner.microsoftonline.cn).
expexp 16015194141601519414 “exp”(过期时间)声明指定只能在哪个时间(含)之前接受 JWT 的处理。The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. 请参阅 RFC 7519 的 4.1.4 节See RFC 7519, Section 4.1.4. 这样就可以在这之前一直使用断言,所以时间要短 - 最多在 nbf 之后 5 - 10 分钟。This allows the assertion to be used until then, so keep it short - 5-10 minutes after nbf at most. Azure AD 当前未对 exp 时间设置限制。Azure AD does not place restrictions on the exp time currently.
ississ {ClientID}{ClientID} “iss”(颁发者)声明标识颁发了 JWT 的主体,在本例中是你的客户端应用程序。The "iss" (issuer) claim identifies the principal that issued the JWT, in this case your client application. 使用 GUID 应用程序 ID。Use the GUID application ID.
jtijti (一个 GUID)(a Guid) “jti”(JWT ID) 声明为 JWT 提供唯一标识符。The "jti" (JWT ID) claim provides a unique identifier for the JWT. 分配标识符值时,所用方式必须确保几乎不可能将同一值意外分配给不同的数据对象;如果应用程序使用多个颁发者,还必须防止在不同的颁发者生成的值之间发生冲突。The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. “jti”值是一个区分大小写的字符串。The "jti" value is a case-sensitive string. RFC 7519 的 4.1.7 节RFC 7519, Section 4.1.7
nbfnbf 16015191141601519114 “nbf”(不早于)声明指定只能在哪个时间之后接受 JWT 的处理。The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. RFC 7519 的 4.1.5 节RFC 7519, Section 4.1.5. 使用当前时间是合适的。Using the current time is appropriate.
subsub {ClientID}{ClientID} “sub”(使用者)声明标识 JWT 的使用者,在本例中也是你的应用程序。The "sub" (subject) claim identifies the subject of the JWT, in this case also your application. 使用与 iss 相同的值。Use the same value as iss.

签名Signature

签名是通过应用证书计算出来的,如 JSON Web 令牌 RFC7519 规范所述。The signature is computed by applying the certificate as described in the JSON Web Token RFC7519 specification.

已解码的 JWT 断言示例Example of a decoded JWT assertion

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.partner.microsoftonline.cn/contoso.partner.onmschina.cn/oauth2/token",
  "exp": 1484593341,
  "iss": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05",
  "jti": "22b3bb26-e046-42df-9c96-65dbd72c1c81",
  "nbf": 1484592741,
  "sub": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05"
}
.
"Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

已编码的 JWT 断言示例Example of an encoded JWT assertion

以下字符串是已编码的断言的示例。The following string is an example of encoded assertion. 如果你仔细查看,会注意到由句点 (.) 分隔的三个部分:If you look carefully, you notice three sections separated by dots (.):

  • 第一部分对标头编码The first section encodes the header
  • 第二部分对声明(有效负载)编码The second section encodes the claims (payload)
  • 最后一部分是使用前两部分内容中的证书计算出来的签名The last section is the signature computed with the certificates from the content of the first two sections
"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

向 Microsoft 标识平台注册证书Register your certificate with Microsoft identity platform

可以使用以下任意方法通过 Azure 门户将证书凭据与 Microsoft 标识平台中的客户端应用程序相关联:You can associate the certificate credential with the client application in Microsoft identity platform through the Azure portal using any of the following methods:

上传证书文件Uploading the certificate file

在客户端应用程序的 Azure 应用注册中:In the Azure app registration for the client application:

  1. 选择“证书和机密”。Select Certificates & secrets.
  2. 单击“上传证书”,然后选择要上传的证书文件。Click on Upload certificate and select the certificate file to upload.
  3. 单击“添加”。Click Add. 上传证书后,将显示指纹、开始日期和到期日期值。Once the certificate is uploaded, the thumbprint, start date, and expiration values are displayed.

更新应用程序清单Updating the application manifest

拥有证书后需计算:Having hold of a certificate, you need to compute:

  • $base64Thumbprint - 证书哈希的 Base64 编码值$base64Thumbprint - Base64-encoded value of the certificate hash
  • $base64Value - 证书原始数据的 Base64 编码值$base64Value - Base64-encoded value of the certificate raw data

还需要提供 GUID 来标识应用程序清单中的密钥 ($keyId)。You also need to provide a GUID to identify the key in the application manifest ($keyId).

在客户端应用程序的 Azure 应用注册中:In the Azure app registration for the client application:

  1. 选择“清单”以打开应用程序清单。Select Manifest to open the application manifest.

  2. 使用以下架构将 keyCredentials 属性替换为新的证书信息。Replace the keyCredentials property with your new certificate information using the following schema.

    "keyCredentials": [
        {
            "customKeyIdentifier": "$base64Thumbprint",
            "keyId": "$keyid",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "value":  "$base64Value"
        }
    ]
    
  3. 将所做的编辑保存到应用程序清单,然后将清单上传到 Microsoft 标识平台。Save the edits to the application manifest and then upload the manifest to Microsoft identity platform.

    keyCredentials 属性具有多个值,因此可上传多个证书实现更丰富的密钥管理。The keyCredentials property is multi-valued, so you may upload multiple certificates for richer key management.

使用客户端断言Using a client assertion

客户端断言可以在任何使用客户端机密的地方使用。Client assertions can be used anywhere a client secret would be used. 例如,在授权代码流中,你可以传入一个 client_secret 来证明请求来自你的应用。So for example, in the authorization code flow, you can pass in a client_secret to prove that the request is coming from your app. 可以用 client_assertionclient_assertion_type 参数替换它。You can replace this with client_assertion and client_assertion_type parameters.

参数Parameter ValueValue 说明Description
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer 这是一个固定值,表示你正在使用证书凭据。This is a fixed value, indicating that you are using a certificate credential.
client_assertion JWTJWT 这是上面创建的 JWT。This is the JWT created above.

后续步骤Next steps

MSAL.NET 库用单行代码处理这种情况The MSAL.NET library handles this scenario in a single line of code.

GitHub 上的使用 Microsoft 标识平台的 .NET Core 守护程序控制台应用程序代码示例展示了应用程序如何使用自己的凭据进行身份验证。The .NET Core daemon console application using Microsoft identity platform code sample on GitHub shows how an application uses its own credentials for authentication. 它还展示了如何使用 New-SelfSignedCertificate PowerShell cmdlet 创建自签名证书It also shows how you can create a self-signed certificate using the New-SelfSignedCertificate PowerShell cmdlet. 你还可以使用示例存储库中的应用创建脚本来创建证书、计算指纹,以及进行其他操作。You can also use the app creation scripts in the sample repo to create certificates, compute the thumbprint, and so on.