Política BasicAuthentication

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

Consulta la documentación de Apigee Edge.

La política BasicAuthentication te permite usar la autenticación básica, que es un método ligero, para proteger la última milla. La política toma un nombre de usuario y una contraseña, los codifica en Base64 y escribe el valor resultante en una variable. El valor resultante tiene el formato Basic Base64EncodedString. Normalmente, este valor se escribe en un encabezado HTTP, como el encabezado Authorization.

La política tiene dos modos de funcionamiento:

Codificar: codifica en Base64 un nombre de usuario y una contraseña almacenados en variables.
Decodificar: decodifica el nombre de usuario y la contraseña de una cadena codificada en Base64.

El nombre de usuario y la contraseña se suelen almacenar en el almacén de pares clave-valor y, a continuación, se leen de él en tiempo de ejecución. Para obtener información sobre cómo usar el almacén de clave-valor, consulta la política Operaciones de mapa de clave-valor.

Esta política no aplica la autenticación básica en una solicitud a un proxy de API. En su lugar, úsala para codificar o decodificar credenciales como Base64, normalmente cuando te conectes a un servidor backend o utilices una política de llamada de servicio, como la política de llamada de servicio, que requiere autenticación básica.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Ejemplos

Codificación de salida

<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 ejemplo anterior, el nombre de usuario y la contraseña que se van a codificar se derivan de las variables especificadas por los atributos ref de los elementos <User> y <Password>. Las variables deben definirse antes de que se ejecute esta política. Normalmente, las variables se rellenan con valores que se leen de un mapa de clave/valor. Consulta la política de operaciones de mapas de clave-valor.

Esta configuración da como resultado el encabezado HTTP llamado Authorization, tal como se especifica en el elemento <AssignTo>, que se añade al mensaje de solicitud de salida enviado al servidor backend:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

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

Supongamos que tienes un mapa de 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 los elementos <User> y <Password> del almacén de claves/valores y rellenarlos 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 este ejemplo de política, la política decodifica el nombre de usuario y la contraseña del encabezado HTTP Authorization, tal como se especifica en el elemento <Source>. La cadena 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.

Referencia de elemento

En la referencia de elementos 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 <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: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual	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

Predeterminado	N/A Si omite este elemento, se usará el valor del atributo `name` de la política.
Presencia	Opcional
Tipo	Cadena

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 codifica o decodifica las credenciales en Base64.

<Operation>Encode</Operation>

Valor predeterminado:

N/A

Presencia:

Obligatorio

Tipo:

Cadena.

A continuación se muestran los valores válidos.

Codificar
Decodificar

Elemento <IgnoreUnresolvedVariables>

Si se le asigna el valor true, la política no generará un error si no se puede resolver una variable. Cuando se usa en el contexto de una política BasicAuthentication, esta opción suele tener el valor false, ya que suele ser útil generar un error si no se encuentra un nombre de usuario o una contraseña en las variables especificadas.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Valor predeterminado:	true
Presencia:	Opcional
Tipo:	Booleano

Elemento <User>

Para la codificación, usa el elemento <User> para 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 descodificar, especifica la variable en la que se escribe el nombre de usuario descodificado.

<User ref="request.queryparam.username" />

Valor predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia
ref	Variable desde la que la política lee de forma dinámica el nombre de usuario (codificación) o escribe el nombre de usuario (decodificación).	N/A	Obligatorio

Elemento <Password>

Para la codificación, use el elemento <Password> para 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" />

Valor predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	N/A

Atributos

Atributo	Descripción	Predeterminado	Presencia
ref	La variable de la que la política lee dinámicamente la contraseña (codificar) o en la que escribe la contraseña (decodificar).	N/A	Obligatorio

Elemento <AssignTo>

Especifica la variable de destino que se va a definir con el valor codificado o decodificado generado por esta política.

En el siguiente ejemplo se indica que la política debe asignar al encabezado Authorization del mensaje el valor generado:

<AssignTo createNew="false">request.header.Authorization</AssignTo>

Valor predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	Cadena

Atributos

Atributo	Descripción	Predeterminado	Presencia
createNew	Determina si la política debe sobrescribir la variable si ya se ha definido. Si el valor es "false", la asignación a la variable se produce solo si la variable no está definida (es nula). Si el valor es "true", la asignación a la variable siempre se produce. Normalmente, este atributo tiene el valor "false" (el valor predeterminado).	falso	Opcional

Atributo

Descripción

Predeterminado

Presencia

createNew

Determina si la política debe sobrescribir la variable si ya se ha definido.

Si el valor es "false", la asignación a la variable se produce solo si la variable no está definida (es nula).

Si el valor es "true", la asignación a la variable siempre se produce.

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

falso

Opcional

Elemento <Source>

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

<Source>request.header.Authorization</Source>

Valor predeterminado:	N/A
Presencia:	Obligatorio para la operación de decodificación.
Tipo:	N/A

Variables de flujo

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

BasicAuthentication.{policy_name}.failed (con el valor true)

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

Temas relacionados

Política de operaciones de mapa de valores clave

Política BasicAuthentication Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Ejemplos

Codificación de salida

Decodificación de entrada

Referencia de elemento

Atributos <BasicAuthentication>

Elemento <DisplayName>

Elemento <Operation>

Elemento <IgnoreUnresolvedVariables>

Elemento <User>

Atributos

Elemento <Password>

Atributos

Elemento <AssignTo>

Atributos

Elemento <Source>

Variables de flujo

Referencia de errores

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Esquemas

Temas relacionados

Política BasicAuthentication