Convalidare il token Microsoft Entra

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il criterio validate-azure-ad-token applica l'esistenza e la validità di un token Web JSON (JWT) fornito dal servizio Microsoft Entra (in precedenza denominato Azure Active Directory) per un set specificato di entità nella directory. Il token JWT può essere estratto da un'intestazione HTTP, un parametro di query o un valore specificato usando un'espressione di criteri o una variabile di contesto.

Nota

Per convalidare un token JWT fornito da un provider di identità diverso da Microsoft Entra, Gestione API fornisce anche i criteri generici validate-jwt.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio. Altre informazioni su come impostare o modificare i criteri di API Management.

Istruzione del criterio

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Microsoft Entra</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Microsoft Entra</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Attributi

Attributo Descrizione Richiesto Valore predefinito
tenant-id ID tenant o URL del tenant di Microsoft Entra ID o uno dei tenant noti seguenti:

- organizations o https://login.microsoftonline.com/organizations per consentire token degli account in qualsiasi directory organizzativa (Qualsiasi directory di Microsoft Entra)
- common oppure https://login.microsoftonline.com/common: per consentire token da account in qualsiasi directory organizzativa (qualsiasi directory di Microsoft Entra) e da account Microsoft personali (ad esempio, Skype, XBox)

Le espressioni di criteri sono consentite.		 Sì N/D
header-name Il nome dell'intestazione HTTP che contiene il token. Le espressioni di criteri sono consentite. È necessario specificare uno degli elementi header-name, query-parameter-name o token-value. Authorization
query-parameter-name Nome di parametro di query che contiene il token. Le espressioni di criteri sono consentite. È necessario specificare uno degli elementi header-name, query-parameter-name o token-value. N/D
token-value Espressione che restituisce una stringa contenente il token. Non è necessario restituire Bearer come parte del valore del token. Le espressioni di criteri sono consentite. È necessario specificare uno degli elementi header-name, query-parameter-name o token-value. N/D
failed-validation-httpcode Codice di stato HTTP da restituire se il token JWT non supera la convalida. Le espressioni di criteri sono consentite. No 401
failed-validation-error-message Messaggio di errore da restituire nel corpo della risposta HTTP se il token JWT non supera la convalida. I caratteri speciali eventualmente contenuti in questo messaggio devono essere adeguatamente preceduti da un carattere di escape. Le espressioni di criteri sono consentite. No Il messaggio di errore predefinito dipende dal problema della convalida, ad esempio "JWT not present" ("JWT non presente").
output-token-variable-name String. Nome della variabile di contesto che riceverà il valore del token come oggetto di tipo Jwt al termine della convalida del token. Le espressioni di criteri non sono consentite. No N/D

Elementi

Elemento Descrizione Richiesto
audiences Contiene un elenco di attestazioni "audience" accettabili che possono essere presenti nel token. Se sono presenti più valori audience, viene provato ogni valore fino al completamento di tutti i valori (caso in cui la convalida ha esito negativo) o fino a quando un valore non ha esito positivo. Le espressioni di criteri sono consentite. No
backend-application-ids Contiene un elenco di ID applicazione back-end accettabili. Questa operazione è necessaria solo nei casi avanzati per la configurazione delle opzioni e in genere può essere rimossa. Le espressioni di criteri non sono consentite. No
client-application-ids Contiene un elenco di ID applicazione client accettabili. Se sono presenti più elementi application-id, viene provato ogni valore fino al completamento di tutti i valori (caso in cui la convalida ha esito negativo) o fino a quando un valore non ha esito positivo. Se non viene specificato un ID applicazione client, è necessario specificare una o più attestazioni audience. Le espressioni di criteri non sono consentite. No
required-claims Contiene un elenco di elementi claim per i valori attestazioni che devono essere presenti nel token affinché sia considerato valido. Perché la convalida abbia esito positivo, quando l'attributo match è impostato su all ogni valore dell'attestazione nel criterio deve essere presente nel token. Perché la convalida abbia esito positivo, quando l'attributo match è impostato su any almeno un'attestazione deve essere presente nel token. Le espressioni di criteri sono consentite. No
decryption-keys Elenco di key sottoelementi, utilizzato per decrittografare un token firmato con una chiave asimmetrica. Se sono presenti più chiavi, ogni chiave viene tentata fino a quando tutte le chiavi non vengono esaurite (nel qual caso la convalida ha esito negativo) o una chiave ha esito positivo.

Specificare la chiave pubblica usando un certificate-id attributo con valore impostato sull'identificatore di un certificato caricato in Gestione API.		 No

attributi attestazione

Attributo Descrizione Richiesto Valore predefinito
name Nome dell'attestazione come previsto visualizzato nel token. Le espressioni di criteri sono consentite. Sì N/D
match Perché la convalida abbia esito positivo, l'attributo match sull'elemento claim specifica se il valore dell'attestazione nel criterio deve essere presente nel token. I valori possibili sono:

- all: ogni valore dell'attestazione nel criterio deve essere presente nel token perché la convalida abbia esito positivo.

- any: almeno un valore dell'attestazione deve essere presente nel token perché la convalida abbia esito positivo.

Le espressioni di criteri sono consentite.		 No tutto
separator String. Specifica un separatore (ad esempio ",") da usare per l'estrazione di un set di valori da un'attestazione multivalore. Le espressioni di criteri sono consentite. No N/D

attributi della chiave

Attributo Descrizione Richiesto Valore predefinito
certificate-id Identificatore di un'entità certificato caricata in Gestione API, usata per specificare la chiave pubblica per verificare un token firmato con chiave asimmetrica. Sì N/D

Utilizzo

Note sull'utilizzo

  • È possibile usare i criteri di restrizione di accesso in ambiti diversi per scopi diversi. Ad esempio, è possibile proteggere l'intera API con l'autenticazione Microsoft Entra applicando i criteri validate-azure-ad-token a livello di API oppure è possibile applicarla a livello di operazione API e usare claims per un controllo più granulare.
  • L'ID Microsoft Entra per i clienti (anteprima) non è supportato.

Esempi

Convalida semplice dei token

I criteri seguenti sono la forma minima dei criteri validate-azure-ad-token. Prevede che il token JWT venga fornito nell'intestazione Authorization predefinita usando lo schema Bearer. In questo esempio vengono forniti l'ID tenant e l'ID applicazione client di Microsoft Entra usando i valori denominati.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

Verificare che il gruppo di destinatari e l'attestazione siano corretti

I criteri seguenti controllano che il gruppo di destinatari sia il nome host dell'istanza di Gestione API e che l'attestazione ctry sia US. L'ID tenant Microsoft è il tenant organizations noto, che consente token da account in qualsiasi directory organizzativa. Il nome host viene fornito usando un'espressione di criteri e l'ID applicazione client viene fornito usando un valore denominato. Il token JWT decodificato viene fornito nella variabile jwt dopo la convalida.

Per altri dettagli sulle attestazioni facoltative, vedere Fornire attestazioni facoltative all'app.

<validate-azure-ad-token tenant-id="organizations" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: