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 otro proveedor de identidades, API Management también proporciona la directiva genérica validate-jwt.

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

Atributos

Atributo Descripción Necesario Valor predeterminado
tenant-id Id. de inquilino o dirección URL del servicio Microsoft Entra. 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

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

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 nombre de host se proporciona mediante una expresión de directiva y el identificador del inquilino de Microsoft Entra y el identificador de la aplicación cliente se proporcionan mediante valores 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="{{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>

Contenido relacionado

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