Stai visualizzando la documentazione di Apigee Edge.
Consulta la
documentazione di Apigee X. info

Cosa
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.
Il criterio consente anche di decodificare le credenziali archiviate in una stringa con codifica Base64 in un nome utente e una password.
Video:questo video mostra come codificare in base64 un nome utente e una password utilizzando le norme di autenticazione di base.
Video:questo video mostra come decodificare un nome utente e una password codificati in base64 utilizzando il criterio di autenticazione di base.
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 norma. In genere, le variabili vengono compilate con valori
letti da una mappa chiave/valore. Consulta le norme relative alle operazioni
della mappa chiave-valore.
Questa configurazione genera l'intestazione HTTP denominata Authorization, come specificato dall'elemento <AssignTo>, che viene aggiunto 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.
Supponiamo di avere una mappa 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 per gli 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.
Informazioni sulla policy di autenticazione di base
Le norme prevedono due modalità di funzionamento:
- Codifica: codifica Base64 di un nome utente e una password memorizzati nelle variabili
- Decodifica: decodifica il nome utente e la password da una stringa codificata in Base64
Il nome utente e la password vengono in genere memorizzati 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.
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 del criterio:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno del criterio. Il valore dell'attributo Se vuoi, puoi utilizzare l'elemento |
N/D | Obbligatorio |
continueOnError |
Imposta il valore su Imposta su |
falso | Facoltativo |
enabled |
Imposta il valore su Imposta |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
falso | Deprecato |
<DisplayName> elemento
Da utilizzare in aggiunta all'attributo name
per etichettare il criterio in
editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.
<DisplayName>Policy Display Name</DisplayName>
Predefinito |
N/D Se ometti questo elemento, il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <Operation>
Determina se il criterio codifica o decodifica le credenziali in Base64.
<Operation>Encode</Operation>
Predefinito: | N/D |
Presenza: | Obbligatorio |
Tipo: |
Stringa. I valori validi includono:
|
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>
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 di nome utente e 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" />
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" />
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>
Per un'operazione Encode
, specifica la variabile di destinazione da impostare con il valore codificato
generato da questa policy.
L'esempio seguente indica che il criterio deve impostare l'intestazione Authorization
del messaggio sul valore generato:
<AssignTo createNew="false">request.header.Authorization</AssignTo>
Predefinito: | N/D |
Presenza: | Obbligatorio per l'operazione Encode . |
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 codificata in Base64, nel formato Basic
Base64EncodedString
. Ad esempio,
specifica request.header.Authorization
, corrispondente all'intestazione Autorizzazione.
<Source>request.header.Authorization</Source>
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 Edge 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 (e.g., does not start with "Basic"). | build |
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. |
build |
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. |
build |
PasswordRequired |
The <Password> element must be present for the named operation. |
build |
AssignToRequired |
The <AssignTo> element must be present for the named operation. |
build |
SourceRequired |
The <Source> element must be present for the named operation. |
build |
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>