Política BasicAuthentication

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

O que

Permite usar a autenticação básica leve para maior segurança. A política usa um nome de usuário e uma senha, a Base64 os codifica e grava o valor resultante em uma variável. O valor resultante está no formato Basic Base64EncodedString. Normalmente, esse valor é gravado em um cabeçalho HTTP, como Autorização.

A política também permite decodificar as credenciais armazenadas em uma string codificada em Base64 em um nome de usuário e uma senha.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Observação: essa política não aplica a autenticação básica a uma solicitação para um proxy de API. Em vez disso, você o usa para codificar credenciais de decodificação/decodificação Base64, geralmente ao se conectar a um servidor de back-end ou usar uma política de destaque de serviço, como a política de destaque de serviço, que requer autenticação básica.

Observação: os vídeos a seguir mostram o editor proxy clássico na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada nos vídeos.

Vídeo: este vídeo demonstra como codificar um nome de usuário e senha em base64 usando a política de autenticação básica.

Vídeo: este vídeo demonstra como decodificar um nome de usuário e uma senha codificados em 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 da política de amostra acima, o nome de usuário e a senha a serem codificados são derivados das variáveis especificadas pelos atributos ref nos elementos <User> e <Password>. As variáveis precisam ser definidas antes da execução dessa política. Normalmente, as variáveis são preenchidas por valores lidos em um mapa de chave-valor. Consulte a política de operações de mapeamento de chave-valor.

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

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

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

Considere que você 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 extrair os valores dos elementos <User> e <Password> do armazenamento de chave-valor e preenchê-los para as 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>
      

Decodificaçã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>

Nesta amostra de política, a política decodifica o nome de usuário e a senha do cabeçalho HTTP Authorization, conforme especificado pelo elemento <Source>. A string codificada em Base64 precisa estar no formato Basic Base64EncodedString.

A política grava o nome de usuário decodificado na variável request.header.username e a senha decodificada na variável request.header.password.

---

Sobre a política de autenticação básica

A política tem dois modos de operações:

• Encode: a Base64 codifica um nome de usuário e uma senha armazenados nas variáveis.
• Decode: decodifica o nome de usuário e a senha de uma string codificada em Base64.

Geralmente, o nome de usuário e a senha são armazenados no armazenamento de chave/valor e, em seguida, leem a partir do armazenamento de chave/valor no ambiente de execução. Para ver detalhes sobre o uso do armazenamento de chave-valor, consulte a Política de operações de mapeamento de chave-valor.

Aviso: a autenticação básica não fornece confidencialidade. Sempre envie credenciais por meio de uma conexão com TLS ativado (HTTPS) com seu serviço de back-end.

Referência de elemento

A referência de elemento descreve os elementos e 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 de <BasicAuthentication>

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo	Descrição	Padrão	Presence
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
async	Esse atributo está obsoleto.	false	Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presence	Opcional
Tipo	String

Elemento <Operation>

Determina se a política Base64 codifica ou decodifica credenciais.

<Operation>Encode</Operation>

Padrão:	N/A
Presença:	Obrigatório
Tipo:	String. Valores válidos: Codificar Decodificar

Elemento <IgnoreUnresolvedVariables>

Quando definida como true, a política não emitirá um erro se uma variável não puder ser resolvida. Quando usada no contexto de uma política BasicAuthentication, essa configuração geralmente é definida como false porque geralmente é vantajoso gerar um erro se um nome de usuário ou senha não for encontrado nas variáveis especificadas.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Padrão:	true
Presença:	Opcional
Tipo:	Booleano

Elemento <User>

• Para codificação, use o elemento <User> para especificar a variável que contém o nome de usuário. Os valores de nome de usuário e senha são concatenados com dois-pontos antes da codificação Base64.
• Para decodificar, especifique a variável em que o nome de usuário decodificado é gravado.

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

Padrão:	N/A
Presença:	Obrigatório
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence
ref	A variável da qual a política lê dinamicamente o nome de usuário (codificado) ou grava o nome de usuário (decodificação).	N/A	Obrigatório

Elemento <Password>

• Para codificação, use o elemento <Password> para especificar a variável que contém a senha.
• Para decodificar, especifique a variável em que a senha decodificada é gravada.

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

Padrão:	N/A
Presença:	Obrigatório
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence
ref	A variável da qual a política lê dinamicamente a senha (codificar) ou grava a senha (decodificar).	N/A	Obrigatório

Elemento <AssignTo>

Especifica a variável de destino a ser definida com o valor codificado ou decodificado gerado por essa política.

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

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

Padrão:	N/A
Presença:	Obrigatório
Tipo:	String

Atributos

Atributo	Descrição	Padrão	Presence
createNew	Determina se a política precisa substituir a variável, caso ela já esteja definida. Quando "falso", a atribuição à variável ocorrerá somente se a variável estiver desativada no momento (nula). Quando "verdadeiro", a atribuição à variável sempre ocorrerá. Normalmente, você define esse atributo como "falso" (o padrão).	false	Opcional

Elemento <Source>

Para decodificaçã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>

Padrão:	N/A
Presença:	Obrigatório para a operação de decodificação.
Tipo:	N/A

Variáveis de fluxo

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

• BasicAuthentication.{policy_name}.failed (com o valor true)

Observação: se você vir variáveis chamadas BasicAuthentication.{policy_name}.fault.cause e BasicAuthentication.{policy_name}.fault.name, elas não estão sendo usados pela Apigee.

Referência de erros

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com erros. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Código de falha	Status HTTP	Causa	Correção
steps.basicauthentication.InvalidBasicAuthenticationSource	500	Em um decodificação quando a string codificada Base64 recebida não contém um valor válido ou o cabeçalho é inválido (por exemplo, não começa com Basic).
steps.basicauthentication.UnresolvedVariable	500	As variáveis de origem necessárias para decodificar ou codificar não estão presentes. Este erro só poderá ocorrer se IgnoreUnresolvedVariables for falso.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Nome do erro	Ocorre quando	Correção
UserNameRequired	O elemento <User> precisa estar presente na operação nomeada.
PasswordRequired	O elemento <Password> precisa estar presente na operação nomeada.
AssignToRequired	O elemento <AssignTo> precisa estar presente na operação nomeada.
SourceRequired	O elemento <Source> precisa estar presente na operação nomeada.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente 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 usuário da política que causou a falha.	BasicAuthentication.BA-Authenticate.failed = true

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele 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

Amostra: veja nossas amostras de repositório do GitHub para os esquemas mais recentes.

Temas relacionados

Política de operações do mapa de chave-valor