Règle BasicAuthentication

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

Consultez la documentation d'Apigee Edge.

icône de la règle

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.

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.

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 :

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

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

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

Articles associés

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