—Rate this article—
 

Basic Authentication policy

 Basic Authentication policy

About | Samples | Element reference | Error codes | Schemas | Usage notes | Related topics

What

Enables you to use lightweight Basic Authentication for last-mile security. The policy takes the username and password defined in the policy, Base64 encodes them, and adds the resulting value to the Authorization: Basic HTTP header. The policy also lets you decode basic authorization credentials on an inbound request.

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

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

In the sample policy configuration above, the username and password to be encoded are derived from the variables specified by the ref attributes on the <User> and <Password> elements. The variables must be set by another policy before this policy executes. Typically, the variables are populated by values that are read from a key/value map. See Key Value Map Operations policy.

This configuration results in an Authorization HTTP header, as shown below, being applied to the outbound request message. The outbound request is the message that the API proxy sends to the backend service specified in the TargetEndpoint configuration. The <User> and <Password> values are concatenated with a colon prior to Base64 encoding.

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Consider that you have a key/value map with the following entry:

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

Attach the following KeyValueMapOperations policies before the BasicAuthentication policy to be able to extract the values for your <User> and <Password> elements from the key/value store and populate them to the variables BasicAuth.credentials.username and BasicAuth.credentials.password.

<KeyValueMapOperations name="getUsername" mapIdentifier="BasicAuthCredentials">
<Scope>apiproxy</Scope>
   <Get assignTo="credentials.username" index='1'>
      <Key>
         <Parameter ref="BasicAuth.credentials.username"/> 
      </Key>
   </Get>
</KeyValueMapOperations>
and
<KeyValueMapOperations name="getPassword" mapIdentifier="BasicAuthCredentials">
   <Scope>apiproxy</Scope>
   <Get assignTo="credentials.password" index='1'>
      <Key>
         <Parameter ref="BasicAuth.credentials.password"/> 
      </Key>
   </Get>
</KeyValueMapOperations>
<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 policy sample configuration above, the username and password are decoded from Authorization: Basic HTTP headers on inbound requests.


Element reference

The element reference describes the elements and attributes of the BasicAuthentication policy.

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

<BasicAuthentication> attributes

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">
Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required

<DisplayName> element

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>Custom label used in UI</DisplayName>
Default: Policy name attribute value.
Presence: Optional
Type: String

<Operation> element

Determines whether the policy will Base64-encode credentials to populate an Authorization: Basic HTTP header on an outbound request or decode Base64-encoded credentials from an Authorization: Basic HTTP header on an inbound request.

<Operation>Encode</Operation>
Default: N/A
Presence: Required
Type:

String.

Valid values include:

  • Encode
  • Decode

<IgnoreUnresolvedVariables> element

When set to true, the policy will not throw an error if a variable cannot be resolved. When used in the context of a BasicAuthentication policy, this setting is usually set to false because it is generally beneficial to throw an error if a username or password cannot be found in the variables specified.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Default: N/A
Presence: Required
Type:

Boolean

<User> element

  • For encoding, set the <User> element with a reference attribute to dynamically retrieve the username from a variable. Username and password values are concatenated with a colon prior to Base64 encoding. If you store credentials in a key/value map, this variable will be the one to which the GET operation assigns the value of the username. See Key Value Map Operations policy
  • For decoding, specify the flow variable in which the decoded username is to be placed.
<User ref="request.queryparam.username" /> 
Default: N/A
Presence: Required
Type:

N/A

Attributes

Attribute Description Default Presence
ref

The variable from which the policy dynamically reads the username.

N/A Required

<Password> element

  • For encoding, set the <Password> element with a reference attribute to dynamically retrieve the password from a variable. Username and password values are concatenated with a colon prior to Base64 encoding. The best practice is to store passwords in a key/value map and retrieve them dynamically at runtime. If you store credentials in a key/value map, this variable will be the one to which the GET operation assigns the value of the password. See Key Value Map Operations policy.
  • For decoding, specify the flow variable in which the decoded password is to be placed.
<Password ref="request.queryparam.password" />
Default: N/A
Presence: Required
Type:

N/A

Attributes

Attribute Description Default Presence
ref

The variable from which the policy dynamically reads the password.

N/A Required

<AssignTo> element

For encoding, this is the location where the Authorization: Basic value, such as TXlVc2VybmFtZTpNeVBhc3N3b3Jk, is set. If you don't specify an <AssignTo> value, the request.header.Authorization is used.

<AssignTo createNew="false">request.header.Authorization</AssignTo>
Default: N/A
Presence: Required
Type:

N/A

Attributes

Attribute Description Default Presence
createNew

For the BasicAuthentication policy, you will usually set this attribute to false.

In the context of BasicAuthentication, you do not want to require that the policy generate a new message. Instead, you want the HTTP Authorization: Basic header to be added to the existing request message.

False Optional

<Source> element

For decoding, the location of the Authorization: Basic value, such as TXlVc2VybmFtZTpNeVBhc3N3b3Jk. The decoded credentials must contain user and password strings concatenated by a colon. If you don't specify a <Source> value, the value is taken from request.header.Authorization.

<Source>request.header.Authorization</Source>
Default: N/A
Presence: Required
Type:

N/A

Error codes

The error code is thrown under the following conditions:

  • When IgnoreUnresolvedVariables is false and the source for the decode or encode is not present
  • When a Basic Authentication HTTP header is not present on an inbound request
Error Code Message
InvalidBasicAuthenticationSource Source variable : request.header.Authorization for basic authentication decode policy is not valid

Schemas

See our GitHub repository samples for the most recent schemas.

Usage notes

The policy gets the username and password from variables that you define. The username and password are commonly stored the key/value store and then read from the key/value store at runtime. For details on using key/value store, see Key Value Map Operations policy.

Basic authentication does not provide confidentiality. Always send credentials over a TLS-enabled (HTTPS) connection to your backend service.

Related topics

Key Value Map Operations policy

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)