Criterio BasicAuthentication

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Consente di utilizzare la semplice autenticazione di base per la sicurezza dell'ultimo miglio. Il criterio prende 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, come l'intestazione Authorization

Il criterio consente inoltre di decodificare le credenziali archiviate in una stringa codificata in Base64 in un nome utente e una password.

Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Nota: questo criterio non applica l'autenticazione di base su una richiesta inviata a un proxy API. Puoi utilizzarlo per codificare/decodificare le credenziali Base64, in genere durante la connessione a un server di backend o utilizzando un criterio di callout del servizio, come il criterio Callout di servizio, che richiede l'autenticazione di base.

Nota: i seguenti video mostrano il proxy Editor classico nell'interfaccia utente di Apigee. Apigee sta introducendo una nuova versione dell'Editor proxy, che ha un design diverso rispetto alla versione classica mostrata nei video.

Video: questo video mostra come codificare in base64 un nome utente e una password utilizzando il criterio 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 questo criterio. In genere, le variabili sono compilate da valori letti da una mappa chiave/valore. Consulta le norme sulle operazioni della mappa 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> sono concatenati con i due punti prima della codifica Base64.

Considera 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 del criterio BasicAuthentication per poter estrarre i valori per i tuoi elementi <User> e <Password> dall'archivio chiave/valore e compilarli 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 essere nel formato Basic Base64EncodedString.

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

---

Informazioni sul criterio di autenticazione di base

Il criterio ha due modalità di funzionamento:

• Codifica: Base64 codifica un nome utente e una password archiviati nelle variabili
• Decodifica: decodifica il nome utente e la password da una stringa codificata Base64

Il nome utente e la password vengono comunemente archiviati nell'archivio chiave/valore e poi letti dall'archivio di chiavi/valore in fase di runtime. Per maggiori dettagli sull'utilizzo dell'archivio chiavi/valore, consulta le norme relative alle operazioni sulla mappa chiave-valore.

Avviso:l'autenticazione di base non offre riservatezza. Invia sempre le credenziali al servizio di backend tramite una connessione abilitata per TLS (HTTPS).

Riferimento elemento

Il riferimento agli elementi 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	Presenza
name	Il nome interno della norma. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/A	Obbligatorio
continueOnError	Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri. Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche: Le regole di errore vengono attivate SOLO in stato di errore (informazioni su continueOnError) Gestione dei guasti all'interno del flusso di corrente	false	Facoltativo
enabled	Imposta il criterio su true per applicare il criterio. Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.	true	Facoltativo
async	Questo attributo è obsoleto.	false	Deprecata

Elemento <DisplayName>

Utilizzalo in aggiunta 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/A Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza	Facoltativo
Tipo	Stringa

Elemento <Operation>

Determina se il criterio Base64 codifica o decodifica le credenziali.

<Operation>Encode</Operation>

Predefinita:	N/D
Presenza:	Obbligatorio
Tipo:	Stringa. I valori validi sono: Codifica Decodifica

Elemento <IgnoraUnresolvedVariables>

Se viene impostato su true, il criterio non genera un errore se non è possibile risolvere una variabile. Quando viene utilizzata nel contesto di un criterio BasicAuthentication, questa impostazione in genere è impostata su false perché, in genere, conviene generare un errore se non è possibile trovare un nome utente o una password nelle variabili specificate.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Predefinita:	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 sono concatenati con i due punti prima della codifica Base64.
• Per la decodifica, specifica la variabile in cui è scritto il nome utente decodificato.

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

Predefinita:	N/D
Presenza:	Obbligatorio
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza
rif	La variabile da cui il criterio legge in modo dinamico 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" />

Predefinita:	N/D
Presenza:	Obbligatorio
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza
rif	La variabile da cui il criterio legge in modo dinamico 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>

Predefinita:	N/D
Presenza:	Obbligatorio
Tipo:	Stringa

Attributi

Attributo	Descrizione	Predefinito	Presenza
createNew	Determina se il criterio deve sovrascrivere la variabile nel caso in cui la variabile sia già impostata. Quando è "false", l'assegnazione alla variabile si verifica solo se la variabile al momento non è impostata (null). Quando il valore è "true", l'assegnazione alla variabile avviene sempre. In genere, imposti questo attributo su "false" (il valore predefinito).	false	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 Authorization.

<Source>request.header.Authorization</Source>

Predefinita:	N/D
Presenza:	Obbligatorio per l'operazione di decodifica.
Tipo:	N/D

Variabili di flusso

La seguente variabile di flusso viene impostata quando il criterio non viene applicato:

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

Nota:se vedi variabili chiamate BasicAuthentication.{policy_name}.fault.cause e BasicAuthentication.{policy_name}.fault.cause, queste non sono attualmente utilizzate da Apigee.

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore	Stato HTTP	Causa	Correggi
steps.basicauthentication.InvalidBasicAuthenticationSource	500	In una decodifica quando la stringa codificata Base64 in arrivo non contiene un valore valido o l'intestazione non è nel formato corretto (ad esempio, non inizia con Basic).
steps.basicauthentication.UnresolvedVariable	500	Le variabili di origine richieste per la decodifica o la codifica non sono presenti. Questo errore può verificarsi solo se IgnoreUnresolvedVariables è falso.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome errore	Si verifica quando	Correggi
UserNameRequired	L'elemento <User> deve essere presente per l'operazione con nome.
PasswordRequired	L'elemento <Password> deve essere presente per l'operazione con nome.
AssignToRequired	L'elemento <AssignTo> deve essere presente per l'operazione con nome.
SourceRequired	L'elemento <Source> deve essere presente per l'operazione con nome.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili	Dove	Esempio
fault.name="fault_name"	fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di errore.	fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed	policy_name è il nome specificato dall'utente del criterio che ha generato l'errore.	BasicAuthentication.BA-Authenticate.failed = true

Esempio di risposta di errore

Nota: per la gestione degli errori, la best practice consiste nell'eseguire il trap della parte errorcode della risposta di errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

{
   "fault":{
      "detail":{
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

Esempio di regola di errore

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

Schema

Esempio: consulta gli esempi del nostro repository GitHub per gli schemi più recenti.

Argomenti correlati

Norme relative alle operazioni della mappa chiave-valore