Detalles del servicio DE API REST de Administración de certificados

Artículo
09/14/2023

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.