Détails du service de l’API REST Gestion des certificats
Les sections suivantes décrivent les détails de l’API REST de gestion des certificats (CM) Microsoft Identity Manager (MIM).
Architecture
Les appels d'API REST MIM CM sont gérés par les contrôleurs. Le tableau suivant présente la liste complète des contrôleurs, ainsi que des exemples du contexte dans lequel ils peuvent être utilisés.
| Contrôleur | Exemple d’itinéraire |
|---|---|
| CertificateDataController | /api/v1.0/requests/{requestid}/certificatedata/ |
| CertificateRequestGenerationOptionsController | /api/v1.0/requests/{requestid} |
| CertificatesController | /api/v1.0/smartcards/{smartcardid}/certificates /api/v1.0/profiles/{profileid}/certificates |
| OperationsController | /api/v1.0/smartcards/{smartcardid}/operations /api/v1.0/profiles/{profileid}/operations |
| PoliciesController | /api/v1.0/profiletemplates/{ID_modèle_profil}/policies/{ID} |
| ProfilesController | /api/v1.0/profiles/{id} |
| ProfileTemplatesController | /api/v1.0/profiletemplates/{id} /api/v1.0/profiletemplates /api/v1.0/profiletemplates/{ID_modèle_profil}/policies/{ID} |
| RequestsController | /api/v1.0/requests/{id} /api/v1.0/requests |
| SmartcardsController | /api/v1.0/requests/{requestid}/smartcards/{id}/diversifiedkey /api/v1.0/requests/{requestid}/smartcards/{id}/serverproposedpin /api/v1.0/requests/{requestid}/smartcards/{id}/authenticationresponse /api/v1.0/requests/{requestid}/smartcards/{id} /api/v1.0/smartcards/{id} /api/v1.0/smartcards |
| SmartcardsConfigurationController | /api/v1.0/profiletemplates/{ID_modèle_profil}/configuration/smartcards |
En-têtes de requête et de réponse HTTP
Les requêtes HTTP envoyées à l’API doivent inclure les en-têtes suivants (cette liste n’est pas exhaustive) :
| En-tête | Description |
|---|---|
| Autorisation | Obligatoire. Le contenu dépend de la méthode d’authentification. La méthode est configurable et peut être basée sur l’authentification intégrée Windows (WIA) ou Services ADFS (ADFS). |
| Content-Type | Obligatoire si la requête a un corps. Doit être application/json. |
| Content-Length | Obligatoire si la requête a un corps. |
| Cookie | Cookie de session. Éventuellement nécessaire, selon la méthode d'authentification. |
Les réponses HTTP incluent les en-têtes suivants (cette liste n’est pas exhaustive) :
| En-tête | Description |
|---|---|
| Content-Type | L’API retourne application/jsontoujours . |
| Content-Length | Longueur du corps de la requête, le cas échéant, en octets. |
Contrôle de version d’API
La version actuelle de l'API REST CM est la version 1.0. La version est spécifiée dans le segment situé directement après le segment /api dans l'URI : /api/v1.0. Le numéro de version change lorsque des modifications majeures sont apportées à l’interface API.
Activer l’API
La section <ClmConfiguration> du fichier Web.config a été étendue avec une nouvelle clé :
<add key="Clm.WebApi.Enabled" value="false" />
Cette clé détermine si l'API REST CM est exposée aux clients. Si la clé a la valeur « false », le mappage d'itinéraire de l'API n'est pas effectué au démarrage de l'application. Les requêtes suivantes adressées aux points de terminaison d’API retournent un code d’erreur HTTP 404. Par défaut, la clé a la valeur « disabled ».
Notes
Après avoir modifié cette valeur sur « true », n’oubliez pas d’exécuter iisreset sur le serveur.
Activer le suivi et la journalisation
L'API REST MIM CM émet des données de trace pour chaque requête HTTP reçue. Vous pouvez définir le niveau de détail des informations de traçage émises, à l'aide de la valeur de configuration suivante :
<add name="Microsoft.Clm.Web.API" value="0" />
Gestion et résolution des erreurs
Quand des exceptions se produisent durant le traitement d'une requête, l'API REST MIM CM retourne un code d'état HTTP au client web. Pour les erreurs usuelles, l'API retourne le code d'état HTTP et le code d'erreur appropriés.
Les exceptions non prises en charge sont converties en HttpResponseException avec le code d'état HTTP 500 (« Erreur interne »). En outre, elles sont tracées dans le journal des événements et le fichier de trace MIM CM. Chaque exception non prise en charge est écrite dans le journal des événements avec un ID de corrélation correspondant. L'ID de corrélation est également envoyé au consommateur de l'API dans le message d'erreur. Pour résoudre l'erreur, un administrateur peut rechercher dans le journal des événements les détails et l'ID de corrélation correspondants.
Notes
Les traces de pile qui correspondent aux erreurs générées suite à la consommation de l’API REST CM MIM ne sont pas renvoyées au client. Les traces ne sont pas renvoyées au client en raison de problèmes de sécurité.