Détails du service d’API REST PAM

Article
09/14/2023

Les sections suivantes présentent les détails relatifs à l'API REST Microsoft Identity Manager (MIM) Privileged Access Management (PAM) REST API.

En-têtes de requête 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, qui est configurable et peut être basée sur WIA (Windows Integrated Authentication) ou ADFS.
Content-Type	Obligatoire si la requête a un corps. Cette propriété doit être définie sur `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.

En-têtes de réponse HTTP

Les réponses HTTP doivent inclure les en-têtes suivants (cette liste n’est pas exhaustive) :

En-tête	Description
Content-Type	L’API retourne `application/json`toujours .
Content-Length	Longueur du corps de la requête, le cas échéant, en octets.

Gestion de version

La version actuelle de l'API est la version 1. La version de l’API peut être spécifiée via un paramètre de requête dans l’URL de demande, comme dans l’exemple suivant : http://localhost:8086/api/pamresources/pamrequests?v=1 Si la version n’est pas spécifiée dans la demande, celle-ci est exécutée sur la version la plus récente de l’API.

Sécurité

L'accès à l'API nécessite l'authentification Windows intégrée. Celle-ci doit être configurée manuellement dans IIS avant l'installation de Microsoft Identity Manager (MIM).

Le protocole HTTPS (TLS) est pris en charge. Toutefois, il doit être configuré manuellement dans IIS. Pour plus d’informations, consultez : Implémenter ssl (Secure Sockets Layer) pour le portail FIM à l’étape 9 : Effectuer des tâches de post-installation FIM 2010 R2 dans le Guide du laboratoire de test FIM 2010 R2.

Vous pouvez générer un nouveau certificat de serveur SSL en exécutant la commande suivante à l'invite de commandes 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

La commande crée un certificat auto-signé qui peut être utilisé pour tester une application web qui utilise SSL sur un serveur web où l’URL est test.cwap.com. L’OID défini par l’option -eku identifie le certificat en tant que certificat de serveur SSL. Le certificat est stocké dans mon magasin et est disponible au niveau de l’ordinateur. Vous pouvez exporter le certificat à partir du composant logiciel enfichable Certificats dans mmc.exe.

Accès entre domaines (CORS)

L'accès entre domaines (CORS) est pris en charge. Toutefois, il doit être configuré manuellement dans IIS. Ajoutez les éléments suivants au fichier web.config de l'API déployée pour configurer l'API et permettre les appels entre domaines :

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

Gestion des erreurs

L'API retourne des réponses d'erreur HTTP pour indiquer les conditions de l'erreur. Les erreurs sont signalées au format OData. Le tableau suivant montre les codes d’erreur qui peuvent être retournés à un client :

Code d'état HTTP	Description
401	Non autorisé
403	Interdit
408	Délai d’expiration de la demande
500	Erreur interne du serveur
503	Service indisponible

Filtrage

Les demandes de l'API REST PAM peuvent inclure des filtres permettant de spécifier les propriétés à inclure dans la réponse. La syntaxe des filtres est basée sur les expressions OData.

Les filtres peuvent spécifier les propriétés de demandes PAM, de rôles PAM ou de demandes PAM en attente. Par exemple : ExpirationTime, DisplayName ou toute autre propriété valide d’une requête PAM, d’un rôle PAM ou d’une requête en attente.

L’API prend en charge les opérateurs suivants dans les expressions de filtre : And, Equal, NotEqual, GreaterThan, LessThan, GreaterThenOrEqueal et LessThanOrEqual.

Les exemples de demandes suivants comportent des filtres :

Cette demande retourne toutes les demandes PAM comprises entre des dates spécifiques : 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'
Cette demande retourne le rôle PAM dont le nom complet est « SQL File Access » : http://localhost:8086/api/pamresources/pamroles?$filter=DisplayName eq 'SQL File Access'

Partager via