Directivas de autenticación de Azure API Management
En este artículo se proporciona una referencia para las directivas de API Management que se usan para la autenticación con back-end de API.
Más información sobre las directivas:
- Introducción a las directivas
- Establecimiento o edición de directivas
- Expresiones de directiva
- Referencia de directivas para una lista completa de instrucciones de directivas y su configuración
Directivas de autenticación
Autenticar con opción básica : autenticar con un servicio de back-end mediante la autenticación básica.
Autenticar con certificado de cliente : autenticar con un servicio de back-end mediante certificados de cliente.
Autenticar con identidad administrada: autenticar con una identidad administrada para el servicio API Management.
Autenticar con básica
Use la directiva authentication-basic para realizar la autenticación con un servicio de back-end mediante autenticación Básica. Esta directiva establece eficazmente el encabezado de autorización HTTP en el valor correspondiente a las credenciales proporcionadas en la directiva.
Nota:
Establezca los elementos de una directiva y los elementos secundarios en el orden proporcionado en la instrucción policy. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.
Instrucción de la directiva
<authentication-basic username="username" password="password" />
Ejemplo
<authentication-basic username="testuser" password="testpassword" />
Elementos
| Nombre | Descripción | Obligatorio |
|---|---|---|
| authentication-basic | Elemento raíz. | Sí |
Atributos
| Nombre | Descripción | Obligatorio | Valor predeterminado |
|---|---|---|---|
| username | Especifica el nombre de usuario de la credencial básica. | Sí | N/D |
| password | Especifica la contraseña de usuario de la credencial básica. | Sí | 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
Autenticar con certificado de cliente
Use la directiva authentication-certificate para realizar la autenticación con un servicio de back-end mediante un certificado de cliente. El certificado se debe instalar en API Management primero y se identifica mediante su huella digital o id. de certificado (nombre del recurso).
Precaución
Si el certificado hace referencia a un certificado almacenado en Azure Key Vault, se identifica mediante el id. de certificado. Cuando se gira un certificado de Key Vault, su huella digital en API Management cambiará, por lo que la directiva no resolverá el nuevo certificado si se identifica mediante la huella digital.
Nota:
Establezca los elementos de una directiva y los elementos secundarios en el orden proporcionado en la instrucción policy. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.
Instrucción de la directiva
<authentication-certificate thumbprint="thumbprint" certificate-id="resource name"/>
Ejemplos
En este ejemplo, el certificado de cliente se identifica mediante el id. de certificado:
<authentication-certificate certificate-id="544fe9ddf3b8f30fb490d90f" />
En este ejemplo, el certificado de cliente se identifica mediante su huella digital:
<authentication-certificate thumbprint="CA06F56B258B7A0D4F2B05470939478651151984" />
En este ejemplo, el certificado de cliente se establece en la directiva en lugar de recuperarlo del almacén de certificados integrado:
<authentication-certificate body="@(context.Variables.GetValueOrDefault<byte[]>("byteCertificate"))" password="optional-certificate-password" />
Elementos
| Nombre | Descripción | Obligatorio |
|---|---|---|
| authentication-certificate | Elemento raíz. | Sí |
Atributos
| Nombre | Descripción | Obligatorio | Valor predeterminado |
|---|---|---|---|
| thumbprint | La huella digital del certificado de cliente. | thumbprint o certificate-id debe estar presente. |
N/D |
| certificate-id | Nombre del recurso de certificado. | thumbprint o certificate-id debe estar presente. |
N/D |
| body | Certificado de cliente como matriz de bytes. | No | N/D |
| password | Contraseña del certificado de cliente. | Se usa si el certificado especificado en body está protegido por contraseña. |
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
Autenticación con una identidad administrada
Use la directiva authentication-managed-identity para realizar la autenticación con un servicio de back-end mediante la identidad administrada. En esencia, esta directiva usa la identidad administrada para obtener un token de acceso de Azure Active Directory para acceder al recurso especificado. Después de obtener el token correctamente, la Directiva establecerá el valor del token en el Authorization encabezado mediante el esquema Bearer.
Para solicitar el token, se puede usar tanto la identidad asignada por el sistema como cualquiera de las distintas identidades asignadas por el usuario. Si no se proporciona client-id, se presupone la identidad asignada por el sistema. Si se proporciona la variable client-id, se solicita el token para esa identidad asignada por el usuario de Azure Active Directory.
Nota:
Establezca los elementos de una directiva y los elementos secundarios en el orden proporcionado en la instrucción policy. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.
Instrucción de la directiva
<authentication-managed-identity resource="resource" client-id="clientid of user-assigned identity" output-token-variable-name="token-variable" ignore-error="true|false"/>
Ejemplo
Uso de una identidad administrada para autenticación con un servicio back-end
<authentication-managed-identity resource="https://graph.microsoft.com"/>
<authentication-managed-identity resource="https://management.azure.com/"/> <!--Azure Resource Manager-->
<authentication-managed-identity resource="https://vault.azure.net"/> <!--Azure Key Vault-->
<authentication-managed-identity resource="https://servicebus.azure.net/"/> <!--Azure Service Bus-->
<authentication-managed-identity resource="https://storage.azure.com/"/> <!--Azure Blob Storage-->
<authentication-managed-identity resource="https://database.windows.net/"/> <!--Azure SQL-->
<authentication-managed-identity resource="AD_application_id"/> <!--Application (client) ID of your own Azure AD Application-->
Uso de una identidad administrada y establecimiento manual de un encabezado
<authentication-managed-identity resource="AD_application_id"
output-token-variable-name="msi-access-token" ignore-error="false" /> <!--Application (client) ID of your own Azure AD Application-->
<set-header name="Authorization" exists-action="override">
<value>@("Bearer " + (string)context.Variables["msi-access-token"])</value>
</set-header>
Uso de una identidad administrada en una directiva send-request
<send-request mode="new" timeout="20" ignore-error="false">
<set-url>https://example.com/</set-url>
<set-method>GET</set-method>
<authentication-managed-identity resource="ResourceID"/>
</send-request>
Elementos
| Nombre | Descripción | Obligatorio |
|---|---|---|
| authentication-managed-identity | Elemento raíz. | Sí |
Atributos
| Nombre | Descripción | Obligatorio | Valor predeterminado |
|---|---|---|---|
| resource | String. Identificador de aplicación de la API web de destino (recurso seguro) en Azure Active Directory. | Sí | N/D |
| client-id | String. El id. de aplicación de la identidad asignada por el usuario en Azure Active Directory. | No | identidad asignada por el sistema |
| output-token-variable-name | String. Nombre de la variable de contexto que recibirá el valor del token como un tipo de objeto string. |
No | N/D |
| ignore-error | booleano. Si se establece en true, la canalización de directivas seguirá ejecutándose incluso si no se obtiene un token de acceso. |
No | false |
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:
- 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
- Ejemplos de directivas