Política BasicAuthentication

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Qué

Te permite usar la autenticación básica ligera para la seguridad de la red de acceso. La política toma un nombre de usuario y una contraseña, Base64 los codifica y escribe el valor resultante en una variable. El valor resultante tiene la forma Basic Base64EncodedString. Por lo general, escribes este valor en un encabezado HTTP, como el encabezado Authorization.

La política también te permite decodificar las credenciales almacenadas en una string codificada en Base64 en un nombre de usuario y una contraseña.

Video: En este video, se muestra cómo codificar un nombre de usuario y una contraseña en Base64 con la política de autenticación básica.

Video: En este video, se muestra cómo decodificar un nombre de usuario y contraseña codificados en Base64 mediante la política de autenticación básica.

Ejemplos

Codificación saliente

<BasicAuthentication name="ApplyBasicAuthHeader">
   <DisplayName>ApplyBasicAuthHeader</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="BasicAuth.credentials.username" />
   <Password ref="BasicAuth.credentials.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
</BasicAuthentication>

En la configuración de la política de muestra anterior, el nombre de usuario y la contraseña que se codificarán se derivan de las variables especificadas por los atributos ref en los elementos <User> y <Password>. Las variables se deben configurar antes de que se ejecute esta política. Por lo general, las variables se propagan con valores que se leen desde un mapa de par clave-valor. Consulta la política de operaciones de mapas de par clave-valor.

Esta configuración da como resultado el encabezado HTTP llamado Authorization, como se especifica en el elemento <AssignTo> y se agrega al mensaje de solicitud saliente enviado al servidor de backend:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Los valores <User> y <Password> se concatenan con dos puntos antes de la codificación en Base64.

Considera que tienes un mapa de par clave-valor con la siguiente entrada:

{
  "encrypted" : true,
  "entry" : [ {
    "name" : "username",
    "value" : "MyUsername"
  }, {
    "name" : "password",
    "value" : "MyPassword"
  } ],
  "name" : "BasicAuthCredentials"
}
      

Adjunta las siguientes políticas KeyValueMapOperations antes de la política BasicAuthentication para poder extraer los valores de tus elementos <User> y <Password> del almacén de par clave-valor y propagarlos en las variables credentials.username y credentials.password.

<KeyValueMapOperations name="getCredentials" mapIdentifier="BasicAuthCredentials">
  <Scope>apiproxy</Scope>
  <Get assignTo="credentials.username" index='1'>
    <Key>
      <Parameter>username</Parameter>
    </Key>
  </Get>
  <Get assignTo="credentials.password" index='1'>
    <Key>
      <Parameter>password</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
      

Decodificación de entrada

<BasicAuthentication name="DecodeBaseAuthHeaders">
   <DisplayName>Decode Basic Authentication Header</DisplayName>
   <Operation>Decode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.header.username" />
   <Password ref="request.header.password" />
   <Source>request.header.Authorization</Source>
</BasicAuthentication>

En esta política de muestra, la política decodifica el nombre de usuario y la contraseña del encabezado HTTP Authorization, como se especifica en el elemento <Source>. La string codificada en base64 debe tener el formato Basic Base64EncodedString..

La política escribe el nombre de usuario decodificado en la variable request.header.username y la contraseña decodificada en la variable request.header.password.


Información sobre la política de autenticación básica

La política tiene dos modos de operaciones:

  • Codificación: codifica en Base64 un nombre de usuario y una contraseña almacenados en variables
  • Decodificación: decodifica el nombre de usuario y la contraseña a partir de una string codificada en Base64

Por lo general, el nombre de usuario y la contraseña se almacenan en el almacén de clave-valor y, luego, se leen desde el almacén de clave-valor en el entorno de ejecución. Para obtener detalles sobre el uso del almacén de clave-valor, consulta Política de operaciones de mapas de valores clave.

Referencia del elemento

En la referencia del elemento, se describen los elementos y atributos de la política BasicAuthentication.

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">
   <DisplayName>Basic Authentication 1</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.queryparam.username" />
   <Password ref="request.queryparam.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
   <Source>request.header.Authorization</Source> 
</BasicAuthentication>

Atributos de <BasicAuthentication>

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo Descripción Predeterminada Presencia
name

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

No disponible Obligatorias
continueOnError

Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle.

false Opcional
enabled

Configúralo como true para aplicar la política.

Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.

true Opcional
async

Este atributo dejó de estar disponible.

false Funciones obsoletas

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>
Predeterminada

No disponible

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia Opcional
Tipo Cadena

Elemento <Operation>

Determina si la política de Base64 codifica o decodifica de credenciales.

<Operation>Encode</Operation>
Predeterminado: No disponible
Presencia: Obligatorias
Tipo:

String.

Estos son algunos de los valores válidos:

  • Codifica
  • Decodifica

Elemento <IgnoreUnresolvedVariables>

Cuando se establece en true, la política no mostrará un error si no se puede resolver una variable. Cuando se usa en el contexto de una política BasicAuthentication, esta configuración suele establecerse en false, ya que suele ser beneficioso arrojar un error si no se puede encontrar un nombre de usuario o una contraseña en las variables especificadas.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Predeterminado: true
Presencia: Opcional
Tipo:

Booleano

Elemento <User>

  • Para la codificación, usa el elemento <User> a fin de especificar la variable que contiene el nombre de usuario. Los valores de nombre de usuario y contraseña se concatenan con dos puntos antes de la codificación Base64.
  • Para la decodificación, especifica la variable en la que se escribe el nombre de usuario decodificado.
<User ref="request.queryparam.username" /> 
Predeterminado: No disponible
Presencia: Obligatorias
Tipo:

No disponible

Atributos

Atributo Descripción Predeterminada Presencia
ref

La variable desde la cual la política lee el nombre de usuario (codificar) de forma dinámica o escribe el nombre de usuario (decodificar).

No disponible Obligatorias

Elemento <PassWord>

  • Para la codificación, usa el elemento <Password> a fin de especificar la variable que contiene la contraseña.
  • Para la decodificación, especifica la variable en la que se escribe la contraseña decodificada.
<Password ref="request.queryparam.password" />
Predeterminado: No disponible
Presencia: Obligatorias
Tipo:

No disponible

Atributos

Atributo Descripción Predeterminada Presencia
ref

La variable desde la cual la política lee la contraseña (codificar) de forma dinámica o escribe la contraseña (decodificar).

No disponible Obligatorio

Elemento <AssignTo>

Especifica la variable de destino que se establece con el valor codificado o decodificado que genera esta política.

En el siguiente ejemplo, se indica que la política debe establecer el encabezado Authorization del mensaje en el valor generado:

<AssignTo createNew="false">request.header.Authorization</AssignTo>
Predeterminado: No disponible
Presencia: Obligatorias
Tipo:

Cadena

Atributos

Atributo Descripción Predeterminada Presence
createNew Determina si la política debe reemplazar la variable si ya está configurada.

Cuando es "false", la asignación a la variable se produce solamente si la variable está actualmente sin configurar (nulo).

Cuando es “true”, la asignación a la variable siempre ocurre.

Normalmente, estableces este atributo en "false" (el valor predeterminado).

false Opcional

Elemento <Source>

Para la decodificación, la variable que contiene la string codificada en Base64, con el formato Basic Base64EncodedString. Por ejemplo, especifica request.header.Authorization, que corresponde al encabezado Authorization.

<Source>request.header.Authorization</Source>
Predeterminado: No disponible
Presencia: Obligatorio para la operación de decodificación.
Tipo:

No disponible

Variables de flujo

La siguiente variable de flujo se establece cuando falla la política:

  • BasicAuthentication.{policy_name}.failed (con un valor true)

Referencia de errores

En esta sección, se describen los códigos y mensajes de error que se muestran y las variables de fallas que establece Edge cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de controlar errores. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Causa Corregir
steps.basicauthentication.InvalidBasicAuthenticationSource 500 En una decodificación cuando la string codificada Base64 entrante no contiene un valor válido o el encabezado tiene un formato incorrecto (p.ej., no comienza con "Básico").
steps.basicauthentication.UnresolvedVariable 500 Las variables de origen necesarias para la decodificación o codificación no están presentes. Este error solo puede ocurrir si IgnoreUnresolvedVariables es falso.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error Ocurre cuando Corregir
UserNameRequired El elemento <User> debe estar presente para la operación con nombre.
PasswordRequired El elemento <Password> debe estar presente para la operación con nombre.
AssignToRequired El elemento <AssignTo> debe estar presente para la operación con nombre.
SourceRequired El elemento <Source> debe estar presente para la operación con nombre.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. BasicAuthentication.BA-Authenticate.failed = true

Ejemplo de respuesta de error

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

Ejemplo de regla de falla

<FaultRule name="Basic Authentication Faults">
    <Step>
        <Name>AM-UnresolvedVariable</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Step>
        <Name>AM-AuthFailedResponse</Name>
        <Condition>(fault.name = "InvalidBasicAuthenticationSource")</Condition>
    </Step>
    <Condition>(BasicAuthentication.BA-Authentication.failed = true) </Condition>
</FaultRule>

Esquemas

Temas relacionados

Política de operaciones de mapas de clave-valor