Compartir vía

Validación del token de Microsoft Entra

  • Artículo

SE APLICA A: todos los niveles de API Management

La directiva de validate-azure-ad-token aplica la existencia y validez de un token web JSON (JWT) proporcionado por el servicio Microsoft Entra (anteriormente denominado Azure Active Directory) para un conjunto especificado de entidades de seguridad en el directorio. Este token se puede extraer de un encabezado HTTP, un parámetro de consulta o un valor especificados mediante una expresión de directiva o una variable de contexto.

Nota:

Para validar un JWT proporcionado por un proveedor de identidades distinto de Microsoft Entra, API Management también proporciona la directiva de validate-jwt genérica.

Nota:

Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.

Instrucción de la directiva

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

Atributos

Atributo Descripción Necesario Valor predeterminado
tenant-id Identificador de inquilino o dirección URL del inquilino de Microsoft Entra, o uno de los siguientes inquilinos conocidos:

- organizations o https://login.microsoftonline.com/organizations para permitir tokens de cuentas en cualquier directorio organizativo (cualquier directorio de Microsoft Entra)
- common o https://login.microsoftonline.com/common: para permitir tokens de cuentas de cualquier directorio organizativo (cualquier directorio de Microsoft Entra) y de cuentas personales de Microsoft (por ejemplo, Skype, XBox)

Se permiten expresiones de directiva.		 Sí N/D
header-name El nombre del encabezado HTTP que contiene el token. Se permiten expresiones de directiva. Se debe especificar uno de header-name, query-parameter-name o token-value. Authorization
nombre del parámetro de consulta Nombre del parámetro de consulta que contiene el token. Se permiten expresiones de directiva. Se debe especificar uno de header-name, query-parameter-name o token-value. N/D
token-value Expresión que devuelve una cadena que contiene el token. No debe devolver Bearer como parte del valor del token. Se permiten expresiones de directiva. Se debe especificar uno de header-name, query-parameter-name o token-value. N/D
failed-validation-httpcode Código de estado HTTP que se devuelve si el elemento JWT no supera la validación. Se permiten expresiones de directiva. No 401
failed-validation-error-message Mensaje de error que se devuelve en el cuerpo de respuesta HTTP si el elemento JWT no supera la validación. Los caracteres especiales de este mensaje deben incluir los caracteres de escape correctos. Se permiten expresiones de directiva. No El mensaje de error predeterminado depende del problema de validación, por ejemplo, la notificación de la ausencia del elemento JWT.
output-token-variable-name String. Nombre de la variable de contexto que recibirá el valor del token como un objeto de tipo Jwt tras la validación correcta del token. No se permiten expresiones de directiva. No N/D

Elementos

Elemento Descripción Obligatorio
audiences Contiene una lista de notificaciones de audiencia aceptables que pueden estar presentes en el token. Si existen varios valores de audience, se prueban los valores uno a uno hasta que se agoten todos (en cuyo caso no se superará la validación) o hasta que se obtenga un resultado positivo con alguno. Se permiten expresiones de directiva. No
backend-application-ids Contiene una lista de identificadores de aplicaciones de back-end aceptables. Esto solo es necesario en casos avanzados para la configuración de opciones y, por lo general, se puede quitar. No se permiten expresiones de directiva. No
client-application-ids Contiene una lista de identificadores de aplicaciones cliente aceptables. Si existen varios elementos de application-id, se prueban los valores uno a uno hasta que se agoten todos (en cuyo caso no se superará la validación) o hasta que se obtenga un resultado positivo con alguno. Si no se proporciona un identificador de aplicación cliente, se deben especificar una o varias notificaciones de audience. No se permiten expresiones de directiva. No
required-claims Contiene una lista de elementos claim para los valores de las notificaciones que se espera que estén presentes en el token para que se considere válido. Cuando el atributo match está establecido en all, todos los valores de notificación de la directiva deben estar presentes en el token para que la validación se efectúe correctamente. Cuando el atributo match está establecido en any, debe haber al menos una notificación en el token para que la validación se efectúe correctamente. Se permiten expresiones de directiva. No
decryption-keys Lista de subelementos key, que se usan para descifrar un token firmado con una clave asimétrica. Si hay varias claves, se prueba cada una hasta que se agoten todas (en cuyo caso no se supera la validación) o que una clave sea la correcta.

Especifique la clave pública mediante un atributo certificate-id con el valor establecido en el identificador de un certificado cargado en API Management.		 No

Atributos de notificación

Atributo Descripción Necesario Valor predeterminado
name Nombre de la notificación tal como se espera que aparezca en el token. Se permiten expresiones de directiva. Sí N/D
match El atributo match del elemento claim especifica si todos los valores de notificación de la directiva deben estar presentes en el token para que la validación se efectúe correctamente. Los valores posibles son:

- all: todos los valores de notificación de la directiva deben estar presentes en el token para que la validación se efectúe correctamente.

- any: al menos un valor de notificación debe estar presente en el token para que la validación se efectúe correctamente.

Se permiten expresiones de directiva.		 No todo
separador Cadena Especifica el separador (por ejemplo: ",") que se va a usar para extraer un conjunto de valores de una notificación con varios valores. Se permiten expresiones de directiva. No N/D

Atributos clave

Atributo Descripción Necesario Valor predeterminado
certificate-id Identificador de una entidad de certificado cargado en API Management, que se usa para especificar la clave pública para comprobar un token firmado con una clave asimétrica. Sí N/D

Uso

Notas de uso

  • Puede usar las directivas de restricción de acceso en distintos ámbitos para distintos propósitos. Por ejemplo, puede proteger toda la API con la autenticación de Microsoft Entra si aplica la directiva validate-azure-ad-token en el nivel de API, o bien puede aplicarla en el nivel de operación de API y usar claims para un control más detallado.
  • No se admite Microsoft Entra ID para clientes (versión preliminar) .

Ejemplos

Validación de tokens simple

La siguiente directiva es el formato mínimo de la directiva validate-azure-ad-token. La directiva espera que el JWT se proporcione en el encabezado Authorization predeterminado mediante el esquema Bearer. En este ejemplo, el identificador de inquilino de Microsoft Entra y el identificador de la aplicación cliente se proporcionan mediante valores con nombre.

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

Comprobación de que la audiencia y la notificación son correctas

La siguiente directiva comprueba que la audiencia es el nombre de host de la instancia de API Management y que la notificación ctry es US. El identificador de inquilino de Microsoft es el inquilino de organizations conocido, que permite tokens de cuentas en cualquier directorio organizativo. El nombre de host se proporciona mediante una expresión de directiva y el identificador de aplicación cliente se proporciona mediante un valor con nombre. El JWT descodificado se proporciona en la variable jwt después de la validación.

Para más información sobre las notificaciones opcionales, consulte Proporcionar notificaciones opcionales a la aplicación.

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

Contenido relacionado

Para más información sobre el trabajo con directivas, vea: