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

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
steps.basicauthentication.InvalidBasicAuthenticationSource	500	On a decode when the incoming Base64 encoded string does not contain a valid value or the header is malformed (for example, does not start with Basic).
steps.basicauthentication.UnresolvedVariable	500	The required source variables for the decode or encode are not present. This error can only occur if IgnoreUnresolvedVariables is false.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Occurs when	Fix
UserNameRequired	The <User> element must be present for the named operation.
PasswordRequired	The <Password> element must be present for the named operation.
AssignToRequired	The <AssignTo> element must be present for the named operation.
SourceRequired	The <Source> element must be present for the named operation.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	BasicAuthentication.BA-Authenticate.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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