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é.