Política BasicAuthentication

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

ícono de política

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.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

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.

Muestras

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 superiores de la política:

Atributo Descripción Predeterminado 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.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

 N/A Obligatorio
continueOnError

Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas.

Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:

 falso Opcional
enabled

Asigna el valor true para aplicar la política.

Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.

 true Opcional
async

Este atributo está obsoleto.

 falso Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>
Predeterminado

N/A

Si omite este elemento, se usará 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: N/A
Presencia: Obligatorio
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: N/A
Presencia: Obligatorio
Tipo:

N/A

Atributos

Atributo Descripción Predeterminado Presence
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).

 N/A Obligatorio

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: N/A
Presencia: Obligatorio
Tipo:

N/A

Atributos

Atributo Descripción Predeterminado Presence
ref

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

 N/A 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: N/A
Presencia: Obligatorio
Tipo:

String

Atributos

Atributo Descripción Predeterminado 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: N/A
Presencia: Obligatorio para la operación de decodificación.
Tipo:

N/A

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 de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante conocer esta información si vas a desarrollar reglas de errores para gestionar errores. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

Código de fallo Estado de HTTP Causa Solucionar
steps.basicauthentication.InvalidBasicAuthenticationSource 500 En una decodificación, cuando la cadena codificada Base64 entrante no contiene un valor válido o el encabezado tiene un formato incorrecto (por ejemplo, no empieza por Basic).
steps.basicauthentication.UnresolvedVariable 500 No están presentes las variables de origen necesarias para la decodificación o la codificación. Este error solo puede producirse si IgnoreUnresolvedVariables es false.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Nombre del error Se produce cuando Solucionar
UserNameRequired El elemento <User> debe estar presente en la operación con nombre.
PasswordRequired El elemento <Password> debe estar presente en la operación con nombre.
AssignToRequired El elemento <AssignTo> debe estar presente en la operación con nombre.
SourceRequired El elemento <Source> debe estar presente en la operación con nombre.

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

Variables Dónde Ejemplo
fault.name="fault_name" fault_name es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error. fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name es el nombre de la política especificado por el usuario que ha provocado el error. BasicAuthentication.BA-Authenticate.failed = true

Ejemplo de respuesta de error

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

Regla de error de ejemplo

<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