Compartir vía

Validar JWT

  • Artículo

SE APLICA A: todos los niveles de API Management

La directiva validate-jwt exige que haya un token web JSON (JWT) admitido, válido, extraído de un encabezado HTTP especificado, extraído de un parámetro de consulta especificado o que coincida con un valor concreto.

Nota:

Para validar un JWT proporcionado por el servicio Microsoft Entra, API Management también proporciona la directiva validate-azure-ad-token.

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" />
  <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 header-name, query-parameter-name o token-value. 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 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 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 true
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 true
clock-skew 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 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
openid-config Agregue uno o varios de estos elementos para especificar una URL de punto de conexión de configuración de OpenID compatible, desde la que se puedan obtener claves de firma y un emisor.

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 kid) 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:https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Para Microsoft Entra ID, use el punto de conexión de metadatos de OpenID Connect configurado en el registro de la aplicación, como:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- v2 multiinquilino https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
- Inquilino del cliente (versión preliminar) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Sustituyendo el nombre o el identificador del inquilino del directorio, por ejemplo contoso.onmicrosoft.com, por {tenant-name}.		 No
issuer-signing-keys Una lista de claves de seguridad con codificación Base64, en subelementos key, 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 id para que coincida con la notificación kid del token. Para validar un token firmado con una clave asimétrica, especifique opcionalmente la clave pública utilizando un atributo certificate-id con valor establecido en el identificador de un certificado cargado en API Management, o el par de módulo RSA n y exponente e de la clave de firma en formato codificado con Base64url.		 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
audiences Una lista de notificaciones de audiencia aceptables, en los subelementos audience, 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
issuers Una lista de entidades de seguridad aceptables, en subelementos issuer, 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 claim, 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 match. No

Atributos clave

Atributo Descripción Necesario Valor predeterminado
id (Solo clave de firma del emisor) Cadena. Identificador usado para buscar coincidencias con la notificación kid 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 kid 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 e. 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 n. No se permiten expresiones de directiva. No N/D

Atributos de notificación

Atributo Descripción Necesario Valor predeterminado
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.		 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. No N/D

Uso

Notas de uso

  • La directiva validate-jwt requiere que la notificación registrada exp se incluya en el token de JWT, a menos que se especifique el atributo require-expiration-time y se establezca en false.
  • 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.
  • Para configurar la directiva con uno o varios puntos de conexión de configuración de OpenID para su uso con una puerta de enlace autohospedada, las direcciones URL de los puntos de conexión de configuración de OpenID también deben ser accesibles por la puerta de enlace en la nube.
  • 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-jwt 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.
  • Al usar un encabezado personalizado (header-name), se omitirá el esquema necesario configurado (require-scheme). Para usar un esquema necesario, los tokens JWT deben proporcionarse en el encabezado Authorization.

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>

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

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

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

<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 de Azure Active Directory B2C

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

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

En este ejemplo se muestra cómo usar la directiva de validate-jwt 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>

Contenido relacionado

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