Règle BasicAuthentication

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Quoi

Cette règle vous permet d'utiliser l'authentification de base légère pour renforcer la sécurité du dernier kilomètre. La règle prend un nom d'utilisateur et un mot de passe, Base64 les encode et écrit la valeur obtenue dans une variable. La valeur obtenue se présente au format Basic Base64EncodedString. Vous écrivez généralement cette valeur dans un en-tête HTTP, tel que l'en-tête Authorization.

La règle vous permet également de décoder les identifiants stockés dans une chaîne encodée en Base64 en un nom d'utilisateur et un mot de passe.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Remarque : Cette règle n'applique pas l'authentification de base sur une requête adressée à un proxy d'API. Vous utilisez plutôt des identifiants d'encodage/de décodage en Base64, généralement lors de la connexion à un serveur backend ou de l'utilisation d'une règle d'appel de service, telle que la règle d'appel de service, qui nécessite une authentification de base.

Remarque : Les vidéos suivantes montrent l'éditeur de proxy classique dans l'interface utilisateur d'Apigee. Apigee intègre une nouvelle version de l'éditeur de proxy, dont la conception est différente de celle de la version classique présentée dans les vidéos.

Vidéo : cette vidéo montre comment encoder un nom d'utilisateur et un mot de passe en Base64 à l'aide de la règle d'authentification de base.

Vidéo : Cette vidéo montre comment décoder un nom d'utilisateur et un mot de passe encodés en Base64 à l'aide de la règle d'authentification de base.

Exemples

Encodage sortant

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

Dans l'exemple de configuration de règle ci-dessus, le nom d'utilisateur et le mot de passe à encoder sont dérivés des variables spécifiées par les attributs ref des éléments <User> et <Password>. Les variables doivent être définies avant l'exécution de cette règle. En règle générale, les variables sont renseignées avec des valeurs lues à partir d'un mappage clé-valeur. Consultez la section Règle des opérations de mappage clé-valeur.

Cette configuration aboutit à l'en-tête HTTP nommé Authorization, comme spécifié par l'élément <AssignTo>, ajouté au message de requête sortant envoyé au serveur de backend :

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Les valeurs <User> et <Password> sont concaténées avec deux points avant l'encodage Base64.

Supposons que vous disposez d'un mappage clé/valeur avec l'entrée suivante :

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

Associez les règles KeyValueMapOperations avant la règle BasicAuthentication afin d'extraire les valeurs de vos éléments <User> et <Password> à partir d'un magasin de paires clé/valeur et de les insérer dans les variables credentials.username et 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>
      

Encodage entrant

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

Dans cet exemple de règle, la règle décode le nom d'utilisateur et le mot de passe de l'en-tête HTTP Authorization, comme spécifié par l'élément <Source>. La chaîne encodée en Base64 doit être au format Basic Base64EncodedString..

La règle écrit le nom d'utilisateur décodé dans la variable request.header.username et le mot de passe décodé dans la variable request.header.password.

---

À propos de la règle d'authentification de base

La règle comporte deux modes d'opérations :

• Encode : Base64 encode un nom d'utilisateur et un mot de passe stockés dans des variables.
• Decode : décode le nom d'utilisateur et le mot de passe à partir d'une chaîne encodée en Base64.

Le nom d'utilisateur et le mot de passe sont généralement stockés dans le magasin de paires clé/valeur, puis lus à partir du magasin de paires clé-valeur lors de l'exécution. Pour en savoir plus sur l'utilisation du magasin de paires clé-valeur, consultez la page Règle d'opérations de mappage de clés-valeurs.

Avertissement : L'authentification de base n'assure pas la confidentialité. Envoyez toujours des identifiants via une connexion conforme au protocole TLS (HTTPS) à votre service de backend.

Documentation de référence des éléments

La documentation de référence des éléments décrit les éléments et les attributs de la règle 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>

Attributs <BasicAuthentication>

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

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut	Description	Par défaut	Presence
name	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.	N/A	Obligatoire
continueOnError	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également : Les règles d'erreur sont déclenchées UNIQUEMENT en état d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel	false	Facultatif
enabled	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.	true	Facultatif
async	Cet attribut est obsolète.	false	Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Par défaut	N/A Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Presence	Facultatif
Type	Chaîne

Élément <Operation>

Détermine si la stratégie Base64 encode ou décode les identifiants.

<Operation>Encode</Operation>

Valeur par défaut :	N/A
Présence :	Obligatoire
Type :	Chaîne. Les valeurs valides sont les suivantes : Encode Decode

Élément <IgnoreUnresolvedVariables>

Lorsqu'elle est définie sur true, la règle ne génère pas d'erreur si une variable ne peut pas être résolue. Lorsqu'il est utilisé dans le cadre d'une règle BasicAuthentication, ce paramètre est généralement défini sur false, car il est généralement utile de générer une erreur si un nom d'utilisateur ou un mot de passe est introuvable dans les variables spécifiées.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Valeur par défaut :	true
Présence :	Facultatif
Type :	Booléen

Élément <User>

• Pour l'encodage, utilisez l'élément <User> pour spécifier la variable contenant le nom d'utilisateur. Les valeurs de nom d'utilisateur et de mot de passe sont concaténées avec deux-points avant l'encodage Base64.
• Pour le décodage, spécifiez la variable dans laquelle le nom d'utilisateur décodé est écrit.

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

Valeur par défaut :	N/A
Présence :	Obligatoire
Type :	N/A

Attributs

Attribut	Description	Par défaut	Presence
ref	La variable à partir de laquelle la règle lit de manière dynamique le nom d'utilisateur (encode) ou écrit le nom d'utilisateur (decode).	N/A	Obligatoire

Élément <PassWord>

• Pour l'encodage, utilisez l'élément <Password> pour spécifier la variable contenant le mot de passe.
• Pour le décodage, spécifiez la variable dans laquelle le mot de passe décodé est écrit.

<Password ref="request.queryparam.password" />

Valeur par défaut :	N/A
Présence :	Obligatoire
Type :	N/A

Attributs

Attribut	Description	Par défaut	Presence
ref	La variable à partir de laquelle la stratégie lit de manière dynamique le mot de passe (encode) ou écrit le nom de passe (decode).	N/A	Obligatoire

Élément <AssignTo>

Spécifie la variable cible à définir avec la valeur encodée ou décodée générée par la règle.

L'exemple suivant indique que la règle doit définir l'en-tête Authorization du message sur la valeur générée :

<AssignTo createNew="false">request.header.Authorization</AssignTo>

Valeur par défaut :	N/A
Présence :	Obligatoire
Type :	Chaîne

Attributs

Attribut	Description	Par défaut	Presence
createNew	Détermine si la règle doit écraser la variable si celle-ci est déjà définie. Lorsque la valeur est "false", l'attribution à la variable se produit uniquement si la variable n'est pas définie (null). Lorsque la valeur est "true", l'attribution à la variable a toujours lieu. Généralement, vous définissez cet attribut sur "false" (valeur par défaut).	false	Facultatif

Élément <Source>

Pour le décodage, la variable contenant la chaîne encodée en Base64, au format Basic Base64EncodedString Par exemple, spécifiez request.header.Authorization, correspondant à l'en-tête Authorization.

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

Valeur par défaut :	N/A
Présence :	Obligatoire pour l'opération Decode.
Type :	N/A

Variables de flux

La variable de flux suivante est définie en cas d'échec de la règle :

• BasicAuthentication.{policy_name}.failed (avec la valeur "true")

Remarque : Si vous voyez des variables appelées BasicAuthentication.{policy_name}.fault.cause et BasicAuthentication.{Policy_name}.fault.name, elles ne sont actuellement pas utilisées par Apigee.

Informations de référence sur les erreurs

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

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Schémas

Exemple : consultez les exemples de dépôt GitHub pour visualiser les schémas les plus récents.

Articles associés

Règle d'opérations de mappage de clés-valeurs