Dettagli del servizio API REST PAM

Articolo
09/14/2023

Nelle sezioni seguenti vengono illustrati i dettagli dell'API REST di gestione accessi con privilegi (PAM) di Microsoft Identity Manager (MIM).

Intestazioni di richiesta HTTP

Le richieste HTTP inviate all'API devono includere le intestazioni seguenti (questo elenco non è esaustivo):

Intestazione	Descrizione
Autorizzazione	Obbligatorio. Il contenuto dipende dal metodo di autenticazione, configurabile e può essere basato su WIA (Autenticazione integrata di Windows) o ADFS.
Content-Type	Obbligatorio se la richiesta ha un corpo. Il valore deve essere impostato su `application/json`.
Content-Length	Obbligatorio se la richiesta ha un corpo.
Cookie	Il cookie di sessione. Potrebbero essere necessari a seconda del metodo di autenticazione.

Intestazioni di risposta HTTP

Le risposte HTTP devono includere le intestazioni seguenti (questo elenco non è esaustivo):

Intestazione	Descrizione
Content-Type	L'API restituisce `application/json`sempre .
Content-Length	La lunghezza del corpo della richiesta, se presente, indicato in byte.

Controllo delle versioni

La versione corrente delle API è 1. La versione dell'API può essere specificata mediante un parametro di query nell'URL della richiesta, come nell'esempio seguente: http://localhost:8086/api/pamresources/pamrequests?v=1 se la versione non è specificata nella richiesta, la richiesta viene eseguita in base alla versione rilasciata più di recente dell'API.

Sicurezza

L'accesso all'API richiede Autenticazione integrata di Windows (IWA). Questa funzionalità deve essere configurata manualmente in IIS prima dell'installazione di Microsoft Identity Manager (MIM).

HTTPS (TLS) è supportato, ma deve essere configurato manualmente in IIS. Per informazioni, vedere Implementare Secure Sockets Layer (SSL) per il portale FIM nel passaggio 9: Eseguire attività successive all'installazione di FIM 2010 R2 nella Guida all'installazione del lab di test FIM 2010 R2.

È possibile generare un nuovo certificato server SSL eseguendo il comando seguente nel prompt dei comandi di 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

Il comando crea un certificato autofirmato che può essere usato per testare un'applicazione Web che usa SSL in un server Web in cui l'URL è test.cwap.com. L'OID definito dall'opzione -eku identifica il certificato come certificato del server SSL. Il certificato viene archiviato nell'archivio personale ed è disponibile a livello di computer. È possibile esportare il certificato dallo snap-in Certificati in mmc.exe.

Accesso tra domini diversi (CORS)

L'accesso tra domini diversi è supportato, ma deve essere configurato manualmente in IIS. Aggiungere i seguenti elementi al file web.config dell'API distribuita per configurare l'API affinché consenta le chiamate tra domini:

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

Gestione degli errori

L'API restituisce le risposte agli errori HTTP per indicare le condizioni di errore. Gli errori sono conformi a OData. La tabella seguente illustra i codici di errore che possono essere restituiti a un client:

Codice di stato HTTP	Descrizione
401	Non autorizzata
403	Accesso negato
408	Timeout richiesta
500	Internal Server Error
503	Servizio non disponibile

Filtro

Le richieste API REST PAM possono includere filtri per specificare le proprietà che devono essere incluse nella risposta. La sintassi di filtro è basata su espressioni OData.

I filtri possono specificare le proprietà delle richieste PAM, dei ruoli PAM o delle richieste PAM in sospeso. Ad esempio: ExpirationTime, DisplayName o qualsiasi altra proprietà valida di una richiesta PAM, di un ruolo PAM o di una richiesta in sospeso.

L'API supporta gli operatori seguenti nelle espressioni di filtro: And, Equal, NotEqual, GreaterThan, LessThan, GreaterThenOrEqueal e LessThanOrEqual.

Le richieste di esempio seguenti includono filtri:

La richiesta restituisce tutte le richieste PAM comprese tra date specifiche: 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'
Questa richiesta restituisce il ruolo PAM con il nome visualizzato "Accesso File SQL": http://localhost:8086/api/pamresources/pamroles?$filter=DisplayName eq 'SQL File Access'

Condividi tramite