Criterio BasicAuthentication

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio BasicAuthentication consente di utilizzare l'autenticazione di base leggera per la sicurezza dell'ultimo miglio. Il criterio accetta un nome utente e una password, li codifica in Base64 e scrive il valore risultante in una variabile. Il valore risultante è nel formato Basic Base64EncodedString. In genere, questo valore viene scritto in un'intestazione HTTP, ad esempio l'intestazione Authorization.

Le norme prevedono due modalità di funzionamento:

  • Codifica: codifica Base64 di un nome utente e una password memorizzati in variabili
  • Decode: decodifica il nome utente e la password da una stringa con codifica Base64

Il nome utente e la password vengono in genere archiviati nell'archivio chiave/valore e poi letti dall'archivio chiave/valore in fase di runtime. Per informazioni dettagliate sull'utilizzo dell'archivio chiave/valore, consulta i criteri relativi alle operazioni della mappa chiave-valore.

Questo criterio non applica l'autenticazione di base a una richiesta a un proxy API. Utilizzalo invece per codificare/decodificare le credenziali come Base64, in genere quando ti connetti a un server di backend o utilizzi un criterio di callout del servizio, ad esempio il criterio di callout del servizio, che richiede l'autenticazione di base.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempi

Codifica in uscita

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

Nella configurazione dei criteri di esempio riportata sopra, il nome utente e la password da codificare derivano dalle variabili specificate dagli attributi ref negli elementi <User> e <Password>. Le variabili devono essere impostate prima dell'esecuzione di questa policy. In genere, le variabili vengono compilate con valori letti da una mappa chiave/valore. Consulta le norme relative alle operazioni della mappa di coppie chiave-valore.

Questa configurazione comporta l'aggiunta dell'intestazione HTTP denominata Authorization, come specificato dall'elemento <AssignTo>, al messaggio di richiesta in uscita inviato al server di backend:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

I valori <User> e <Password> vengono concatenati con i due punti prima della codifica Base64.

Considera di avere una mappa di coppie chiave-valore con la seguente voce:

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

Collega i seguenti criteri KeyValueMapOperations prima dei criteri BasicAuthentication per poter estrarre i valori degli elementi <User> e <Password> dall'archivio chiave/valore e inserirli nelle variabili 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 in entrata

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

In questo esempio di criterio, il criterio decodifica il nome utente e la password dall'intestazione HTTP Authorization, come specificato dall'elemento <Source>. La stringa con codifica Base64 deve avere la forma Basic Base64EncodedString.

Il criterio scrive il nome utente decodificato nella variabile request.header.username e la password decodificata nella variabile request.header.password.

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio 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>

Attributi <BasicAuthentication>

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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presence
name

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Deprecato

Elemento <DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence Facoltativo
Tipo Stringa

Elemento <Operation>

Determina se il criterio codifica o decodifica le credenziali in base64.

<Operation>Encode</Operation>
Valore predefinito: N/D
Presenza: Obbligatorio
Tipo:

Stringa.

I valori validi includono:

  • Codifica
  • Decodifica

Elemento <IgnoreUnresolvedVariables>

Se impostato su true, il criterio non genererà un errore se una variabile non può essere risolta. Se utilizzato nel contesto di una norma BasicAuthentication, questa impostazione viene in genere impostata su false perché in genere è utile generare un errore se non è possibile trovare un nome utente o una password nelle variabili specificate.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Valore predefinito: true
Presenza: Facoltativo
Tipo:

Booleano

Elemento <User>

  • Per la codifica, utilizza l'elemento <User> per specificare la variabile contenente il nome utente. I valori del nome utente e della password vengono concatenati con i due punti prima della codifica Base64.
  • Per la decodifica, specifica la variabile in cui viene scritto il nome utente decodificato.
<User ref="request.queryparam.username" />
Valore predefinito: N/D
Presenza: Obbligatorio
Tipo:

N/D

Attributi

Attributo Descrizione Predefinito Presenza
ref

La variabile da cui il criterio legge dinamicamente il nome utente (codifica) o scrive il nome utente (decodifica).

 N/D Obbligatorio

Elemento <Password>

  • Per la codifica, utilizza l'elemento <Password> per specificare la variabile contenente la password.
  • Per la decodifica, specifica la variabile in cui viene scritta la password decodificata.
<Password ref="request.queryparam.password" />
Valore predefinito: N/D
Presenza: Obbligatorio
Tipo:

N/D

Attributi

Attributo Descrizione Predefinito Presenza
ref

La variabile da cui il criterio legge dinamicamente la password (codifica) o scrive la password (decodifica).

 N/D Obbligatorio

Elemento <AssignTo>

Specifica la variabile di destinazione da impostare con il valore codificato o decodificato generato da questo criterio.

L'esempio seguente indica che il criterio deve impostare l'intestazione Authorization del messaggio sul valore generato:

<AssignTo createNew="false">request.header.Authorization</AssignTo>
Valore predefinito: N/D
Presenza: Obbligatorio
Tipo:

Stringa

Attributi

Attributo Descrizione Predefinito Presenza
createNew Determina se la policy deve sovrascrivere la variabile se questa è già impostata.

Se il valore è "false", l'assegnazione alla variabile avviene solo se la variabile non è attualmente impostata (null).

Se il valore è "true", l'assegnazione alla variabile avviene sempre.

In genere, questo attributo è impostato su "false" (valore predefinito).

 falso Facoltativo

Elemento <Source>

Per la decodifica, la variabile contenente la stringa con codifica Base64, nel formato Basic Base64EncodedString. Ad esempio, specifica request.header.Authorization, corrispondente all'intestazione Autorizzazione.

<Source>request.header.Authorization</Source>
Valore predefinito: N/D
Presenza: Obbligatorio per l'operazione di decodifica.
Tipo:

N/D

Variabili di flusso

Quando il criterio non viene rispettato, viene impostata la seguente variabile di flusso:

  • BasicAuthentication.{policy_name}.failed (con un valore true)

Messaggi di errore

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

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

Schemi

Argomenti correlati

Norme operative per la mappa di coppie chiave-valore