Política BasicAuthentication

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

Consulta la documentación de Apigee Edge.

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.

Nota: Esta política no aplica la autenticación básica en una solicitud a un proxy de API. En cambio, lo usas para codificar o decodificar credenciales en Base64, por lo general, cuando te conectas a un servidor de backend o usas una política de texto destacado de servicio, como la política de solicitud de oferta de servicio, que requiere autenticación básica.

Nota: En los siguientes videos, se muestra el Editor de proxies clásico en la IU de Apigee. Apigee presenta una versión nueva del Editor de proxies, que tiene un diseño diferente al de la versión clásica que se muestra en los videos.

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.

Advertencia: La autenticación básica no proporciona confidencialidad. Siempre envía credenciales mediante una conexión habilitada para TLS (HTTPS) a tu servicio de backend.

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	Configuración predeterminada	Presence
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.	N/A	Obligatorio
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. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	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	Obsoleto

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>

Configuración predeterminada	N/A Si omites este elemento, se usa el valor del atributo name de la política.
Presence	Opcional
Tipo	String

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)

Nota: Si ves variables llamadas BasicAuthentication.{policy_name}.fault.cause y BasicAuthentication.{policy_name}.fault.name, actualmente no utilizas por Apigee.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee 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 (por ejemplo, no comienza con Basic).
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

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

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

Muestra: Consulta nuestros repositorios de GitHub para ver los esquemas más recientes.

Temas relacionados

Política de operaciones de mapas de clave-valor