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.

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:

 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)

Referência de erro

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

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

Tópicos relacionados

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