通过

使用 Microsoft Graph 向应用添加证书

  • 项目

Microsoft Entra ID支持三种类型的凭据对应用和服务主体进行身份验证：密码 (应用机密) 、证书和联合标识凭据。 如果无法对应用使用联合标识凭据，我们强烈建议使用证书而不是机密。

可以使用 Microsoft Entra 管理中心添加或删除证书。 但是，在自动化方案中，可能需要自动执行应用或服务主体的证书滚动更新。

本文提供有关使用 Microsoft Graph 和 PowerShell 脚本以编程方式更新应用注册证书凭据的指南。

先决条件

若要完成本教程，需要以下资源和特权：

  • 活动Microsoft Entra租户。
  • 一个 API 客户端，例如 Graph 资源管理器。 以 应用程序管理员 角色的用户或允许在租户中创建和管理应用程序的用户身份登录。
  • 用于对应用进行身份验证的已签名证书。 本文使用自签名证书进行演示。 若要了解如何创建自签名证书，请参阅 创建自签名公共证书对应用程序进行身份验证。

警告

强烈建议使用证书，而不使用机密;但是，我们不建议使用自签名证书。 由于各种因素（例如，使用过时的哈希和密码套件或缺少验证），它们可能会减少应用程序的安全栏。 建议从已知的受信任证书颁发机构购买证书。

步骤 1：阅读证书详细信息

若要使用 Microsoft Graph 以编程方式添加证书，需要证书的密钥。 可以选择添加证书的指纹。

[可选]获取证书指纹

可以选择将证书指纹添加到请求有效负载。 如果要添加指纹，可以运行以下 PowerShell 请求来读取证书的指纹。 此请求假定你已生成证书并将其导出到本地驱动器。

请求

## Replace the file path with the source of your certificate

Get-PfxCertificate -Filepath "C:\Users\admin\Desktop\20230112.cer" | Out-File -FilePath "C:\Users\admin\Desktop\20230112.cer.thumbprint.txt"

响应

保存在 .txt 文件中的输出可能类似于以下内容。

Thumbprint                                Subject
----------                                -------
5A126608ED1A1366F714A4A62B7015F3262840F1  CN=20230112

获取证书密钥

若要使用 PowerShell 读取证书的密钥，请运行以下请求。

请求

PowerShell < 6：

## Replace the file path with the location of your certificate

[convert]::ToBase64String((Get-Content C:\Users\admin\Desktop\20230112.cer -Encoding byte)) | Out-File -FilePath "C:\Users\admin\Desktop\20230112.key.txt"

PowerShell >= 6：

## Replace the file path with the location of your certificate

[convert]::ToBase64String((Get-Content C:\Users\admin\Desktop\20230112.cer -AsByteStream))  | Out-File -FilePath "C:\Users\admin\Desktop\20230112.key.txt"

响应

保存在 .txt 文件中的输出可能类似于以下内容。

注意： 为了提高可读性，此处显示的键已缩短。

MIIDADCCAeigAwIBAgIQP6HEGDdZ65xJTcK4dCBvZzANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExMjAeFw0yMzAxMTIwODExNTZaFw0yNDAxMTIwODMxNTZaMBMxETAPBgNVBAMMCDIwMjMwMTEyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAseKf1weEacJ67D6/...dG+7WMIBsIUy0xz6MmyvfSohz3oNP4jHt7pJ9TyxnvDlaxQPUbuIL+DaXVkKRm1V3GgIpKTBqMzTf4tCpy7rpUZbhcwAFw6h9A==

步骤 2：使用 Microsoft Graph 添加证书详细信息

请求

以下请求将证书详细信息添加到应用。 设置如下：

  • startDateTime 是证书创建日期或之后的日期。
  • endDateTime 可以从 startDateTime 开始最多 1 年。 如果未指定，系统会在 startDateTime 1 年后自动分配日期。
  • 类型和用法必须AsymmetricX509Cert分别为 和 Verify 。
  • 将证书使用者名称分配给 displayName 属性。
  • 键是在上一步中生成的 Base64 编码值。

注意

如果应用具有要继续使用进行身份验证的现有有效证书，请在应用的 keyCredentials 对象中包含当前证书详细信息和新证书详细信息。 由于此修补程序调用，该调用通过协议将 属性的内容替换为新值，仅包括新证书会将现有证书替换为新证书。

以下示例添加新证书并替换任何现有证书。

注意： 为了提高可读性，此处显示的键已缩短。

PATCH https://graph.microsoft.com/v1.0/applications/bb77f42f-dacb-4ece-b3e6-285e63c24d52
Content-type: application/json

{
    "keyCredentials": [
        {
            "endDateTime": "2024-01-11T15:31:26Z",
            "startDateTime": "2023-01-12T15:31:26Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "base64MIIDADCCAeigAwIBAgIQP6HEGDdZ65xJTcK4dCBvZzANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExMjAeFw0yMzAxMTIwODExNTZaFw0yNDAxMTIwODMxNTZaMBMxETAPBgNVBAMMCDIwMjMwMTEyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAseKf1weEacJ67D6/...laxQPUbuIL+DaXVkKRm1V3GgIpKTBqMzTf4tCpy7rpUZbhcwAFw6h9A==",
            "displayName": "CN=20230112"
        }
    ]
}

以下示例添加新证书，但不替换由指纹 52ED9B5038A47B9E2E2190715CC238359D4F8F73标识的现有证书。

注意： 为了提高可读性，此处显示的键已缩短。

PATCH https://graph.microsoft.com/v1.0/applications/bb77f42f-dacb-4ece-b3e6-285e63c24d52
Content-type: application/json

{
    "keyCredentials": [
        {
            "endDateTime": "2024-01-11T15:31:26Z",
            "startDateTime": "2023-01-12T09:31:26Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "base64MIIDADCCAeigAwIBAgIQejfrj3S974xI//npv7hFHTANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExNDAeFw0yMzAxMTIwOTA4NThaFw0yNDAxMTIwOTI4NThaMBMxETAPBgNVBAMMCDIwMjMwMTE0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt5vEj6j1l5wOVHR4eDGe77HWslaIVJ1NqxrXPm/...+R+U7sboj+kUvmFzXI+Ge73Liu8egL2NzOHHpO43calWgq36a9YW1yhBQR1ioEchu6jmudW3rF6ktmVqQ==",
            "displayName": "CN=20230114"
        },
        {
            "customKeyIdentifier": "52ED9B5038A47B9E2E2190715CC238359D4F8F73",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "base64MIIDADCCAeigAwIBAgIQfoIvchhpToxKEPI4iMrU1TANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExMzAeFw0yMzAxMTIwODI3NTJaFw0yNDAxMTIwODQ3NTJaMBMxETAPBgNVBAMMCDIwMjMwMTEzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+iqg1nMjYmFcFJh/.../S5X6qoEOyJBgtfpSBANWAdA==",
            "displayName": "CN=20230113"
        }
    ]
}

响应

HTTP/1.1 204 No Content

步骤 3：测试仅限应用的身份验证

可以使用 Microsoft Graph PowerShell 测试仅限应用的身份验证，如以下示例所示。

请求

## Authenticate using the certificate thumbprint
Connect-MgGraph -ClientID cf34b10f-50fd-4167-acf6-4f08ddd4561b -TenantId 38d49456-54d4-455d-a8d6-c383c71e0a6d -CertificateThumbprint 52ED9B5038A47B9E2E2190715CC238359D4F8F73

## Authenticate using the certificate subject name
Connect-MgGraph -ClientID 588028ea-22c2-490e-8c6b-80cd06985e8c -TenantId 38d49456-54d4-455d-a8d6-c383c71e0a6d -CertificateName CN=20230113

响应

Welcome To Microsoft Graph!

若要确认在没有登录用户的情况下运行 Microsoft Graph PowerShell 会话，请运行以下请求。

Get-MgContext

响应如下所示。



ClientId              : cf34b10f-50fd-4167-acf6-4f08ddd4561b
TenantId              : 38d49456-54d4-455d-a8d6-c383c71e0a6d
CertificateThumbprint :
Scopes                :
AuthType              : AppOnly
AuthProviderType      : ClientCredentialProvider
CertificateName       : CN=20230113
Account               :
AppName               : testApp
ContextScope          : Process
Certificate           :
PSHostVersion         : 5.1.22621.963
ClientTimeout         : 00:05:00

总结

你已使用 Microsoft Graph 更新应用对象的证书凭据。 此过程是使用 Microsoft Entra 管理中心 的编程替代方法。 还可以通过遵循类似的过程并调用终结点来更新服务主体的 https://graph.microsoft.com/v1.0/servicePrincipals/ 证书凭据。