Política BasicAuthentication

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

Veja a documentação do Apigee Edge.

O quê

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 autorização.

A política também permite descodificar credenciais armazenadas numa string codificada em Base64 num nome de utilizador e numa palavra-passe.

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.

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

Nota: os vídeos seguintes mostram o editor de proxy clássico na IU do Apigee. A Apigee está a introduzir uma nova versão do Proxy Editor, que tem um design diferente da versão clássica apresentada nos vídeos.

Vídeo: este vídeo demonstra como codificar em base64 um nome de utilizador e uma palavra-passe através da política de autenticação básica.

Vídeo: este vídeo demonstra como descodificar um nome de utilizador e uma palavra-passe com codificação base64 usando a política de autenticação básica.

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 chaves-valores 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.

---

Acerca da política de autenticação básica

A política tem dois modos de funcionamento:

• Codificar: o Base64 codifica 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 arquivo de chave/valor e, em seguida, lidos a partir do arquivo de chave/valor 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.

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.

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 (descodificar).	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 Authorization.

<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

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes se estiver a desenvolver regras de falhas para resolver erros. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha	Estado de HTTP	Causa	Corrigir
steps.basicauthentication.InvalidBasicAuthenticationSource	500	Numa descodificação, quando a string codificada Base64 recebida não contém um valor válido ou o cabeçalho tem um formato incorreto (por exemplo, não começa com Basic).
steps.basicauthentication.UnresolvedVariable	500	As variáveis de origem necessárias para a descodificação ou a codificação não estão presentes. Este erro só pode ocorrer se IgnoreUnresolvedVariables for falso.

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Nome do erro	Ocorre quando	Corrigir
UserNameRequired	O elemento <User> tem de estar presente para a operação com nome.
PasswordRequired	O elemento <Password> tem de estar presente para a operação com nome.
AssignToRequired	O elemento <AssignTo> tem de estar presente para a operação com nome.
SourceRequired	O elemento <Source> tem de estar presente para a operação com nome.

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	BasicAuthentication.BA-Authenticate.failed = true

Exemplo de resposta de erro

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque pode mudar.

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

Exemplo de regra de falha

<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