Directivas de restricción de acceso de API Management

En este artículo se proporciona una referencia para las directivas de restricción de acceso de API Management.

Más información sobre las directivas:

Directivas de restricción de acceso

Sugerencia

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

Comprobar encabezado HTTP

Usa la directiva check-header para exigir que una solicitud tenga un encabezado HTTP especificado. Si lo desea, puede comprobar si el encabezado tiene un valor específico o un intervalo de valores permitidos. Si el resultado de la comprobación es negativo, la directiva finaliza el procesamiento de la solicitud y devuelve el mensaje de error y el código de estado HTTP que especifica.

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

<check-header name="header name" failed-check-httpcode="code" failed-check-error-message="message" ignore-case="true">
    <value>Value1</value>
    <value>Value2</value>
</check-header>

Ejemplo

<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
    <value>f6dc69a089844cf6b2019bae6d36fac8</value>
</check-header>

Elementos

Nombre Descripción Obligatorio
check-header Elemento raíz.
value Valor del encabezado HTTP permitido. Cuando se especifican varios elementos de valor, el resultado de la comprobación se considera positivo en caso de coincidencia con cualquiera de los valores. No

Atributos

Nombre Descripción Obligatorio Valor predeterminado
failed-check-error-message Mensaje de error que se devuelve en el cuerpo de la respuesta HTTP si el encabezado no existe o tiene un valor no válido. Los caracteres especiales de este mensaje deben incluir los caracteres de escape correctos. N/D
failed-check-httpcode Código de estado HTTP que se devuelve si el encabezado no existe o tiene un valor no válido. N/D
header-name El nombre del encabezado HTTP que hay que comprobar. N/D
ignore-case Puede establecerse en True o False. Si se establece en True, se omite la presencia de mayúsculas/minúsculas cuando el valor del encabezado se compara con el conjunto de valores aceptables. N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: entrante y saliente

  • Ámbitos de la directiva: todos los ámbitos

Obtener un código de autorización

Use la directiva get-authorization-context para obtener contexto de autorización de una autorización (en versión preliminar) especificada y que se ha configurado en la instancia de API Management.

La directiva captura y almacena los tokens de autorización y actualización del proveedor de autorización configurado.

Si identity-type=jwt está configurado, es necesario validar un token JWT. El público de este token debe ser https://azure-api.net/authorization-manager.

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

<get-authorization-context
    provider-id="authorization provider id" 
    authorization-id="authorization id" 
    context-variable-name="variable name" 
    identity-type="managed | jwt"
    identity="JWT bearer token"
    ignore-error="true | false" />

Ejemplos

Ejemplo 1: Recuperación del token

<!-- Add to inbound policy. -->
<get-authorization-context 
    provider-id="github-01" 
    authorization-id="auth-01" 
    context-variable-name="auth-context" 
    identity-type="managed" 
    identity="@(context.Request.Headers["Authorization"][0].Replace("Bearer ", ""))"
    ignore-error="false" />
<!-- Return the token -->
<return-response>
    <set-status code="200" />
    <set-body template="none">@(((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</set-body>
</return-response>

Ejemplo 2: Recuperación del token con atributos establecidos dinámicamente

<!-- Add to inbound policy. -->
<get-authorization-context 
  provider-id="@(context.Request.Url.Query.GetValueOrDefault("authorizationProviderId"))" 
  authorization-id="@(context.Request.Url.Query.GetValueOrDefault("authorizationId"))" context-variable-name="auth-context" 
  ignore-error="false" 
  identity-type="managed" />
<!-- Return the token -->
<return-response>
    <set-status code="200" />
    <set-body template="none">@(((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</set-body>
</return-response>

Ejemplo 3: Adjuntar el token a la llamada de back-end

<!-- Add to inbound policy. -->
<get-authorization-context
    provider-id="github-01" 
    authorization-id="auth-01" 
    context-variable-name="auth-context" 
    identity-type="managed" 
    ignore-error="false" />
<!-- Attach the token to the backend call -->
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
</set-header>

Ejemplo 4: Obtener el token de la solicitud entrante y devolver el token

<!-- Add to inbound policy. -->
<get-authorization-context 
    provider-id="github-01" 
    authorization-id="auth-01" 
    context-variable-name="auth-context" 
    identity-type="jwt" 
    identity="@(context.Request.Headers["Authorization"][0].Replace("Bearer ", ""))"
    ignore-error="false" />
<!-- Return the token -->
<return-response>
    <set-status code="200" />
    <set-body template="none">@(((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</set-body>
</return-response>

Elementos

Nombre Descripción Obligatorio
get-authorization-context Elemento raíz.

Atributos

Nombre Descripción Obligatorio Valor predeterminado
provider-id El identificador de recursos del proveedor de autorización.
authorization-id El identificador del recurso de autorización.
context-variable-name El nombre de la variable de contexto que se va a recibir el Authorization objeto.
identity-type El tipo de identidad que se debe comprobar con la directiva de acceso de autorización.
- managed: identidad administrada del servicio de administración de API.
- jwt: token de portador JWT especificado en el atributo identity.
No administrado
identidad Un token de portador JWT de Azure AD que se va a comprobar con los permisos de autorización. Se omite para los identity-type que no sean jwt.

Notificaciones esperadas:
- público: https://azure-api.net/authorization-manager
- oid: Identificación del objeto de permiso
- tid: Identificación de inquilino de permiso
No
ignore-error booleano. Si la adquisición del contexto de autorización produce un error (por ejemplo, no se encuentra el recurso de autorización o está en un estado de error):
- true: a la variable de contexto se le asigna un valor NULL.
- false: devuelve 500
No false

Objeto de autorización

La variable de contexto de autorización recibe un objeto de tipo Authorization.

class Authorization
{
    public string AccessToken { get; }
    public IReadOnlyDictionary<string, object> Claims { get; }
}
Nombre de propiedad Descripción
AccessToken Token de acceso de portador para autorizar una solicitud HTTP de back-end.
Notificaciones Notificaciones devueltas por la API de respuesta de token del servidor de autorización (consulte RFC6749#section-5.1).

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)

  • Ámbitos de la directiva: todos los ámbitos

Limitar la tasa de llamadas por suscripción

La directiva rate-limit evita los picos de uso de la API según suscripción limitando la tasa de llamadas a un número especificado por un período de tiempo establecido. Cuando se supera la tasa de llamadas, el autor de la llamada recibe un código de estado de respuesta 429 Too Many Requests.

Para comprender la diferencia entre las cuotas y los límites de frecuencia, consulte Límites y cuotas de frecuencia.

Importante

  • Esta directiva se puede usar una sola vez por documento de directiva.
  • Las expresiones de directiva no se pueden usar en ninguno de los atributos para esta directiva.

Precaución

Debido a la naturaleza distribuida de la arquitectura de limitación, el límite de velocidad nunca es completamente preciso. La diferencia entre la cantidad configurada y la cantidad real de solicitudes permitidas varía según el volumen y la frecuencia de solicitudes, la latencia del back-end y otros factores.

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

<rate-limit calls="number" renewal-period="seconds">
    <api name="API name" id="API id" calls="number" renewal-period="seconds">
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" 
        retry-after-header-name="custom header name, replaces default 'Retry-After'" 
        retry-after-variable-name="policy expression variable name"
        remaining-calls-header-name="header name"  
        remaining-calls-variable-name="policy expression variable name"
        total-calls-header-name="header name"/>
    </api>
</rate-limit>

Ejemplo

En el ejemplo siguiente, el límite de tasa por suscripción es de 20 llamadas por 90 segundos. Después de cada ejecución de directiva, las llamadas restantes permitidas en el período de tiempo se almacenan en la variable remainingCallsPerSubscription.

<policies>
    <inbound>
        <base />
        <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementos

Nombre Descripción Requerido
rate-limit Elemento raíz.
api Agregue uno o varios de estos elementos para imponer un límite de tasa de llamadas a las API del producto. Los límites de tasa de llamadas a la API y al producto se aplican de forma independiente. Se puede hacer referencia a la API a través de name o id. Si se proporcionan ambos atributos, id se usará y name se omitirá. No
operation Agregue uno o varios de estos elementos para imponer un límite de tasa de llamadas a las operaciones de una API. Los límites de tasa de llamadas se aplican de forma independiente a la API, a la operación y al producto. Se puede hacer referencia a la operación a través de name o id. Si se proporcionan ambos atributos, id se usará y name se omitirá. No

Atributos

Nombre Descripción Obligatorio Valor predeterminado
name Nombre de la API a la que se va a aplicar un límite de tasa. N/D
calls Número total máximo de llamadas permitidas durante el intervalo de tiempo especificado en renewal-period. N/D
renewal-period La longitud en segundos de la ventana deslizante durante la cual el número de solicitudes permitidas no debe superar el valor especificado en calls. Valor máximo permitido: 300 segundos. N/D
retry-after-header-name Nombre de un encabezado de respuesta personalizado cuyo valor es el intervalo de reintento recomendado en segundos, después de que se supere la tasa de llamadas especificada. No Retry-After
retry-after-variable-name Nombre de una variable de expresión de directiva que almacena el intervalo de reintento recomendado en segundos después de que se supere la tasa de llamadas especificada. No N/D
remaining-calls-header-name Nombre de un encabezado de respuesta cuyo valor después de cada ejecución de directiva es el número de llamadas restantes permitidas para el intervalo de tiempo especificado en renewal-period. No N/D
remaining-calls-variable-name Nombre de una variable de expresión de directiva que después de cada ejecución de directiva almacena el número de llamadas restantes permitidas para el intervalo de tiempo especificado en renewal-period. No N/D
total-calls-header-name Nombre de un encabezado de respuesta cuyo valor es el valor especificado en calls. No N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)

  • Ámbitos de la directiva: product, api, operation (producto, API, operación)

Limitar la tasa de llamadas por clave

Importante

Esta característica no está disponible en el nivel Consumo de API Management.

La directiva rate-limit-by-key evita los picos de uso de la API según clave limitando la tasa de llamadas a un número especificado por un período de tiempo establecido. La clave puede tener un valor de cadena arbitrario y normalmente se proporciona mediante una expresión de directiva. Puede agregarse una condición de incremento opcional para especificar qué solicitudes se deben contar para este límite. Cuando se supera la tasa de llamadas, el autor de la llamada recibe un código de estado de respuesta 429 Too Many Requests.

Para comprender la diferencia entre las cuotas y los límites de frecuencia, consulte Límites y cuotas de frecuencia.

Para obtener más información y ver ejemplos de esta directiva, consulte Limitación avanzada de solicitudes con Azure API Management.

Precaución

Debido a la naturaleza distribuida de la arquitectura de limitación, el límite de velocidad nunca es completamente preciso. La diferencia entre la cantidad configurada y la cantidad real de solicitudes permitidas varía según el volumen y la frecuencia de solicitudes, la latencia del back-end y otros factores.

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

<rate-limit-by-key calls="number"
                   renewal-period="seconds"
                   increment-condition="condition"
                   increment-count="number"
                   counter-key="key value" 
                   retry-after-header-name="custom header name, replaces default 'Retry-After'" 
                   retry-after-variable-name="policy expression variable name"
                   remaining-calls-header-name="header name"  
                   remaining-calls-variable-name="policy expression variable name"
                   total-calls-header-name="header name"/> 

Ejemplo

En el ejemplo siguiente, El límite de tasa de 10 llamadas por 60 segundos se establece según la dirección IP del autor de la llamada. Después de cada ejecución de directiva, las llamadas restantes permitidas en el período de tiempo se almacenan en la variable remainingCallsPerIP.

<policies>
    <inbound>
        <base />
        <rate-limit-by-key  calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Request.IpAddress)"
              remaining-calls-variable-name="remainingCallsPerIP"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementos

Nombre Descripción Requerido
rate-limit-by-key Elemento raíz.

Atributos

Nombre Descripción Obligatorio Valor predeterminado
calls Número total máximo de llamadas permitidas durante el intervalo de tiempo especificado en renewal-period. Se permite la expresión de directivas. N/D
counter-key Clave que se usa para la directiva de límite de tasa. En cada valor de clave, se usa un único contador para todos los ámbitos en los que se configura la directiva. N/D
increment-condition Expresión booleana que especifica si la solicitud se debe contar para la tasa (true). No N/D
increment-count Número por el que aumenta el contador por solicitud. No 1
renewal-period La longitud en segundos de la ventana deslizante durante la cual el número de solicitudes permitidas no debe superar el valor especificado en calls. Se permite la expresión de directivas. Valor máximo permitido: 300 segundos. N/D
retry-after-header-name Nombre de un encabezado de respuesta personalizado cuyo valor es el intervalo de reintento recomendado en segundos, después de que se supere la tasa de llamadas especificada. No Retry-After
retry-after-variable-name Nombre de una variable de expresión de directiva que almacena el intervalo de reintento recomendado en segundos después de que se supere la tasa de llamadas especificada. No N/D
remaining-calls-header-name Nombre de un encabezado de respuesta cuyo valor después de cada ejecución de directiva es el número de llamadas restantes permitidas para el intervalo de tiempo especificado en renewal-period. No N/D
remaining-calls-variable-name Nombre de una variable de expresión de directiva que después de cada ejecución de directiva almacena el número de llamadas restantes permitidas para el intervalo de tiempo especificado en renewal-period. No N/D
total-calls-header-name Nombre de un encabezado de respuesta cuyo valor es el valor especificado en calls. No N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)

  • Ámbitos de la directiva: todos los ámbitos

Restringir IP de autor de llamada

La directiva ip-filter filtra (permite/deniega) llamadas de direcciones IP específicas o de intervalos de direcciones.

Nota:

La directiva filtra la dirección IP del autor de la llamada inmediato. Sin embargo, si API Management se hospeda detrás de Application Gateway, la directiva considera su dirección IP, no el originador de la solicitud de API. Actualmente, no se tienen en cuenta las direcciones IP de X-Forwarded-For.

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

<ip-filter action="allow | forbid">
    <address>address</address>
    <address-range from="address" to="address" />
</ip-filter>

Ejemplo

En el siguiente ejemplo, la directiva solo permite solicitudes provenientes de la única dirección IP o rango de direcciones IP especificadas.

<ip-filter action="allow">
    <address>13.66.201.169</address>
    <address-range from="13.66.140.128" to="13.66.140.143" />
</ip-filter>

Elementos

Nombre Descripción Requerido
ip-filter Elemento raíz.
address Especifica la dirección IP única por la que filtrar. Es necesario al menos un elemento address o address-range.
address-range from="address" to="address" Especifica un intervalo de direcciones IP por el que filtrar. Es necesario al menos un elemento address o address-range.

Atributos

Nombre Descripción Obligatorio Valor predeterminado
address-range from="address" to="address" Un intervalo de direcciones IP a las que permitir o denegar el acceso. Obligatorio cuando se utiliza el elemento address-range. N/D
ip-filter action="allow | forbid" Especifica si se deben permitir o no las llamadas para los intervalos y direcciones IP especificados. N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)
  • Ámbitos de la directiva: todos los ámbitos

Nota:

Si configura esta directiva en más de un ámbito, el filtrado IP se aplica en el orden de evaluación de directivas en la definición de su directiva.

Establecer cuota de uso por suscripción

La directiva quota aplica un volumen de llamadas o una cuota de ancho de banda renovables o permanentes por suscripción. Cuando se supera la cuota, el autor de la llamada recibe un código de estado de respuesta 403 Forbidden y la respuesta incluye un encabezado Retry-After cuyo valor es el intervalo de reintento recomendado en segundos.

Para comprender la diferencia entre las cuotas y los límites de frecuencia, consulte Límites y cuotas de frecuencia.

Importante

  • Esta directiva se puede usar una sola vez por documento de directiva.
  • Las expresiones de directiva no se pueden usar en ninguno de los atributos para esta directiva.

Nota

Cuando los recursos de proceso subyacentes se reinician en la plataforma de servicio, API Management pueden seguir administrando las solicitudes durante un breve período después de alcanzar una cuota.

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

<quota calls="number" bandwidth="kilobytes" renewal-period="seconds">
    <api name="API name" id="API id" calls="number">
        <operation name="operation name" id="operation id" calls="number" />
    </api>
</quota>

Ejemplo

<policies>
    <inbound>
        <base />
        <quota calls="10000" bandwidth="40000" renewal-period="3600" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementos

Nombre Descripción Requerido
quota Elemento raíz.
api Agregue uno o varios de estos elementos para imponer una cuota de llamadas a las API del producto. Las cuotas de llamada de API y de producto se aplican de forma independiente. Se puede hacer referencia a la API a través de name o id. Si se proporcionan ambos atributos, id se usará y name se omitirá. No
operation Agregue uno o varios de estos elementos para imponer una cuota de llamadas a las operaciones de una API. Las cuotas de llamadas de API, operación y producto se aplican de forma independiente. Se puede hacer referencia a la operación a través de name o id. Si se proporcionan ambos atributos, id se usará y name se omitirá. No

Atributos

Nombre Descripción Obligatorio Valor predeterminado
name Nombre de la API u operación a la que se aplica la cuota. N/D
bandwidth Número total máximo de kilobytes permitidos durante el intervalo de tiempo especificado en renewal-period. Debe especificarse calls, bandwidth o ambos. N/D
calls Número total máximo de llamadas permitidas durante el intervalo de tiempo especificado en renewal-period. Debe especificarse calls, bandwidth o ambos. N/D
renewal-period Longitud en segundos de la ventana fija después de la cual se restablece la cuota. El inicio de cada período se calcula en relación con la hora de inicio de la suscripción. Cuando renewal-period se establece en 0, el periodo se establece en infinito. N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)
  • Ámbitos de la directiva: producto

Establecer cuota de uso por clave

Importante

Esta característica no está disponible en el nivel Consumo de API Management.

La directiva quota-by-key aplica un volumen de llamadas o una cuota de ancho de banda por clave renovables o permanentes. La clave puede tener un valor de cadena arbitrario y normalmente se proporciona mediante una expresión de directiva. Puede agregarse una condición de incremento opcional para especificar qué solicitudes se cuentan para esta cuota. Si varias directivas incrementan el mismo valor de clave, se incrementa solo una vez por solicitud. Cuando se supera la cuota, el autor de la llamada recibe un código de estado de respuesta 403 Forbidden y la respuesta incluye un encabezado Retry-After cuyo valor es el intervalo de reintento recomendado en segundos.

Para obtener más información y ver ejemplos de esta directiva, consulte Limitación avanzada de solicitudes con Azure API Management.

Para comprender la diferencia entre las cuotas y los límites de frecuencia, consulte Límites y cuotas de frecuencia.

Nota

Cuando los recursos de proceso subyacentes se reinician en la plataforma de servicio, API Management pueden seguir administrando las solicitudes durante un breve período después de alcanzar una cuota.

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

<quota-by-key calls="number"
              bandwidth="kilobytes"
              renewal-period="seconds"
              increment-condition="condition"
              counter-key="key value"
              first-period-start="date-time" />

Ejemplo

En el ejemplo siguiente, la clave de la cuota se establece según la dirección IP del autor de la llamada.

<policies>
    <inbound>
        <base />
        <quota-by-key calls="10000" bandwidth="40000" renewal-period="3600"
                      increment-condition="@(context.Response.StatusCode >= 200 && context.Response.StatusCode < 400)"
                      counter-key="@(context.Request.IpAddress)" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Elementos

Nombre Descripción Requerido
quota Elemento raíz.

Atributos

Nombre Descripción Obligatorio Valor predeterminado
bandwidth Número total máximo de kilobytes permitidos durante el intervalo de tiempo especificado en renewal-period. Debe especificarse calls, bandwidth o ambos. N/D
calls Número total máximo de llamadas permitidas durante el intervalo de tiempo especificado en renewal-period. Debe especificarse calls, bandwidth o ambos. N/D
counter-key Clave que se usa para la directiva de cuota. En cada valor de clave, se usa un único contador para todos los ámbitos en los que se configura la directiva. N/D
increment-condition Expresión booleana que especifica si la solicitud se debe contar para la cuota (true). No N/D
renewal-period Longitud en segundos de la ventana fija después de la cual se restablece la cuota. El inicio de cada período se calcula en relación con first-perdiod-start. Cuando renewal-period se establece en 0, el periodo se establece en infinito. N/D
first-period-start Fecha y hora de inicio de los períodos de renovación de cuota en formato yyyy-MM-ddTHH:mm:ssZ, según lo especificado por el estándar ISO 8601. No 0001-01-01T00:00:00Z

Nota

El valor del atributo counter-key debe ser único en todas las API de API Management si no quiere compartir el total entre las demás API.

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)
  • Ámbitos de la directiva: todos los ámbitos

Validación de un token de Azure Active Directory

La directiva validate-azure-ad-token exige la existencia y validez de un token web JSON (JWT) proporcionado por el servicio Azure Active Directory. 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.

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>

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 mediante el esquema Bearer. En este ejemplo, el identificador de inquilino de Azure AD 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 Azure AD 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>

Elementos

Elemento Descripción Obligatorio
validate-azure-ad-token Elemento raíz.
audiences Contiene una lista de notificaciones de audiencia aceptables 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
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
client-application-ids Contiene una lista de identificadores de aplicaciones cliente aceptables. Si existen varios elementos 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. Debe especificarse al menos un elemento application-id.
required-claims Contiene una lista 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. No

Atributos

Nombre Descripción Obligatorio Valor predeterminado
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. No El mensaje de error predeterminado depende del problema de validación, por ejemplo, la notificación de la ausencia del elemento JWT.
failed-validation-httpcode Código de estado HTTP que se devuelve si el elemento JWT no supera la validación. No 401
header-name El nombre del encabezado HTTP que contiene el token. Se debe especificar uno de header-name, query-parameter-name o token-value. 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.
No todo
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 N/D
nombre del parámetro de consulta Nombre del parámetro de consulta que contiene el token. Se debe especificar uno de header-name, query-parameter-name o token-value. N/D
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
token-value Expresión que devuelve una cadena que contiene el token. No debe devolver Bearer como parte del valor del token. Se debe especificar uno de header-name, query-parameter-name o token-value. N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)
  • Ámbitos de la directiva: todos los ámbitos

Limitaciones

Esta directiva solo se puede usar con un inquilino de Azure Active Directory en la nube pública de Azure. No admite inquilinos configurados en nubes regionales o nubes de Azure con acceso restringido.

Validar JWT

La directiva validate-jwt exige que haya un token web JSON (JWT) 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.

Importante

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 validate-jwt es compatible con los algoritmos de firma HS256 y RS256. En el caso de HS256, la clave debe proporcionarse en línea dentro de la directiva con el formato de codificación Base64. En el caso de RS256, la clave se puede proporcionar mediante un punto de conexión de configuración de Open ID o con el identificador de un certificado cargado que contenga la clave pública o el par módulo-exponente de la clave pública pero en formato PFX. La directiva validate-jwt admite tokens cifrados con claves simétricas que utilicen los siguientes algoritmos de cifrado: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.

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, e.g. https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>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 values, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed values, then add additional value elements -->
  </required-claims>
</validate-jwt>

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

Nota

Use la directiva validate-azure-ad-token para validar tokens en 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/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" 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>d313c4e4-de5f-4197-9470-e509a2f0b806</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 validación de 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>

Elementos

Elemento Descripción Requerido
validate-jwt Elemento raíz.
audiences Contiene una lista de notificaciones de audiencia aceptables 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
issuer-signing-keys Lista de las claves de seguridad con codificación Base64 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). Los elementos de clave tienen un atributo id opcional que se utiliza para compararlo con la notificación kid.

También puede proporcionar una clave de firma de emisor mediante:

- certificate-id en formato <key certificate-id="mycertificate" /> para especificar el identificador de una entidad de certificado cargada en API Management
- El par módulo n y exponente e de RSA en formato <key n="<modulus>" e="<exponent>" /> para especificar los parámetros de RSA en formato codificado de base64url
No
decryption-keys Una lista de claves con codificación Base64 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. Los elementos de clave tienen un atributo id opcional que se utiliza para compararlo con la notificación kid.

También puede proporcionar una clave de descifrado mediante:

- certificate-id en formato <key certificate-id="mycertificate" /> para especificar el identificador de una entidad de certificado cargada en API Management
No
issuers Lista de entidades de seguridad aceptables 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
openid-config Agregue uno o varios de estos elementos para especificar un punto de conexión de configuración de OpenID compatible, desde el que se pueden 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.
No
required-claims Contiene una lista 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. No

Atributos

Nombre Descripción Obligatorio Valor predeterminado
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. No 0 segundos
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. No El mensaje de error predeterminado depende del problema de validación, por ejemplo, la notificación de la ausencia del elemento JWT.
failed-validation-httpcode Código de estado HTTP que se devuelve si el elemento JWT no pasa la validación. No 401
header-name El nombre del encabezado HTTP que contiene el token. 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 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 debe especificar uno de header-name, query-parameter-name o token-value. N/D
id El atributo id del elemento key le permite especificar la cadena que se comparará con la notificación kid del token (si existe) para averiguar qué clave debe usarse para validar la firma. No 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.
No todo
require-expiration-time booleano. Especifica si es necesaria una notificación de expiración en el token. 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. No N/D
require-signed-tokens booleano. Especifica si un token debe estar firmado. No true
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
url Dirección URL del punto de conexión de configuración de OpenID desde donde se pueden obtener los metadatos de configuración de OpenID. 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 Azure Active Directory, 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

sustituyendo el nombre o el identificador del inquilino del directorio, por ejemplo contoso.onmicrosoft.com, por {tenant-name}.
N/D
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 N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)
  • Ámbitos de la directiva: todos los ámbitos

Validación del certificado de cliente

Use la directiva validate-client-certificate para exigir que un certificado presentado por un cliente a una instancia de API Management coincida con notificaciones y reglas de validación especificadas como un firmante o un emisor de certificado para una o varias identidades de certificación.

Para considerarlo válido, un certificado de cliente debe coincidir con todas las reglas de validación que se definen en los atributos en el elemento de nivel superior y coincidir con todas las notificaciones definidas para, al menos, una de las identidades definidas.

Use esta directiva para comprobar las propiedades del certificado entrante con respecto a las propiedades deseadas. Use esta directiva también para invalidar la validación predeterminada de los certificados de cliente en estos casos:

  • Si cargó certificados de entidades de certificación personalizados para validar solicitudes de cliente en la puerta de enlace administrada.
  • Si configuró entidades de certificación personalizadas para validar solicitudes de cliente en una puerta de enlace autoadministrada.

Para más información sobre las entidades de certificación y los certificados de entidades de certificación personalizadas, consulte Incorporación de un certificado de entidad de certificación personalizado a Azure API Management.

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-client-certificate 
    validate-revocation="true|false"
    validate-trust="true|false" 
    validate-not-before="true|false" 
    validate-not-after="true|false" 
    ignore-error="true|false">
    <identities>
        <identity 
            thumbprint="certificate thumbprint"
            serial-number="certificate serial number"
            common-name="certificate common name"
            subject="certificate subject string"
            dns-name="certificate DNS name"
            issuer-subject="certificate issuer"
            issuer-thumbprint="certificate issuer thumbprint"
            issuer-certificate-id="certificate identifier" />
    </identities>
</validate-client-certificate> 

Ejemplo

En el ejemplo siguiente se valida un certificado de cliente para que coincida con las reglas de validación predeterminadas de la directiva y se comprueba si el nombre del firmante y el emisor coinciden con los valores especificados.

<validate-client-certificate 
    validate-revocation="true" 
    validate-trust="true" 
    validate-not-before="true" 
    validate-not-after="true" 
    ignore-error="false">
    <identities>
        <identity
            subject="C=US, ST=Illinois, L=Chicago, O=Contoso Corp., CN=*.contoso.com"
            issuer-subject="C=BE, O=FabrikamSign nv-sa, OU=Root CA, CN=FabrikamSign Root CA" />
    </identities>
</validate-client-certificate> 

Elementos

Elemento Descripción Requerido
validate-client-certificate Elemento raíz.
Identidades Contiene una lista de identidades con notificaciones definidas en el certificado de cliente. No

Atributos

Nombre Descripción Obligatorio Valor predeterminado
validate-revocation booleano. Especifica si el certificado se valida con la lista de revocación en línea.  No True
validate-trust booleano. Especifica si se debe generar un error de validación en caso de que la cadena no se pueda crear correctamente en una entidad de certificación de confianza. No True
validate-not-before booleano. Valida el valor con respecto a la hora actual. No True
validate-not-after booleano. Valida el valor con respecto a la hora actual. No True
ignore-error booleano. Especifica si la directiva debe continuar con el controlador siguiente o pasar al error si se genera un error en la validación. No False
identidad String. Combinación de valores de notificaciones de certificado que hacen que el certificado sea válido. N/D
thumbprint Huella digital del certificado. No N/D
serial-number Número de serie del certificado. No N/D
common-name Nombre común del certificado (parte de la cadena del firmante). No N/D
subject Cadena del firmante. Debe seguir el formato de nombre distintivo (DN). No N/D
dns-name Valor de la entrada dnsName dentro de la notificación Nombre alternativo del firmante. No N/D
issuer-subject Firmante del emisor. Debe seguir el formato de nombre distintivo (DN). No N/D
issuer-thumbprint Huella digital del emisor. No N/D
issuer-certificate-id Identificador de la entidad de certificación existente que representa la clave pública del emisor. Mutuamente excluyente con otros atributos del emisor. No N/D

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

  • Secciones de la directiva: inbound (entrada)
  • Ámbitos de la directiva: todos los ámbitos

Pasos siguientes

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