使用 API 将 SCEP 的第三方 CA 添加到 IntuneUse APIs to add third-party CAs for SCEP to Intune

在 Microsoft Intune 中,可以添加第三方证书颁发机构 (CA),然后让这些 CA 使用简单证书注册协议 (SCEP) 颁发和验证证书。In Microsoft Intune, you can add third-party certificate authorities (CA), and have these CAs issue and validate certificates using the Simple Certificate Enrollment Protocol (SCEP). 添加第三方证书颁发机构概述了此功能并描述了 Intune 中的管理员任务。Add third-party certification authority provides an overview of this feature, and describes the Administrator tasks in Intune.

还有一些开发人员任务使用 Microsoft 在 GitHub.com 上发布的开源代码库。There are also some developer tasks that use an open-source library that Microsoft published in GitHub.com. 该库包含的 API 会执行以下操作:The library includes an API that:

  • 验证 Intune 动态生成的 SCEP 密码Validates the SCEP password dynamically generated by Intune
  • 通知 Intune 在提交 SCEP 请求的设备上创建的证书Notifies Intune of the certificates created on devices submitting SCEP requests

使用此 API,你的第三方 SCEP 服务器可与适用于 MDM 设备的 Intune SCEP 管理解决方案集成。Using this API, your third-party SCEP server integrates with the Intune SCEP management solution for MDM devices. 该库会从其用户中提取诸如身份验证、服务位置和 ODATA Intune 服务 API 等方面的信息。The library abstracts aspects such as authentication, service location, and the ODATA Intune Service API from its users.

SCEP 管理解决方案SCEP management solution

第三方认证机构 SCEP 与 Microsoft Intune 集成的方式

使用 Intune,管理员可以创建 SCEP 配置文件,然后将这些配置文件分配给 MDM 设备。Using Intune, administrators create SCEP profiles, and then assign these profiles to MDM devices. SCEP 配置文件包括参数,例如:The SCEP profiles include parameters, such as:

  • SCEP 服务器的 URLThe URL of the SCEP server
  • 证书颁发机构的受信任的根证书The Trusted Root Certificate of the Certificate Authority
  • 证书属性等Certificate attributes, and more

使用 Intune 签入的设备分配有 SCEP 配置文件,并配置了这些参数。Devices that check-in with Intune are assigned the SCEP profile, and are configured with these parameters. Intune 创建动态生成的 SCEP 质询密码,然后将其分配给设备。A dynamically-generated SCEP challenge password is created by Intune, and then assigned to the device.

此质询包含:This challenge contains:

  • 动态生成的质询密码The dynamically-generated challenge password
  • 有关设备向 SCEP 服务器发出的证书签名请求 (CSR) 中预期参数的详细信息The details on the parameters expected in the certificate signing request (CSR) that the device issues to the SCEP server
  • 质询到期时间The challenge expiration time

Intune 会加密此信息,对加密的 blob 进行签名,然后将这些详细信息打包到 SCEP 质询密码中。Intune encrypts this information, signs the encrypted blob, and then packages these details into the SCEP challenge password.

设备联系 SCEP 服务器以请求证书,然后提供此 SCEP 质询密码。Devices contacting the SCEP server to request a certificate then give this SCEP challenge password. SCEP 服务器将 CSR 和加密的 SCEP 质询密码发送到 Intune 以进行验证。The SCEP server sends the CSR and encrypted SCEP challenge password to Intune for validation. 只有在质询密码和 CSR 通过验证后,SCEP 服务器才能向设备颁发证书。This challenge password and CSR must pass validation for the SCEP server to issue a certificate to the device. 进行 SCEP 质询验证时,会进行以下检查:When an SCEP challenge is validated, the following checks happen:

  • 验证加密 blob 的签名Validates the signature of the encrypted blob
  • 验证质询是否未过期Validates that the challenge hasn't expired
  • 验证配置文件是否仍然针对设备Validates that the profile is still targeted to the device
  • 验证 CSR 中设备请求的证书属性是否与预期值匹配Validates that the certificate properties requested by the device in the CSR match the expected values

SCEP 管理解决方案还包括报告。The SCEP management solution also includes reporting. 管理员可以获取有关 SCEP 配置文件的部署状态以及颁发给设备的证书的信息。An administrator can get information on the deployment status of the SCEP profile, and about the certificates issued to the devices.

与 Intune 集成Integrate with Intune

Microsoft/Intune-Resource-Access GitHub 存储库中可以下载与 Intune SCEP 集成的库代码。The code for the library to integrate with the Intune SCEP is available for download in the Microsoft/Intune-Resource-Access GitHub repository.

将库集成到产品中包括以下步骤。Integrating the library into your products includes the following steps. 这些步骤需要有关使用 GitHub 存储库以及在 Visual Studio 中创建解决方案和项目的知识。These steps require knowledge on working with GitHub repositories, and creating solutions and projects in Visual Studio.

  1. 注册以接收来自存储库的通知Register to receive notifications from the repository

  2. 克隆或下载存储库Clone or download the repository

  3. 转到 \src\CsrValidation 文件夹下所需的库实现 (https://github.com/Microsoft/Intune-Resource-Access/tree/develop/src/CsrValidation)Go to the library implementation you need under the \src\CsrValidation folder (https://github.com/Microsoft/Intune-Resource-Access/tree/develop/src/CsrValidation)

  4. 使用 README 文件中的说明构建库Build the library using the instructions in the README file

  5. 在构建 SCEP 服务器的项目中包含库Include the library in the project that builds your SCEP server

  6. 在 SCEP 服务器上完成以下任务:Complete the following tasks on the SCEP Server:

    • 允许管理员配置库进行身份验证所使用的 Azure 应用程序标识符、Azure 应用程序密钥和租户 ID(在本文中)。Allow the admin to configure the Azure Application Identifier, Azure Application Key, and Tenant ID (in this article) that the library uses for authentication. 应允许管理员更新 Azure 应用程序密钥。Administrators should be allowed to update the Azure Application Key.
    • 识别包含 Intune 生成的 SCEP 密码的 SCEP 请求Identify SCEP requests that include an Intune-generated SCEP password
    • 使用“验证请求 API”库验证 Intune 生成的 SCEP 密码Use the Validate Request API library to validate Intune-generated SCEP passwords
    • 使用库通知 API 通知 Intune 已针对具有 Intune 生成的 SCEP 密码的 SCEP 请求发出的证书。Use the library notification APIs to notify Intune about certificates issued for SCEP requests that have the Intune-generated SCEP passwords. 还要通知 Intune 在处理这些 SCEP 请求时可能会发生的错误。Also notify Intune about errors that can occur when processing these SCEP requests.
    • 确认服务器记录了足够的信息以帮助管理员排查问题Confirm that the server logs enough information to help admins troubleshoot issues
  7. 完成集成测试(在本文中),并解决任何问题Complete integration testing (in this article), and address any issues

  8. 向客户提供书面指南,说明:Give written guidance to the customer that explains:

    • SCEP 服务器需要如何载入 Azure 门户How the SCEP Server needs to be onboarded in the Azure portal
    • 如何获取配置库所需的 Azure 应用程序标识符和 Azure 应用程序密钥How to get the Azure Application Identifier and Azure Application Key needed to configure the library

在 Azure 中载入 SCEP 服务器Onboard SCEP server in Azure

要对 Intune 进行身份验证,SCEP 服务器需要 Azure 应用程序 ID、Azure 应用程序密钥和租户 ID。To authenticate to Intune, the SCEP server requires an Azure Application ID, an Azure Application Key, and a Tenant ID. SCEP 服务器还需要有权访问 Intune API。The SCEP Server also needs authorized to access the Intune API.

要获取此数据,SCEP 服务器管理员需登录到 Azure 门户,注册应用程序,为应用程序授予 Microsoft Intune API\SCEP 质询验证权限,为应用程序创建密钥,然后下载应用程序 ID、其密钥和租户 ID 。To get this data, the SCEP server administrator signs in to the Azure portal, registers the application, gives the application the Microsoft Intune API\SCEP challenge validation permission, creates a key for the application, and then downloads the application ID, its key, and the tenant ID.

有关注册应用程序以及获取 ID 和密钥的指导,请参阅使用门户创建 AAD 应用程序和服务主体以访问资源For guidance on registering an application, and getting the IDs and keys, see Use portal to create an AAD application and service principal to access resources.

Java 库 APIJava Library API

Java 库是作为 Maven 项目实现的,该项目在构建时会拉入其依赖项。The Java library is implemented as a Maven project that pulls in its dependencies when it's built. API 在 com.microsoft.intune.scepvalidation 命名空间下由 IntuneScepServiceClient 类实现。The API is implemented under the com.microsoft.intune.scepvalidation namespace by the IntuneScepServiceClient class.

IntuneScepServiceClient 类IntuneScepServiceClient class

IntuneScepServiceClient 类包括 SCEP 服务用来验证 SCEP 密码、通知 Intune 已创建的证书以及列出任何错误的方法。The IntuneScepServiceClient class includes the methods used by the SCEP service to validate SCEP passwords, to notify Intune about certificates that are created, and to list any errors.

IntuneScepServiceClient 构造函数IntuneScepServiceClient constructor

签名Signature:

IntuneScepServiceClient(
    Properties configProperties)

描述Description:

实例化和配置 IntuneScepServiceClient 对象。Instantiates and configures an IntuneScepServiceClient object.

参数Parameters:

  • configProperties - 包含客户端配置文件信息的属性对象configProperties - Properties object containing client configuration information

配置必须包含以下属性:The configuration must include following properties:

  • AAD_APP_ID=“在载入过程中获得的 Azure 应用程序 ID”AAD_APP_ID="The Azure Application Id obtained during the onboarding process"
  • AAD_APP_KEY=“在载入过程中获得的 Azure 应用程序密钥”AAD_APP_KEY="The Azure Application Key obtained during the onboarding process"
  • TENANT=“在载入过程中获得的租户 ID”TENANT="The Tenant Id obtained during the onboarding process"
  • PROVIDER_NAME_AND_VERSION=“用于标识产品及其版本的信息”PROVIDER_NAME_AND_VERSION="Information used to identify your product and its version"

如果解决方案需要具有身份验证或无身份验证的代理,则可以添加以下属性:If your solution requires a proxy either with authentication or without authentication, then you can add the following properties:

  • PROXY_HOST =“托管代理的主机。”PROXY_HOST="The host the proxy is hosted on."
  • PROXY_PORT =“代理侦听的端口。”PROXY_PORT="The port the proxy is listening on."
  • PROXY_USER =“代理使用基本身份验证时所用的用户名。”PROXY_USER="The username to use if proxy uses basic authentication."
  • PROXY_PASS =“代理使用基本身份验证时所用的密码。”PROXY_PASS="The password to use if proxy uses basic authentication."

引发Throws:

  • IllegalArgumentException - 在没有适当属性对象的情况下执行构造函数时引发。IllegalArgumentException - Thrown if the constructor is executed without a proper property object.

重要

最好实例化此类的实例,并使用它来处理多个 SCEP 请求。It's best to instantiate an instance of this class, and use it to process multiple SCEP requests. 这样做可以减少开销,因为它可以缓存身份验证令牌和服务位置信息。Doing so reduces overhead, as it caches authentication tokens and service location information.

安全说明Security notes
SCEP 服务器实施者必须保护永久保存到存储空间的配置属性中输入的数据,防止篡改和泄露。The SCEP server implementer must protect the data entered in the configuration properties persisted to storage against tampering and disclosure. 建议使用适当的 ACL 和加密来保护信息。It's recommended to use proper ACLs and encryption to secure the information.

ValidateRequest 方法ValidateRequest method

签名Signature:

void ValidateRequest(
    String transactionId,
    String certificateRequest)

描述Description:

验证 SCEP 证书请求。Validates a SCEP certificate request.

参数Parameters:

  • transactionId - SCEP 事务 IDtransactionId - The SCEP Transaction ID
  • certificateRequest - 采用 DER 编码的 PKCS #10 证书请求,该请求通过 Base64 编码成为字符串certificateRequest - DER-encoded PKCS #10 Certificate Request Base64 encoded as a string

引发Throws:

  • IllegalArgumentException - 使用无效参数进行调用时引发IllegalArgumentException - Thrown if called with a parameter that is not valid
  • IntuneScepServiceException - 发现证书请求无效时引发IntuneScepServiceException - Thrown if it is found that the certificate request is not valid
  • Exception - 遇到意外错误时引发Exception - Thrown if an un-expected error is encountered

重要

服务器应记录此方法引发的异常。Exceptions thrown by this method should be logged by the server. 请注意,IntuneScepServiceException 属性具有证书请求验证失败的原因的详细信息。Note that the IntuneScepServiceException properties have detailed information on why the certificate request validation failed.

安全说明Security notes:

  • 如果此方法引发异常,则 SCEP 服务器不得向客户端颁发证书 。If this method throws an exception, the SCEP server must not issue a certificate to the client.
  • SCEP 证书请求验证失败可能表示 Intune 基础结构中存在问题。SCEP certificate request validation failures may indicate a problem in the Intune infrastructure. 或者,他们可以表示攻击者正在尝试获取证书。Or, they could indicate that an attacker is trying to get a certificate.
SendSuccessNotification 方法SendSuccessNotification method

签名Signature:

void SendSuccessNotification(
    String transactionId,
    String certificateRequest,
    String certThumbprint,
    String certSerialNumber,
    String certExpirationDate,
    String certIssuingAuthority)

描述Description:

通知 Intune 在处理 SCEP 请求时创建了一个证书。Notifies Intune that a certificate is created as part of processing a SCEP request.

参数Parameters:

  • transactionId - SCEP 事务 IDtransactionId - The SCEP Transaction ID
  • certificateRequest - 采用 DER 编码的 PKCS #10 证书请求,该请求通过 Base64 编码成为字符串certificateRequest - DER-encoded PKCS #10 Certificate Request Base64 encoded as a string
  • certThumprint - 预配证书的指纹的 SHA1 哈希certThumprint - SHA1 hash of the thumbprint of the provisioned certificate
  • certSerialNumber - 预配证书的序列号certSerialNumber - Serial number of the provisioned certificate
  • certExpirationDate - 预配证书的到期日期。certExpirationDate - Expiration date of the provisioned certificate. 日期时间字符串应采取的格式为 Web UTC 时间 (YYYY-MM-DDThh:mm:ss.sssTZD) ISO 8601。The date time string should be formatted as web UTC time (YYYY-MM-DDThh:mm:ss.sssTZD) ISO 8601.
  • certIssuingAuthority - 颁发证书的机构名称certIssuingAuthority - Name of the authority that issued the certificate

引发Throws:

  • IllegalArgumentException - 使用无效参数进行调用时引发IllegalArgumentException - Thrown if called with a parameter that is not valid
  • IntuneScepServiceException - 发现证书请求无效时引发IntuneScepServiceException - Thrown if it is found that the certificate request is not valid
  • Exception - 遇到意外错误时引发Exception - Thrown if an un-expected error is encountered

重要

服务器应记录此方法引发的异常。Exceptions thrown by this method should be logged by the server. 请注意,IntuneScepServiceException 属性具有证书请求验证失败的原因的详细信息。Note that the IntuneScepServiceException properties have detailed information on why the certificate request validation failed.

安全说明Security notes:

  • 如果此方法引发异常,则 SCEP 服务器不得向客户端颁发证书 。If this method throws an exception, the SCEP server must not issue a certificate to the client.
  • SCEP 证书请求验证失败可能表示 Intune 基础结构中存在问题。SCEP certificate request validation failures may indicate a problem in the Intune infrastructure. 或者,他们可以表示攻击者正在尝试获取证书。Or, they could indicate that an attacker is trying to get a certificate.
SendFailureNotification 方法SendFailureNotification method

签名Signature:

void SendFailureNotification(
    String transactionId,
    String certificateRequest,
    long  hResult,
    String errorDescription)

描述Description:

通知 Intune 在处理 SCEP 请求时出现错误。Notifies Intune that an error occurred while processing a SCEP request. 不应对此类的方法引发的异常调用此方法。This method shouldn't be invoked for exceptions thrown by the methods of this class.

参数Parameters:

  • transactionId - SCEP 事务 IDtransactionId - The SCEP Transaction ID
  • certificateRequest - 采用 DER 编码的 PKCS #10 证书请求,该请求通过 Base64 编码成为字符串certificateRequest - DER-encoded PKCS #10 Certificate Request Base64 encoded as a string
  • hResult - 最能说明遇到的错误的 Win32 错误代码。hResult - Win32 error code that best describes the error that was encountered. 请参阅 Win32 错误代码See Win32 Error Codes
  • errorDescription - 遇到的错误的描述errorDescription - Description of the error encountered

引发Throws:

  • IllegalArgumentException - 使用无效参数进行调用时引发IllegalArgumentException - Thrown if called with a parameter that is not valid
  • IntuneScepServiceException - 发现证书请求无效时引发IntuneScepServiceException - Thrown if it is found that the certificate request is not valid
  • Exception - 遇到意外错误时引发Exception - Thrown if an un-expected error is encountered

重要

服务器应记录此方法引发的异常。Exceptions thrown by this method should be logged by the server. 请注意,IntuneScepServiceException 属性具有证书请求验证失败的原因的详细信息。Note that the IntuneScepServiceException properties have detailed information on why the certificate request validation failed.

安全说明Security notes:

  • 如果此方法引发异常,则 SCEP 服务器不得向客户端颁发证书 。If this method throws an exception, the SCEP server must not issue a certificate to the client.
  • SCEP 证书请求验证失败可能表示 Intune 基础结构中存在问题。SCEP certificate request validation failures may indicate a problem in the Intune infrastructure. 或者,他们可以表示攻击者正在尝试获取证书。Or, they could indicate that an attacker is trying to get a certificate.
SetSslSocketFactory 方法SetSslSocketFactory method

签名Signature:

void SetSslSocketFactory(
    SSLSocketFactory factory)

描述Description:

使用此方法通知客户端,在与 Intune 通信时必须使用指定的(而非默认的)SSL 套接字工厂。Use this method to inform the client that it must use the specified SSL socket factory (instead of the default) when communicating with Intune.

参数Parameters:

  • factory - 客户端应该用于 HTTPS 请求的 SSL 套接字工厂factory - The SSL socket factory that the client should use for HTTPS requests

引发Throws:

  • IllegalArgumentException - 使用无效参数进行调用时引发IllegalArgumentException - Thrown if called with a parameter that is not valid

备注

在执行此类的其他方法之前,必须设置 SSL 套接字工厂(如果需要)。The SSL Socket factory must be set if required prior to executing the other methods of this class.

集成测试Integration testing

必须验证并测试解决方案是否与 Intune 正确集成。Validating and testing that your solution is properly integrated with Intune is a must. 以下列出了步骤概述:The following lists an overview of the steps:

  1. 设置 Intune 试用帐户Set up an Intune trial account.
  2. 将 SCEP 服务器载入 Azure 门户(在本文中)。Onboard the SCEP Server in the Azure portal (in this article).
  3. 使用在载入 SCEP 服务器时创建的 ID 和密钥配置 SCEP 服务器Configure the SCEP Server with the IDs and key created when onboarding your SCEP server.
  4. 注册设备以测试方案测试矩阵中的方案。Enroll devices to test the scenarios in the scenario testing matrix.
  5. 为测试证书颁发机构创建受信任的根证书配置文件Create a Trusted Root Certificate profile for your test Certificate Authority.
  6. 创建 SCEP 配置文件以测试方案测试矩阵中列出的方案。Create SCEP profiles to test the scenarios listed in the scenario testing matrix.
  7. 向已注册其设备的用户分配配置文件Assign the profiles to users that enrolled their devices.
  8. 等待设备与 Intune 同步。Wait for the devices to sync with Intune. 或者,手动同步设备Or, manually sync the devices.
  9. 确认将受信任的根证书和 SCEP 配置文件部署到设备Confirm the Trusted Root Certificate and SCEP profiles are deployed to the devices.
  10. 确认所有设备上都安装了受信任的根证书。Confirm the Trusted Root Certificate are installed on all the devices.
  11. 确认所有设备上都已安装分配的配置文件的 SCEP 证书。Confirm the SCEP Certificates for the assigned profiles are installed on all the devices.
  12. 确认已安装证书的属性与 SCEP 配置文件中设置的属性相匹配。Confirm the properties of the installed certificates match the properties set in the SCEP profile.
  13. 确认在 Intune 控制台中正确列出了已颁发的证书Confirm the issued certificates are properly listed in the Intune console

另请参阅See also