Convalidare il token Microsoft Entra

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il validate-azure-ad-token criterio 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 altro provider di identità, Gestione API fornisce anche i criteri validate-jwt generici.

Nota

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

Istruzione del criterio

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    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 Azure Active Directory</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 Azure Active Directory</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>
</validate-azure-ad-token>

Attributi

Attributo Descrizione Richiesto Valore predefinito
tenant-id ID tenant o URL del servizio Microsoft Entra. 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ù audience valori, ogni valore viene provato fino a quando non vengono esauriti tutti (nel qual caso la convalida ha esito negativo) o fino a quando non viene completata una. 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ù application-id elementi, ogni valore viene provato fino a quando non vengono esauriti tutti (nel qual caso la convalida ha esito negativo) o fino a quando non viene completata una. Se non viene specificato un ID applicazione client, è necessario specificare una o più audience attestazioni. Le espressioni di criteri non sono consentite. Sì
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

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

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. Il nome host viene fornito usando un'espressione di criteri e vengono forniti l'ID tenant e l'ID applicazione client di Microsoft Entra usando i valori denominati. 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="{{aad-tenant-id}}" 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: