Criterio BasicAuthentication

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza la documentazione di Apigee Edge.

icona norme

Cosa

Consente di utilizzare l'autenticazione di base leggera per sicurezza dell'ultimo miglio. Il criterio accetta un nome utente e una password, li codifica in Base64 e scrive come valore generato da 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 inoltre di decodificare le credenziali archiviate in una stringa codificata Base64 in un nome utente e password.

Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni sull'utilizzo, consulta Tipi di criteri.

Video: questo video mostra come eseguire la codifica in Base64 di un nome utente e usando 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 sono derivata dalle variabili specificate dagli attributi ref nella <User> e <Password>. Le variabili devono essere impostato prima dell'esecuzione di questo criterio. In genere, le variabili sono compilate da valori che lette da una mappa chiave/valore. Consulta la Mappa dei valori chiave Norme relative alle operazioni.

Questa configurazione fa sì che l'intestazione HTTP denominata Authorization, come specificato dall'elemento <AssignTo>, venga aggiunta al messaggio di richiesta in uscita inviato al server di backend:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

I valori <User> e <Password> vengono concatenati con 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 gli elementi <User> e <Password> dallo spazio dati 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'Authorization intestazione HTTP, 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. la password decodificata nella variabile request.header.password.

Informazioni sul criterio di autenticazione di base

Il criterio ha due modalità di funzionamento:

  • Codifica: codifica in Base64 un nome utente e una password memorizzati nelle variabili
  • Decode: decodifica il nome utente e la password da un Stringa codificata Base64

Il nome utente e la password vengono in genere memorizzati nello spazio chiavi/valori e poi letti da questo allo stato di esecuzione. Per informazioni dettagliate sull'utilizzo dell'archivio chiavi-valore, consulta Operazioni della mappa valori-chiave .

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>

&lt;BasicAuthentication&gt; attributi

<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 del criterio. Il valore dell'attributo name può Deve 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 il valore su false per restituire un errore quando un criterio non funziona. Si tratta di un comportamento previsto comportamento 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 false per disattivare il criterio. Il criterio non verrà applicata anche se rimane collegata a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Ritirato

&lt;DisplayName&gt; 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 name del criterio è in uso.
Presenza Facoltativo
Tipo Stringa

&lt;Operation&gt; elemento

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

&lt;IgnoreUnresolvedVariables&gt; elemento

Se viene impostato su true, il criterio non genera un errore se una variabile non può essere risolto. Se utilizzata nel contesto di un criterio di autenticazione di base, 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

&lt;User&gt; elemento

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

La variabile da cui il criterio legge dinamicamente il nome utente (codifica) o lo scrive (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
riferimento

La variabile da cui il criterio legge dinamicamente la password (codifica) o la scrive (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 se questa è già per iniziare.

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

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

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

 falso Facoltativo

Elemento <Source>

Per la decodifica, la variabile contenente la stringa codificata Base64, nel modulo Basic Base64EncodedString. Ad esempio, specifica request.header.Authorization, che corrisponde all'intestazione Authorization.

<Source>request.header.Authorization</Source>
Valore predefinito: 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 va a buon fine:

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

Messaggi di errore

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

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Causa Correggi
steps.basicauthentication.InvalidBasicAuthenticationSource 500 In fase di decodifica quando la stringa codificata Base64 in entrata non contiene un valore valido o il formato dell'intestazione non è valido (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ò si verificano solo se IgnoreUnresolvedVariables è false.

Errori di deployment

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

Nome dell'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 denominata.
AssignToRequired L'elemento <AssignTo> deve essere presente per l'operazione denominata.
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 ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come elencato nella precedente tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice dell'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

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

Schemi

Argomenti correlati

Norme relative alle operazioni della mappa di valori chiave