Validación del token de Microsoft Entra
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>Base64 encoded signing key | certificate-id="mycertificate"</key>
<!-- 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 | Una lista de claves con codificación Base64, en subelementos key , que se usan para descifrar los tokens. Si existen varias claves de seguridad, se prueba cada clave hasta que se agoten todas (en cuyo caso no se superará la validación) o que una sea la correcta.Para descifrar un token cifrado con una clave asimétrica, especifique opcionalmente la clave pública mediante un atributo certificate-id con el valor establecido en el identificador de un certificado subido a 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. | No | N/D |
Uso
- Secciones de la directiva: inbound (entrada)
- Ámbitos de la directiva: global, área de trabajo, producto, API, operación
- Puertas de enlace: clásica, v2, consumo, autohospedada y área de trabajo
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 usarclaims
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>
Directivas relacionadas
Contenido relacionado
Para más información sobre el trabajo con directivas, vea:
- Tutorial: Transformación y protección de una API
- Referencia de directivas para una lista completa de instrucciones de directivas y su configuración
- Expresiones de directiva
- Establecimiento o edición de directivas
- Reutilización de configuraciones de directivas
- Repositorio de fragmentos de código de directiva
- Creación de directivas mediante Microsoft Copilot en Azure