使用 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. 動態產生的 SCEP 挑戰密碼是由 Intune 所建立,然後指派給裝置。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

與 Intune SCEP 整合的程式庫程式碼可供下載,其位於 Microsoft/Intune-Resource-Acess GitHub 存放庫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. 使用讀我檔案中的指示建置程式庫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 應用程式金鑰和租用戶識別碼 (在本文中)。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

將 SCEP 伺服器在 Azure 上架Onboard SCEP server in Azure

若要向 Intune 驗證,SCEP 伺服器需要 Azure 應用程式識別碼、Azure 應用程式金鑰和租用戶識別碼。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 挑戰驗證權限、建立應用程式金鑰,然後下載應用程式識別碼、其金鑰及租用戶識別碼。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.

如需註冊應用程式並取得識別碼和金鑰的指引,請參閱使用入口網站來建立 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 由 IntuneScepServiceClient 類別實作在 com.microsoft.intune.scepvalidation 命名空間下。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 應用程式識別碼"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="在上架程序中取得的租用戶識別碼"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"

如果您的解決方案需要 Proxy (可搭配或不搭配驗證使用),則您可以新增下列屬性:If your solution requires a proxy either with authentication or without authentication, then you can add the following properties:

  • PROXY_HOST="裝載 Proxy 的主機。"PROXY_HOST="The host the proxy is hosted on."
  • PROXY_PORT="Proxy 正在接聽的連接埠。"PROXY_PORT="The port the proxy is listening on."
  • PROXY_USER="Proxy 使用基本驗證時要使用的使用者名稱。"PROXY_USER="The username to use if proxy uses basic authentication."
  • PROXY_PASS="Proxy 使用基本驗證時要使用的密碼。"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 交易識別碼transactionId - 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 交易識別碼transactionId - 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 交易識別碼transactionId - 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 通訊端 Factory (而不是預設值)。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 通訊端 Factory。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. 在 Azure 入口網站中將 SCEP 伺服器上架 (在本文中)。Onboard the SCEP Server in the Azure portal (in this article).
  3. 使用上架 SCEP 伺服器時建立的識別碼和金鑰,設定 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