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, 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 库之一。To compute the assertion, you can use one of the many JWT libraries in the language of your choice. 令牌在其标头声明签名中携带相关信息。The information is carried by the token in its Header, Claims, and Signature.

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

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

参数Parameter 备注Remarks
aud 受众:应为 https://login.partner.microsoftonline.cn/<your-tenant-id>/oauth2/tokenAudience: Should be https://login.partner.microsoftonline.cn/<your-tenant-id>/oauth2/token
exp 到期日期:令牌的到期日期。Expiration date: The date when the token expires. 该时间表示为自 1970 年 1 月 1 日 (1970-01-01T0:0:0Z) UTC 至令牌有效期到期的秒数。The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the token validity expires. 建议使用较短的到期时间(10 分钟至 1 小时)。We recommend using a short expiration time - 10 minutes to one hour.
iss 颁发者:应为 client_id(客户端服务的应用程序(客户端)ID)Issuer: Should be the client_id (Application (client) ID of the client service)
jti GUID:JWT IDGUID: The JWT ID
nbf 不早于:在此日期之前不能使用令牌。Not Before: The date before which the token cannot be used. 该时间表示为自 1970 年 1 月 1 日 (1970-01-01T0:0:0Z) UTC 起至断言创建时间的秒数。The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the assertion was created.
sub 使用者:对于 iss,应为 client_id(客户端服务的应用程序(客户端)ID)Subject: As for iss, should be the client_id (Application (client) ID of the client service)

签名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.

后续步骤Next steps

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.