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.

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

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

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

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 :

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

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

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

Articles associés

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

Règle BasicAuthentication Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Quoi

Exemples

Encodage sortant

Encodage entrant

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

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

Attributs <BasicAuthentication>

<DisplayName> element

Élément <Operation>

Élément <IgnoreUnresolvedVariables>

Élément <User>

Attributs

Élément <PassWord>

Attributs

Élément <AssignTo>

Attributs

Élément <Source>

Variables de flux

Informations de référence sur les erreurs

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Schémas

Articles associés

Règle BasicAuthentication