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.

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.

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

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

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

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)

Referência de erros

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

Temas relacionados

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

Política BasicAuthentication Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O que

Amostras

Codificação de saída

Decodificação de entrada

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

Referência de elemento

Atributos de <BasicAuthentication>

Elemento <DisplayName>

Elemento <Operation>

Elemento <IgnoreUnresolvedVariables>

Elemento <User>

Atributos

Elemento <Password>

Atributos

Elemento <AssignTo>

Atributos

Elemento <Source>

Variáveis de fluxo

Referência de erros

Erros de tempo de execução

Erros de implementação

Variáveis de falha

Exemplo de resposta de erro

Exemplo de regra de falha

Esquemas

Temas relacionados

Política BasicAuthentication