Detalles del servicio DE API REST de Administración de certificados
En las secciones siguientes se describen los detalles de la API REST de administración de certificados (CM) de Microsoft Identity Manager (MIM).
Architecture
Las llamadas a la API de REST de CM de MIM se controlan mediante controladores. En la siguiente tabla se muestra la lista completa de controladores y ejemplos del contexto en el que pueden usarse.
| Controller | Ruta de ejemplo |
|---|---|
| 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/{profiletemplateid}/policies/{id} |
| ProfilesController | /api/v1.0/profiles/{id} |
| ProfileTemplatesController | /api/v1.0/profiletemplates/{id} /api/v1.0/profiletemplates /api/v1.0/profiletemplates/{profiletemplateid}/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/{profiletemplateid}/configuration/smartcards |
Encabezados de solicitud y respuesta HTTP
Las solicitudes HTTP enviadas a la API deben incluir los siguientes encabezados (esta lista no es exhaustiva):
| Encabezado | Descripción |
|---|---|
| Authorization | Necesario. El contenido depende del método de autenticación. El método es configurable y se puede basar en la autenticación integrada de Windows (WIA)) o Servicios de federación de Active Directory (AD FS) (ADFS). |
| Content-Type | Obligatorio si la solicitud tiene un cuerpo. Debe ser application/json. |
| Content-Length | Obligatorio si la solicitud tiene un cuerpo. |
| Cookie | Cookie de la sesión. Puede ser obligatorio en función del método de autenticación. |
Las respuestas HTTP incluyen los siguientes encabezados (esta lista no es exhaustiva):
| Encabezado | Descripción |
|---|---|
| Content-Type | La API siempre devuelve application/json. |
| Content-Length | Longitud del cuerpo de la solicitud en bytes si es que está presente. |
Control de versiones de la API
La versión actual de la API de REST de CM es 1.0. La versión se especifica en el segmento que se encuentra justo después del segmento /api del URI: /api/v1.0. El número de versión cambia cuando se realizan modificaciones importantes en la interfaz de API.
Habilitación de la API
La sección <ClmConfiguration> del archivo Web.config se ha extendido con una clave nueva:
<add key="Clm.WebApi.Enabled" value="false" />
Esta clave determina si la API de REST de CM se expone a los clientes. Si la clave se establece en "false", la asignación de ruta de la API no se realiza al iniciar la aplicación. Las solicitudes posteriores a los puntos de conexión de API devuelven un código de error HTTP 404. De forma predeterminada, la clave se establece en "disabled".
Nota
Después de cambiar este valor a "true", recuerde ejecutar iisreset en el servidor.
Habilitación del seguimiento y el registro
La API de REST de CM de MIM emite los datos de seguimiento de cada solicitud HTTP que se le envía. Puede establecer el nivel de detalle de la información de seguimiento emitida estableciendo el siguiente valor de configuración:
<add name="Microsoft.Clm.Web.API" value="0" />
Control de errores y solución de problemas
Cuando se producen excepciones al procesar una solicitud, la API de REST de CM de MIM devuelve un código de estado HTTP al cliente web. Si se trata de errores comunes, la API devuelve un código de estado HTTP adecuado y un código de error.
Las excepciones no controladas se convierten en una HttpResponseException con el código de estado HTTP 500 ("Error interno") y se incluyen en el registro de eventos y en el archivo de seguimiento de CM de MIM. Cada excepción no controlada se incluye en el registro de eventos con un identificador de correlación correspondiente. El identificador de correlación también se envía al consumidor de la API en el mensaje de error. Para solucionar el error, un administrador puede buscar en el registro de eventos el identificador de correlación correspondiente y los detalles del error.
Nota
Los seguimientos de pila que corresponden a errores, que se generan como resultado de consumir la API REST de MIM CM, no se envían de vuelta al cliente. Los seguimientos no se envían de vuelta al cliente debido a problemas de seguridad.