Detalles del servicio de API REST de PAM

Artículo
09/14/2023

En las siguientes secciones se describen los detalles de la API de REST de Privileged Access Management (PAM) de Microsoft Identity Manager (MIM).

Encabezados de solicitud HTTP

Las solicitudes HTTP que se envían 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, que es configurable y puede basarse en WIA (autenticación integrada de Windows) o ADFS.
Content-Type	Obligatorio si la solicitud tiene un cuerpo. Se debe establecer en `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.

Encabezados de respuesta HTTP

Las respuestas HTTP deben incluir 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

La versión actual de la API es 1. La versión de API puede especificarse mediante un parámetro de consulta en la dirección URL de solicitud, como en el ejemplo siguiente: http://localhost:8086/api/pamresources/pamrequests?v=1 Si no se especifica la versión de la solicitud, la solicitud se ejecuta con la versión más reciente publicada de la API.

Seguridad

El acceso a la API requiere Autenticación integrada de Windows (IWA). Esta debe configurarse manualmente en IIS antes de instalar Microsoft Identity Manager (MIM).

Se ofrece compatibilidad con HTTPS (TLS), pero debe configurarse manualmente en IIS. Para obtener información, consulte: Implementar capa de sockets seguros (SSL) para el portal de FIM en paso 9: Realizar tareas posteriores a la instalación de FIM 2010 R2 en la Guía del laboratorio de pruebas de FIM 2010 R2.

Puede generar un nuevo certificado de servidor SSL ejecutando el siguiente comando en el símbolo del sistema de Visual Studio:

Makecert -r -pe -n CN="test.cwap.com" -b 05/10/2014 -e 12/22/2048 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localmachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12

El comando crea un certificado autofirmado que se puede usar para probar una aplicación web que usa SSL en un servidor web donde la dirección URL es test.cwap.com. El OID definido por la -eku opción identifica el certificado como un certificado de servidor SSL. El certificado se almacena en mi almacén y está disponible en el nivel de máquina. Puede exportar el certificado desde el complemento Certificados en mmc.exe.

Acceso entre dominios (CORS)

Se ofrece compatibilidad con CORS, pero debe configurarse manualmente en IIS. Agregue los siguientes elementos al archivo web.config de la API implementada para configurar la API para que permita las llamadas entre dominios:

<system.webServer>       
    <httpProtocol> 
        <customHeaders> 
            <add name="Access-Control-Allow-Credentials" value="true"  /> 
            <add name="Access-Control-Allow-Headers" value="content-type" /> 
            <add name="Access-Control-Allow-Origin" value="http://<hostname>:8090" /> 
        </customHeaders> 
    </httpProtocol> 
</system.webServer>

Control de errores

La API devuelve respuestas de error HTTP para indicar condiciones de error. Los errores son compatibles con OData. En la tabla siguiente se muestran los códigos de error que se pueden devolver a un cliente:

Código de estado HTTP	Descripción
401	No autorizado
403	Prohibido
408	Tiempo de espera de solicitud
500	Internal Server Error
503	Servicio no disponible

Filtrado

Las solicitudes de la API de REST de PAM pueden incluir filtros para especificar las propiedades que deben incluirse en la respuesta. La sintaxis de filtro se basa en expresiones de OData.

Los filtros pueden especificar cualquiera de las propiedades de las solicitudes de PAM, de los roles de PAM o de las solicitudes pendientes de PAM. Por ejemplo: ExpirationTime, DisplayName o cualquier otra propiedad válida de una solicitud de PAM, rol de PAM o solicitud pendiente de PAM.

La API es compatible con los siguientes operadores en las expresiones de filtros: And, Equal, NotEqual, GreaterThan, LessThan, GreaterThanOrEqual y LessThanOrEqual.

Las siguientes solicitudes de ejemplo incluyen filtros:

Esta solicitud devuelve todas las solicitudes de PAM entre fechas específicas: http://localhost:8086/api/pamresources/pamrequests?$filter=ExpirationTime gt datetime'2015-01-09T08:26:49.721Z' and ExpirationTime lt datetime'2015-02-10T08:26:49.722Z'
Esta solicitud devuelve el rol de PAM con el nombre para mostrar "Acceso a archivo SQL": http://localhost:8086/api/pamresources/pamroles?$filter=DisplayName eq 'SQL File Access'

Compartir a través de