Política BasicAuthentication

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política BasicAuthentication permite-lhe usar a autenticação básica simples para a segurança do último quilómetro. A política usa um nome de utilizador e uma palavra-passe, codifica-os em Base64 e escreve o valor resultante numa variável. O valor resultante está no formato Basic Base64EncodedString. Normalmente, escreve este valor num cabeçalho HTTP, como o cabeçalho Authorization.

A política tem dois modos de funcionamento:

• Codificar: codifica em Base64 um nome de utilizador e uma palavra-passe armazenados em variáveis
• Decode: descodifica o nome de utilizador e a palavra-passe de uma string codificada em Base64

O nome de utilizador e a palavra-passe são normalmente armazenados no armazenamento de chaves/valores e, em seguida, lidos a partir do armazenamento de chaves/valores no momento da execução. Para ver detalhes sobre a utilização do armazenamento de chaves/valores, consulte a Política de operações de mapas de chaves-valores.

Esta política não aplica a autenticação básica a um pedido a um proxy de API. Em alternativa, use-o para codificar/descodificar credenciais como Base64, normalmente quando se liga a um servidor de back-end ou usa uma política de chamadas de serviço, como a política de chamadas de serviço, que requer autenticação básica.

Aviso: a autenticação básica não oferece confidencialidade. Envie sempre as credenciais através de uma ligação com TLS ativado (HTTPS) para o seu serviço de back-end.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Amostras

Codificação de saída

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

Na configuração de política de exemplo acima, o nome de utilizador e a palavra-passe a codificar são derivados das variáveis especificadas pelos atributos ref nos elementos <User> e <Password>. As variáveis têm de ser definidas antes da execução desta política. Normalmente, as variáveis são preenchidas com valores que são lidos a partir de um mapa de chave/valor. Consulte a Política de Operações de Mapeamento de Chaves-Valores.

Esta configuração resulta no cabeçalho HTTP denominado Authorization, conforme especificado pelo elemento <AssignTo>, a ser adicionado à mensagem de pedido de saída enviada para o servidor de back-end:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Os valores <User> e <Password> são concatenados com dois pontos antes da codificação Base64.

Considere que tem um mapa de chave/valor com a seguinte entrada:

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

Anexe as seguintes políticas KeyValueMapOperations antes da política BasicAuthentication para poder extrair os valores dos elementos <User> e <Password> da loja de chaves/valores e preenchê-los nas variáveis credentials.username e 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>
      

Descodificação 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>

Neste exemplo de política, a política descodifica o nome de utilizador e a palavra-passe do cabeçalho HTTP, conforme especificado pelo elemento <Source>.Authorization A string codificada em Base64 tem de estar no formato Basic Base64EncodedString.

A política escreve o nome de utilizador descodificado na variável request.header.username e a palavra-passe descodificada na variável request.header.password.

Referência do elemento

A referência do elemento descreve os elementos e os atributos da 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">

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <Operation>

Determina se a política codifica ou descodifica credenciais em Base64.

<Operation>Encode</Operation>

Predefinição:	N/A
Presença:	Obrigatória
Tipo:	String. Os valores válidos incluem: Codificar Descodificar

Elemento <IgnoreUnresolvedVariables>

Quando definida como true, a política não gera um erro se não for possível resolver uma variável. Quando usada no contexto de uma política BasicAuthentication, esta definição é normalmente definida como false porque é geralmente benéfico gerar um erro se não for possível encontrar um nome de utilizador ou uma palavra-passe nas variáveis especificadas.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Predefinição:	verdadeiro
Presença:	Opcional
Tipo:	Booleano

Elemento <User>

• Para a codificação, use o elemento <User> para especificar a variável que contém o nome de utilizador. Os valores do nome de utilizador e da palavra-passe são concatenados com dois pontos antes da codificação Base64.
• Para a descodificação, especifique a variável onde o nome de utilizador descodificado é escrito.

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

Predefinição:	N/A
Presença:	Obrigatória
Tipo:	N/A

Atributos

Atributo	Descrição	Predefinição	Presença
ref	A variável a partir da qual a política lê dinamicamente o nome de utilizador (codificar) ou escreve o nome de utilizador (descofificar).	N/A	Obrigatória

Elemento <Password>

• Para a codificação, use o elemento <Password> para especificar a variável que contém a palavra-passe.
• Para a descodificação, especifique a variável onde a palavra-passe descodificada é escrita.

<Password ref="request.queryparam.password" />

Predefinição:	N/A
Presença:	Obrigatória
Tipo:	N/A

Atributos

Atributo	Descrição	Predefinição	Presença
ref	A variável a partir da qual a política lê dinamicamente a palavra-passe (codificar) ou escreve a palavra-passe (descofificar).	N/A	Obrigatória

Elemento <AssignTo>

Especifica a variável de destino a definir com o valor codificado ou descodificado gerado por esta política.

O exemplo seguinte indica que a política deve definir o cabeçalho Authorization da mensagem para o valor gerado:

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

Predefinição:	N/A
Presença:	Obrigatória
Tipo:	String

Atributos

Atributo	Descrição	Predefinição	Presença
createNew	Determina se a política deve substituir a variável se a variável já estiver definida. Quando "false", a atribuição à variável ocorre apenas se a variável não estiver atualmente definida (nula). Quando é "true", a atribuição à variável ocorre sempre. Normalmente, define este atributo como "false" (predefinição).	falso	Opcional

Elemento <Source>

Para a descodificação, a variável que contém a string codificada em Base64, no formato Basic Base64EncodedString. Por exemplo, especifique request.header.Authorization, correspondente ao cabeçalho Autorização.

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

Predefinição:	N/A
Presença:	Obrigatório para a operação Decode.
Tipo:	N/A

Variáveis de fluxo

A seguinte variável de fluxo é definida quando a política falha:

• BasicAuthentication.{policy_name}.failed (com um valor verdadeiro)

Nota: se vir variáveis denominadas BasicAuthentication.{policy_name}.fault.cause e BasicAuthentication.{policy_name}.fault.name, não estão a ser usadas atualmente pelo Apigee.

Referência de erro

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

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

Tópicos relacionados

Política de Operações do Mapa de Chaves-Valores