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

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

É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 :	Requis
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 :	vrai
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 :	Requis
Type :	N/A

Attributs

Attribut	Description	Par défaut	Présence
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 :	Requis
Type :	N/A

Attributs

Attribut	Description	Par défaut	Présence
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 :	Requis
Type :	Chaîne

Attributs

Attribut	Description	Par défaut	Présence
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).	faux	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

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les erreurs. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur	État HTTP	Cause	Corriger
steps.basicauthentication.InvalidBasicAuthenticationSource	500	Sur un décodage lorsque la chaîne entrante encodée en Base64 ne contient pas de valeur valide ou si l'en-tête est incorrect (par exemple, ne commence pas par Basic).
steps.basicauthentication.UnresolvedVariable	500	Les variables source requises pour le décodage ou l'encodage ne sont pas présentes. Cette erreur ne peut se produire que si la valeur de IgnoreUnresolvedVariables est "false".

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur	Se produit quand	Corriger
UserNameRequired	L'élément <User> doit être présent pour l'opération nommée.
PasswordRequired	L'élément <Password> doit être présent pour l'opération nommée.
AssignToRequired	L'élément <AssignTo> doit être présent pour l'opération nommée.
SourceRequired	L'élément <Source> doit être présent pour l'opération nommée.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables	Lieu	Exemple
fault.name="fault_name"	fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed	policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	BasicAuthentication.BA-Authenticate.failed = true

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la meilleure pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

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

Exemple de règle de défaillance

<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