Détails du service de l’API REST de gestion des certificats
les sections suivantes décrivent les détails de l’API REST de gestion des certificats 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 Windows intégrée (WIA)) ou services de fédération Active Directory (AD FS) (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 toujours application/json . |
| 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 demandes suivantes aux points de terminaison de l’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 des erreurs et résolution des problèmes
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, qui sont générées à la suite de l’utilisation de l’API REST MIM CM, ne sont pas renvoyées au client. Les traces ne sont pas renvoyées au client en raison de problèmes de sécurité.