Utiliser des API pour ajouter des autorités de certification tierces pour SCEP à IntuneUse APIs to add third-party CAs for SCEP to Intune

Dans Microsoft Intune, vous pouvez ajouter des autorités de certification tierces et faire en sorte qu’elles émettent et valident des certificats à l’aide du protocole SCEP (Simple Certificate Enrollment Protocol).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). Ajouter une autorité de certification tierce fournit une vue d’ensemble de cette fonctionnalité et décrit les tâches d’administration dans Intune.Add third-party certification authority provides an overview of this feature, and describes the Administrator tasks in Intune.

Certaines tâches de développement utilisent également une bibliothèque open source publiée par Microsoft sur GitHub.com.There are also some developer tasks that use an open-source library that Microsoft published in GitHub.com. La bibliothèque inclut une API qui :The library includes an API that:

  • Valide le mot de passe SCEP généré de manière dynamique par Intune.Validates the SCEP password dynamically generated by Intune
  • Informe Intune des certificats créés sur les appareils soumettant des requêtes SCEP.Notifies Intune of the certificates created on devices submitting SCEP requests

À l’aide de cette API, votre serveur SCEP tiers s’intègre avec la solution de gestion SCEP Intune pour les appareils MDM.Using this API, your third-party SCEP server integrates with the Intune SCEP management solution for MDM devices. La bibliothèque offre une abstraction d’aspects tels que l’authentification, l’emplacement du service et l’API de service ODATA Intune par rapport à ses utilisateurs.The library abstracts aspects such as authentication, service location, and the ODATA Intune Service API from its users.

Solution de gestion SCEPSCEP management solution

Intégration d’une autorité de certification tierce SCEP avec Microsoft Intune

À l’aide d’Intune, les administrateurs créent des profils SCEP, puis affectent ces profils à des appareils MDM.Using Intune, administrators create SCEP profiles, and then assign these profiles to MDM devices. Les profils SCEP incluent des paramètres tels que :The SCEP profiles include parameters, such as:

  • L’URL du serveur SCEPThe URL of the SCEP server
  • Le certificat racine approuvé de l’autorité de certificationThe Trusted Root Certificate of the Certificate Authority
  • Les attributs de certificats, et bien plus encoreCertificate attributes, and more

Le profil SCEP est affecté aux appareils inscrits auprès d’Intune, et ceux-ci sont configurés avec ces paramètres.Devices that check-in with Intune are assigned the SCEP profile, and are configured with these parameters. Un mot de passe de stimulation SCEP généré de manière dynamique est créé par Intune, puis affecté à l’appareil.A dynamically-generated SCEP challenge password is created by Intune, and then assigned to the device.

Cette stimulation contient :This challenge contains:

  • le mot de passe de stimulation généré de manière dynamique ;The dynamically-generated challenge password
  • les détails sur les paramètres attendus dans la demande de signature de certificat envoyée par l’appareil au serveur SCEP ;The details on the parameters expected in the certificate signing request (CSR) that the device issues to the SCEP server
  • l’heure d’expiration de la stimulation.The challenge expiration time

Intune chiffre ces informations, signe l’objet blob chiffré, puis empaquète ces détails dans le mot de passe de stimulation SCEP.Intune encrypts this information, signs the encrypted blob, and then packages these details into the SCEP challenge password.

Les appareils contactant le serveur SCEP pour demander un certificat donnent ensuite ce mot de passe de stimulation SCEP.Devices contacting the SCEP server to request a certificate then give this SCEP challenge password. Le serveur SCEP envoie la demande de signature de certificat et le mot de passe de stimulation SCEP chiffré à Intune pour validation.The SCEP server sends the CSR and encrypted SCEP challenge password to Intune for validation. Ce mot de passe de stimulation et la demande de signature de certificat doivent réussir la phase de validation afin que le serveur SCEP émette un certificat pour l’appareil.This challenge password and CSR must pass validation for the SCEP server to issue a certificate to the device. Quand une stimulation SCEP est validée, les vérifications suivantes se produisent :When an SCEP challenge is validated, the following checks happen:

  • Validation de la signature de l’objet blob chiffréValidates the signature of the encrypted blob
  • Validation du fait que la demande n’a pas expiréValidates that the challenge hasn't expired
  • Validation du fait que le profil cible toujours l’appareilValidates that the profile is still targeted to the device
  • Validation du fait que les propriétés de certificat demandées par l’appareil dans la demande de signature de certificat correspondent aux valeurs attenduesValidates that the certificate properties requested by the device in the CSR match the expected values

La solution de gestion SCEP comprend également des rapports.The SCEP management solution also includes reporting. Un administrateur peut obtenir des informations sur l’état du déploiement du profil SCEP, ainsi que sur les certificats délivrés aux appareils.An administrator can get information on the deployment status of the SCEP profile, and about the certificates issued to the devices.

Intégrer à IntuneIntegrate with Intune

Le code d’intégration de la bibliothèque avec le protocole SCEP Intune peut être téléchargé à partir du dépôt GitHub Microsoft/Intune-Resource-Access.The code for the library to integrate with the Intune SCEP is available for download in the Microsoft/Intune-Resource-Access GitHub repository.

L’intégration de la bibliothèque dans vos produits nécessite les étapes suivantes.Integrating the library into your products includes the following steps. Pour effectuer ces étapes, vous devez savoir comment utiliser des dépôts GitHub et comment créer des solutions et des projets dans Visual Studio.These steps require knowledge on working with GitHub repositories, and creating solutions and projects in Visual Studio.

  1. Inscrivez-vous pour recevoir des notifications du dépôt.Register to receive notifications from the repository

  2. Clonez ou téléchargez le dépôt.Clone or download the repository

  3. Accédez à l’implémentation de la bibliothèque dont vous avez besoin sous le dossier \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. Générez la bibliothèque en suivant les instructions fournies dans le fichier Lisez-moi.Build the library using the instructions in the README file

  5. Incluez la bibliothèque dans le projet qui génère votre serveur SCEP.Include the library in the project that builds your SCEP server

  6. Effectuez les tâches suivantes sur le serveur SCEP :Complete the following tasks on the SCEP Server:

    • Autorisez l’administrateur à configurer l’identificateur d’application Azure, la clé d’application Azure et l’ID de locataire (dans cet article) utilisés par la bibliothèque pour l’authentification.Allow the admin to configure the Azure Application Identifier, Azure Application Key, and Tenant ID (in this article) that the library uses for authentication. Les administrateurs doivent être autorisés à mettre à jour la clé d’application Azure.Administrators should be allowed to update the Azure Application Key.
    • Identifiez les requêtes SCEP qui comprennent un mot de passe SCEP généré par Intune.Identify SCEP requests that include an Intune-generated SCEP password
    • Utilisez la bibliothèque d’API Valider la requête pour valider les mots de passe SCEP générés par Intune.Use the Validate Request API library to validate Intune-generated SCEP passwords
    • Utilisez les API de notification de la bibliothèque afin d’informer Intune des certificats émis pour les requêtes SCEP qui contiennent des mots de passe SCEP générés par Intune.Use the library notification APIs to notify Intune about certificates issued for SCEP requests that have the Intune-generated SCEP passwords. Informez également Intune des erreurs qui peuvent se produire lors du traitement de ces requêtes SCEP.Also notify Intune about errors that can occur when processing these SCEP requests.
    • Vérifiez que le serveur enregistre suffisamment d’informations dans le journal pour aider les administrateurs à résoudre les problèmes.Confirm that the server logs enough information to help admins troubleshoot issues
  7. Effectuez les tests d’intégration (dans cet article) et résolvez les éventuels problèmes.Complete integration testing (in this article), and address any issues

  8. Donnez des instructions écrites au client qui expliquent :Give written guidance to the customer that explains:

    • Comment le serveur SCEP doit être intégré dans le portail Azure.How the SCEP Server needs to be onboarded in the Azure portal
    • Comment obtenir l’identificateur d’application Azure et la clé d’application Azure nécessaires pour configurer la bibliothèque.How to get the Azure Application Identifier and Azure Application Key needed to configure the library

Intégrer le serveur SCEP dans AzureOnboard SCEP server in Azure

Pour s’authentifier auprès d’Intune, le serveur SCEP a besoin d’un ID d’application Azure, d’une clé d’application Azure et d’un ID de locataire.To authenticate to Intune, the SCEP server requires an Azure Application ID, an Azure Application Key, and a Tenant ID. Il doit également être autorisé à accéder à l’API Intune.The SCEP Server also needs authorized to access the Intune API.

Pour obtenir ces données, l’administrateur de serveur SCEP se connecte au portail Azure, inscrit l’application, lui donne l’autorisation API Microsoft Intune\Validation de test SCEP, crée une clé pour l’application, puis télécharge l’ID d’application, sa clé et l’ID de locataire.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.

Pour obtenir des instructions sur l’inscription d’une application et l’obtention d’ID et de clés, consultez Utiliser le portail pour créer une application et un principal du service Azure Active Directory pouvant accéder aux ressources.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.

API de bibliothèque JavaJava Library API

La bibliothèque Java est implémentée en tant que projet Maven qui extrait ses dépendances quand il est généré.The Java library is implemented as a Maven project that pulls in its dependencies when it's built. L’API est implémentée sous l’espace de noms com.microsoft.intune.scepvalidation par la classe IntuneScepServiceClient.The API is implemented under the com.microsoft.intune.scepvalidation namespace by the IntuneScepServiceClient class.

Classe IntuneScepServiceClientIntuneScepServiceClient class

La classe IntuneScepServiceClient contient les méthodes utilisées par le service SCEP pour valider les mots de passe SCEP, pour informer Intune des certificats qui sont créés, et pour répertorier les erreurs éventuelles.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.

Constructeur IntuneScepServiceClientIntuneScepServiceClient constructor

Signature :Signature:

IntuneScepServiceClient(
    Properties configProperties)

Description :Description:

Instancie et configure un objet IntuneScepServiceClient.Instantiates and configures an IntuneScepServiceClient object.

Paramètres :Parameters:

  • configProperties : objet de propriétés contenant des informations sur la configuration du clientconfigProperties - Properties object containing client configuration information

La configuration doit inclure les propriétés suivantes :The configuration must include following properties:

  • AAD_APP_ID="ID d’application Azure obtenu pendant le processus d’intégration"AAD_APP_ID="The Azure Application Id obtained during the onboarding process"
  • AAD_APP_KEY="Clé d’application Azure obtenue pendant le processus d’intégration"AAD_APP_KEY="The Azure Application Key obtained during the onboarding process"
  • TENANT="ID de locataire obtenu pendant le processus d’intégration"TENANT="The Tenant Id obtained during the onboarding process"
  • PROVIDER_NAME_AND_VERSION="Informations permettant d’identifier votre produit et sa version"PROVIDER_NAME_AND_VERSION="Information used to identify your product and its version"

Si votre solution nécessite un proxy avec ou sans authentification, vous pouvez ajouter les propriétés suivantes :If your solution requires a proxy either with authentication or without authentication, then you can add the following properties:

  • PROXY_HOST="Hôte d’hébergement du proxy."PROXY_HOST="The host the proxy is hosted on."
  • PROXY_PORT="Port d’écoute du proxy."PROXY_PORT="The port the proxy is listening on."
  • PROXY_USER="Nom d’utilisateur à employer si le proxy utilise l’authentification de base."PROXY_USER="The username to use if proxy uses basic authentication."
  • PROXY_PASS="Mot de passe à employer si le proxy utilise l’authentification de base."PROXY_PASS="The password to use if proxy uses basic authentication."

Lève :Throws:

  • IllegalArgumentException : levée si le constructeur est exécuté sans objet de propriété approprié.IllegalArgumentException - Thrown if the constructor is executed without a proper property object.

Important

Il est préférable d’instancier une instance de cette classe et de l’utiliser pour traiter plusieurs requêtes SCEP.It's best to instantiate an instance of this class, and use it to process multiple SCEP requests. Cela réduit la charge, grâce à la mise en cache des jetons d’authentification et des informations d’emplacement du service.Doing so reduces overhead, as it caches authentication tokens and service location information.

Notes de sécuritéSecurity notes
L’implémenteur du serveur SCEP doit protéger contre la falsification et la divulgation les données entrées dans les propriétés de configuration rendues persistantes dans le stockage.The SCEP server implementer must protect the data entered in the configuration properties persisted to storage against tampering and disclosure. Nous vous recommandons d’utiliser les ACL et le chiffrement appropriés pour sécuriser les informations.It's recommended to use proper ACLs and encryption to secure the information.

Méthode ValidateRequestValidateRequest method

Signature :Signature:

void ValidateRequest(
    String transactionId,
    String certificateRequest)

Description :Description:

Valide une demande de certificat SCEP.Validates a SCEP certificate request.

Paramètres :Parameters:

  • transactionId : l’ID de transaction SCEPtransactionId - The SCEP Transaction ID
  • certificateRequest : demande de certificat PKCS #10 encodée DER, codée en Base64 sous forme de chaînecertificateRequest - DER-encoded PKCS #10 Certificate Request Base64 encoded as a string

Lève :Throws:

  • IllegalArgumentException : levée en cas d’appel avec un paramètre qui n’est pas valideIllegalArgumentException - Thrown if called with a parameter that is not valid
  • IntuneScepServiceException : levée s’il est constaté que la demande de certificat n’est pas valideIntuneScepServiceException - Thrown if it is found that the certificate request is not valid
  • Exception : levée si une erreur non attendue se produitException - Thrown if an un-expected error is encountered

Important

Les exceptions levées par cette méthode doivent être consignées par le serveur.Exceptions thrown by this method should be logged by the server. Notez que les propriétés IntuneScepServiceException ont des informations détaillées sur la cause de l’échec de la validation de demande de certificat.Note that the IntuneScepServiceException properties have detailed information on why the certificate request validation failed.

Notes de sécurité :Security notes:

  • Si cette méthode lève une exception, le serveur SCEP ne doit pas délivrer de certificat au client.If this method throws an exception, the SCEP server must not issue a certificate to the client.
  • Les échecs de validation de demande de certificat SCEP peuvent indiquer un problème dans l’infrastructure Intune.SCEP certificate request validation failures may indicate a problem in the Intune infrastructure. Ils peuvent également signifier qu’une personne malveillante essaie d’obtenir un certificat.Or, they could indicate that an attacker is trying to get a certificate.
Méthode SendSuccessNotificationSendSuccessNotification method

Signature :Signature:

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

Description :Description:

Signale à Intune qu’un certificat est créé dans le cadre du traitement d’une requête SCEP.Notifies Intune that a certificate is created as part of processing a SCEP request.

Paramètres :Parameters:

  • transactionId : l’ID de transaction SCEPtransactionId - The SCEP Transaction ID
  • certificateRequest : demande de certificat PKCS #10 encodée DER, codée en Base64 sous forme de chaînecertificateRequest - DER-encoded PKCS #10 Certificate Request Base64 encoded as a string
  • certThumprint : code de hachage SHA-1 de l’empreinte du certificat provisionnécertThumprint - SHA1 hash of the thumbprint of the provisioned certificate
  • certSerialNumber : numéro de série du certificat provisionnécertSerialNumber - Serial number of the provisioned certificate
  • certExpirationDate : date d’expiration du certificat provisionné.certExpirationDate - Expiration date of the provisioned certificate. La chaîne de date et heure doit être mise en forme en tant qu’heure UTC web (AAAA-MM-JJThh: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 : nom de l’autorité qui a émis le certificatcertIssuingAuthority - Name of the authority that issued the certificate

Lève :Throws:

  • IllegalArgumentException : levée en cas d’appel avec un paramètre qui n’est pas valideIllegalArgumentException - Thrown if called with a parameter that is not valid
  • IntuneScepServiceException : levée s’il est constaté que la demande de certificat n’est pas valideIntuneScepServiceException - Thrown if it is found that the certificate request is not valid
  • Exception : levée si une erreur non attendue se produitException - Thrown if an un-expected error is encountered

Important

Les exceptions levées par cette méthode doivent être consignées par le serveur.Exceptions thrown by this method should be logged by the server. Notez que les propriétés IntuneScepServiceException ont des informations détaillées sur la cause de l’échec de la validation de demande de certificat.Note that the IntuneScepServiceException properties have detailed information on why the certificate request validation failed.

Notes de sécurité :Security notes:

  • Si cette méthode lève une exception, le serveur SCEP ne doit pas délivrer de certificat au client.If this method throws an exception, the SCEP server must not issue a certificate to the client.
  • Les échecs de validation de demande de certificat SCEP peuvent indiquer un problème dans l’infrastructure Intune.SCEP certificate request validation failures may indicate a problem in the Intune infrastructure. Ils peuvent également signifier qu’une personne malveillante essaie d’obtenir un certificat.Or, they could indicate that an attacker is trying to get a certificate.
Méthode SendFailureNotificationSendFailureNotification method

Signature :Signature:

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

Description :Description:

Signale à Intune qu’une erreur s’est produite lors du traitement d’une requête SCEP.Notifies Intune that an error occurred while processing a SCEP request. Cette méthode ne doit pas être appelée pour les exceptions levées par les méthodes de cette classe.This method shouldn't be invoked for exceptions thrown by the methods of this class.

Paramètres :Parameters:

  • transactionId : l’ID de transaction SCEPtransactionId - The SCEP Transaction ID
  • certificateRequest : demande de certificat PKCS #10 encodée DER, codée en Base64 sous forme de chaînecertificateRequest - DER-encoded PKCS #10 Certificate Request Base64 encoded as a string
  • hResult : code d’erreur Win32 décrivant le mieux l’erreur qui s’est produite.hResult - Win32 error code that best describes the error that was encountered. Voir Codes d’erreur Win32See Win32 Error Codes
  • errorDescription : description de l’erreur qui s’est produiteerrorDescription - Description of the error encountered

Lève :Throws:

  • IllegalArgumentException : levée en cas d’appel avec un paramètre qui n’est pas valideIllegalArgumentException - Thrown if called with a parameter that is not valid
  • IntuneScepServiceException : levée s’il est constaté que la demande de certificat n’est pas valideIntuneScepServiceException - Thrown if it is found that the certificate request is not valid
  • Exception : levée si une erreur non attendue se produitException - Thrown if an un-expected error is encountered

Important

Les exceptions levées par cette méthode doivent être consignées par le serveur.Exceptions thrown by this method should be logged by the server. Notez que les propriétés IntuneScepServiceException ont des informations détaillées sur la cause de l’échec de la validation de demande de certificat.Note that the IntuneScepServiceException properties have detailed information on why the certificate request validation failed.

Notes de sécurité :Security notes:

  • Si cette méthode lève une exception, le serveur SCEP ne doit pas délivrer de certificat au client.If this method throws an exception, the SCEP server must not issue a certificate to the client.
  • Les échecs de validation de demande de certificat SCEP peuvent indiquer un problème dans l’infrastructure Intune.SCEP certificate request validation failures may indicate a problem in the Intune infrastructure. Ils peuvent également signifier qu’une personne malveillante essaie d’obtenir un certificat.Or, they could indicate that an attacker is trying to get a certificate.
Méthode SetSslSocketFactorySetSslSocketFactory method

Signature :Signature:

void SetSslSocketFactory(
    SSLSocketFactory factory)

Description :Description:

Utilisez cette méthode pour signaler au client qu’il doit utiliser la fabrique de socket SSL spécifiée (au lieu de la fabrique par défaut) lors des communications avec Intune.Use this method to inform the client that it must use the specified SSL socket factory (instead of the default) when communicating with Intune.

Paramètres :Parameters:

  • factory : fabrique de socket SSL que le client doit utiliser pour les requêtes HTTPSfactory - The SSL socket factory that the client should use for HTTPS requests

Lève :Throws:

  • IllegalArgumentException : levée en cas d’appel avec un paramètre qui n’est pas valideIllegalArgumentException - Thrown if called with a parameter that is not valid

Notes

La fabrique de socket de SSL doit être définie si nécessaire avant d’exécuter les autres méthodes de cette classe.The SSL Socket factory must be set if required prior to executing the other methods of this class.

Tests d’intégrationIntegration testing

Il est indispensable de tester et de valider l’intégration correcte de votre solution à Intune.Validating and testing that your solution is properly integrated with Intune is a must. Vous trouverez ci-dessous une vue d’ensemble des étapes :The following lists an overview of the steps:

  1. Configurer un compte d’évaluation Intune.Set up an Intune trial account.
  2. Intégrer le serveur SCEP dans le portail Azure (dans cet article).Onboard the SCEP Server in the Azure portal (in this article).
  3. Configurer le serveur SCEP avec les ID et la clé créés lors de l’intégration de votre serveur SCEP.Configure the SCEP Server with the IDs and key created when onboarding your SCEP server.
  4. Inscrire des appareils pour tester les scénarios dans la matrice de test de scénario.Enroll devices to test the scenarios in the scenario testing matrix.
  5. Créer un profil de certificat racine approuvé pour votre autorité de certification de test.Create a Trusted Root Certificate profile for your test Certificate Authority.
  6. Créer des profils SCEP pour tester les scénarios répertoriés dans la matrice de test de scénario.Create SCEP profiles to test the scenarios listed in the scenario testing matrix.
  7. Attribuer les profils aux utilisateurs ayant inscrit leurs appareils.Assign the profiles to users that enrolled their devices.
  8. Attendre que les appareils se synchronisent avec Intune.Wait for the devices to sync with Intune. Ou synchroniser manuellement les appareils.Or, manually sync the devices.
  9. Confirmer que le certificat racine approuvé et les profils SCEP sont déployés sur les appareils.Confirm the Trusted Root Certificate and SCEP profiles are deployed to the devices.
  10. Confirmer que le certificat racine approuvé est installé sur tous les appareils.Confirm the Trusted Root Certificate are installed on all the devices.
  11. Confirmer que les certificats SCEP pour les profils affectés sont installés sur tous les appareils.Confirm the SCEP Certificates for the assigned profiles are installed on all the devices.
  12. Confirmer que les propriétés des certificats installés correspondent aux propriétés définies dans le profil SCEP.Confirm the properties of the installed certificates match the properties set in the SCEP profile.
  13. Confirmer que les certificats émis sont correctement répertoriés dans la console IntuneConfirm the issued certificates are properly listed in the Intune console

Voir aussiSee also