Validar JWT

SE APLICA A: todos los niveles de API Management

La directiva aplica la existencia y validez de un JSON Web Token (JWT) admitido proporcionado por un proveedor de identidades. El JWT se puede extraer de un encabezado HTTP especificado, extraerse de un parámetro de consulta especificado o coincidir con un valor específico.

Nota:

Use la directiva validate-azure-ad-token para validar un JWT proporcionado por Microsoft Entra.

Nota:

Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Para que pueda configurar esta directiva, el portal proporciona un editor guiado basado en formularios. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.

Instrucción de la directiva

<validate-jwt
    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"
    require-expiration-time="true | false"
    require-scheme="scheme"
    require-signed-tokens="true | false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, for example, https://login.constoso.com/openid-configuration" validate-connectivity="true | false"/>
  <issuer-signing-keys>
    <key id="kid-claim" certificate-id="mycertificate" n="modulus" e="exponent">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key certificate-id="mycertificate">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <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 claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Atributos

Atributo	Descripción	Necesario	Valor predeterminado
header-name	El nombre del encabezado HTTP que contiene el token. Se permiten expresiones de directiva.	Se debe especificar uno de , o .	N/D
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 , o .	N/D
token-value	Expresión que devuelve una cadena que contiene el token. No debe devolver como parte del valor del token. Se permiten expresiones de directiva.	Se debe especificar uno de , o .	N/D
failed-validation-httpcode	Código de estado HTTP que se devuelve si el elemento JWT no pasa 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.
require-expiration-time	booleano. Especifica si es necesaria una notificación de expiración en el token. Se permiten expresiones de directiva.	No	cierto
require-scheme	El nombre del esquema del token, por ejemplo, "Portador". Cuando se establece este atributo, la directiva se asegurará de que ese esquema especificado esté presente en el valor del encabezado de la autorización. Se permiten expresiones de directiva.	No	N/D
require-signed-tokens	booleano. Especifica si un token debe estar firmado. Se permiten expresiones de directiva.	No	cierto
sesgo de reloj	Intervalo de tiempo. Utilice esta opción para especificar la diferencia máxima de tiempo esperado entre los relojes del sistema del emisor del token y la instancia de API Management. Se permiten expresiones de directiva.	No	0 segundos
output-token-variable-name	Cuerda. Nombre de la variable de contexto que recibirá el valor del token como un objeto de tipo tras la validación correcta del token. No se permiten expresiones de directiva.	No	N/D

Elementos

Elemento	Descripción	Necesario
openid-config	Agregue uno o varios de estos elementos para especificar un punto de conexión de configuración de OpenID compatible ( atributo) desde el que se pueden obtener las claves de firma y el emisor. Opcionalmente, establezca el atributo en para deshabilitar la comprobación de la disponibilidad del punto de conexión si la dirección URL no se puede resolver a través de DNS público. La configuración que incluye JSON Web Key Set (JWKS) se extrae del punto de conexión cada hora y se almacena en caché. Si el token que se valida hace referencia a una clave de validación (mediante una notificación ) que falta en la configuración almacenada en caché, o si se produce un error en la recuperación, API Management extrae del punto de conexión, como máximo, una vez cada 5 minutos. Estos intervalos están sujetos a cambios sin previo aviso. La respuesta debe ser acorde a las especificaciones definidas en la dirección URL:. Para Microsoft Entra ID use el punto de conexión de OpenID Connect metadata configurado en el registro de la aplicación, como: - v2 - v2 multiinquilino - v1 - Inquilino del cliente (versión preliminar) Sustituyendo el nombre o el identificador del inquilino del directorio, por ejemplo , por .	No
issuer-signing-keys	Una lista de claves de seguridad con codificación Base64, en subelementos , que se utilizan para validar los tokens firmados. Si existen varias claves de seguridad, se prueban las claves una a una hasta que se agoten todas (en cuyo caso no se superará la validación) o que una sea la correcta (lo que es útil para la sustitución de tokens). Opcionalmente, especifique una clave mediante el atributo para que coincida con la notificación del token. Para validar un token firmado con una clave asimétrica, especifique opcionalmente la clave pública utilizando un atributo con valor establecido en el identificador de un certificado cargado en API Management, o el par de módulo RSA y exponente de la clave de firma en formato codificado con Base64url.	No
descifrado-claves	Una lista de claves con codificación Base64, en subelementos , 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 con el valor establecido en el identificador de un certificado subido a API Management.	No
Audiencias	Una lista de notificaciones de audiencia aceptables, en los subelementos , que pueden estar presentes en el token. Si existen varios valores de audiencia, 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. Debe especificarse al menos una audiencia.	No
Emisores	Una lista de entidades de seguridad aceptables, en subelementos , que emitieron el token. Si existen varios valores de emisor, 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.	No
required-claims	Una lista de las notificaciones, en los subelementos , que se espera que estén presentes en el token para que se considere válido. Cuando hay varias notificaciones, el token debe coincidir con los valores de notificación según el valor del atributo .	No

Atributos clave

Atributo	Descripción	Necesario	Valor predeterminado
identificación	(Solo clave de firma del emisor) Cadena. Identificador usado para buscar coincidencias con la notificación presentada en JWT. Si no hay claves que coincidan con la notificación, API Management intentará cada clave especificada. Obtenga más información sobre la notificación de en RFC.	No	N/D
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
n	(Solo clave de firma del emisor) Módulo de la clave pública que se usa para comprobar el emisor de un token firmado con una clave asimétrica. Debe especificarse con el valor del exponente . No se permiten expresiones de directiva.	No	N/D
e	(Solo clave de firma del emisor) Exponente de la clave pública que se usa para comprobar el emisor de un token firmado con una clave asimétrica. Debe especificarse con el valor del módulo . No se permiten expresiones de directiva.	No	N/D

Atributos de notificación

Atributo	Descripción	Necesario	Valor predeterminado
cerilla	El atributo del elemento 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: : todos los valores de notificación de la directiva deben estar presentes en el token para que la validación se efectúe correctamente. : al menos un valor de notificación debe estar presente en el token para que la validación se efectúe correctamente.	No	todo
separador	Cuerda. Especifica el separador (por ejemplo: ",") que se va a usar para extraer un conjunto de valores de una notificación con varios valores.	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

La directiva requiere que la notificación registrada se incluya en el JWT, a menos que se especifique el atributo y establezca en .
La directiva admite algoritmos de firma simétricos y asimétricos:
- Simétrico: se admiten los siguientes algoritmos de cifrado: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
  - Si se usa en la directiva, la clave debe proporcionarse en línea dentro de la directiva en el formulario codificado en Base64.
- Asimétrico: Se admiten los siguientes algoritmos de cifrado: PS256, RS256, RS512, ES256.
  - Si se usa en la directiva, la clave se puede proporcionar a través de un punto de conexión de configuración de OpenID o proporcionando el identificador de un certificado cargado (en formato PFX) que contiene la clave pública o el par modulus-exponent de la clave pública.
Si la instancia de API Management se inserta o integra en una red virtual y las direcciones URL del punto de conexión se configuran en la directiva, establezca el atributo en para deshabilitar la comprobación de la disponibilidad del punto de conexión.
Puede usar las directivas de restricción de acceso en distintos ámbitos para distintos propósitos. Por ejemplo, puede proteger toda la API con Microsoft Entra autenticación aplicando la directiva de validate-jwt en el nivel de API, o puede aplicarla en el nivel de operación de API y usar claims para un control más granular.
Al usar un encabezado personalizado (), se omitirá el esquema necesario configurado (). Para usar un esquema necesario, se deben proporcionar JWT en el encabezado .

Ejemplos

Validación de tokens simple

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Validación de tokens con certificado RSA

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Microsoft Entra ID validación de tokens de inquilino único

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>00001111-aaaa-2222-bbbb-3333cccc4444</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Microsoft Entra ID validación de tokens de inquilino de cliente

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

validación de tokens B2C de Azure Active Directory

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>11112222-bbbb-3333-cccc-4444dddd5555</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Importante

A partir del 1 de mayo de 2025, Azure AD B2C ya no estará disponible para comprar nuevos clientes. Obtenga más información en nuestras preguntas más frecuentes.

Validación de tokens mediante la clave de descifrado

En este ejemplo se muestra cómo usar la directiva de para validar un token que se descifra mediante una clave de descifrado. La clave se especifica mediante el id. de un certificado cargado (en formato PFX) que contiene la clave pública.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
    <decryption-keys>
        <key certificate-id="my-certificate-in-api-management" /> <!-- decryption key specified as certificate ID -->
    </decryption-keys>
</validate-jwt>

Autorización de acceso a las operaciones según las notificaciones de tokens

En este ejemplo se muestra cómo usar la directiva de para autorizar el acceso a operaciones según el valor de las notificaciones de token.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

Autenticación y autorización

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 Policy
repositorio del área de juegos Policy
Azure API Management policy toolkit
Get Copilot ayuda para crear, explicar y solucionar problemas de directivas

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-03-06