| description |
|---|
This page provides the technical details of the Basic Authentication policy |
You can use the basic-authentication policy to manage basic authentication headers sent in API calls. The policy compares the user and password sent in the basic authentication header to an APIM user to determine if the user credentials are valid.
To use the policy in an API, you need to:
- Configure an LDAP, inline, or HTTP resource for your API plan to specify where the APIM users are stored
- Configure a basic authentication policy for the API flows
{% hint style="info" %} LDAP, inline, and HTTP resources are not part of the default APIM configuration. You must first configure an LDAP, inline, or HTTP resource for APIM. {% endhint %}
Functional and implementation information for the basic-authentication policy is organized into the following sections:
{% hint style="warning" %} This policy can be applied to v2 APIs and v4 HTTP proxy APIs. It cannot be applied to v4 message APIs or v4 TCP proxy APIs. {% endhint %}
{% tabs %}
{% tab title="HTTP proxy API example" %}
If an API is configured with the basic-authentication policy, a request with invalid credentials will result in the following response:
{% code title="Default response" %}
{
"http_status_code": 401,
"message": "Unauthorized"
}{% endcode %}
The response headers will also contain a WWW-Authenticate header containing the realm value the API publisher configured.
To authenticate, pass the Authorization: Basic yourCredentials header with your request.
{% endtab %}
{% endtabs %}
The phases checked below are supported by the basic-authentication policy:
| v2 Phases | Compatible? | v4 Phases | Compatible? |
|---|---|---|---|
| onRequest | true | onRequest | true |
| onResponse | false | onResponse | false |
| onRequestContent | false | onMessageRequest | false |
| onResponseContent | false | onMessageResponse | false |
You can configure the basic-authentication policy with the following options:
| Property | Required | Description | Type |
|---|---|---|---|
| authenticationProviders | true | A list of authentication providers | List of strings |
| realm | false | Name showed to the client in case of error | string |
After successful authentication, connected username is stored in context attributes, accessible with context.attributes['user'] expression language.
In order to display the connected username in API logging, you can enable the environment setting Gateway > API logging > Display end user on API Logging. This adds a user column in the logs table.
The following is the compatibility matrix for APIM and the basic-authentication policy:
| Plugin Version | Supported APIM versions |
|---|---|
| Up to 1.x | Up to 3.14.x |
| 1.4.x+ | 3.15.x+ |
{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-basic-authentication/blob/master/CHANGELOG.md" %}