---
title: HttpBasicAuthenticationClientFilter
description: Authenticates clients according to the HTTP basic access authentication scheme.
component: pinggateway
version: 2026
page_id: pinggateway:reference:HttpBasicAuthenticationClientFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/HttpBasicAuthenticationClientFilter.html
revdate: 2025-06-02T18:01:47Z
section_ids:
  HttpBasicAuthenticationClientFilter-usage: Usage
  HttpBasicAuthenticationClientFilter-properties: Properties
  HttpBasicAuthenticationClientFilter-example: Example
  HttpBasicAuthenticationClientFilter-moreinfo: More information
---

# HttpBasicAuthenticationClientFilter

Authenticates clients according to the HTTP basic access authentication scheme.

HTTP basic access authentication is a simple challenge and response mechanism, where a server requests credentials from a client, and the client passes them to the server in an `Authorization` header. The credentials are base-64 encoded. To protect them, use SSL encryption for the connections between the server and client. For more information, refer to [RFC 2617](https://www.rfc-editor.org/rfc/rfc2617.html).

|   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|   | Compare the purpose of this filter with that of the following filters:- [ClientCredentialsOAuth2ClientFilter](ClientCredentialsOAuth2ClientFilter.html), which authenticates clients by their OAuth 2.0 credentials to obtain an access token from an Authorization Server.

- [ClientSecretBasicAuthenticationFilter](ClientSecretBasicAuthenticationFilter.html), which fulfils the same role of transforming OAuth 2.0 credentials to an `Authorization` header, but is more strict for OAuth 2.0 requirements. |

Use HttpBasicAuthenticationClientFilter in a service-to-service context, where services need to access resources protected by HTTP basic access authentication.

## Usage

```json
{
  "name": string,
  "type": "HttpBasicAuthenticationClientFilter",
  "config": {
    "username": configuration expression<string>,
    "passwordSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
    "urlEncodeCredentials": configuration expression<boolean>
  }
}
```

## Properties

* `"username"`: *configuration expression<[string](preface.html#definition-string)>, required*

  The username of the client to authenticate.

* `"passwordSecretId"`: *configuration expression<[string](preface.html#definition-string)>, required*

  The secret ID required to obtain the client password.

  This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types).

* `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required*

  The [SecretsProvider](SecretsProvider.html) to query for the `passwordSecretId`.

* `"urlEncodeCredentials"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional*

  Set to `true` to URL-encoded credentials before base64-encoding them.

  Default: `false`

## Example

The following example shows the flow of information when a client service accesses a resource protected by HTTP basic access authentication:

![HttpBasicAuthenticationClientFilter](https://kroki.io/plantuml/svg/eNqNVLFu3DAM3fUVxC2ZfGkzFOgNAZoD0nQLko5dZJlnq9CJLiXb8Sf1N_plpWxfmsLOnb0YIB4f36NIqusrBXuqe7ZlFeHPb7j58PEzZPK7-QSP1pfwrUAfbewFxjWxjpa8UvC9sgEMFQjyjwQ5QhOwAHwxrgm2RdeD9YLwHk3Kgc7G6gwlBDrETjMCMQTk1hoMW_V-BpCXGnQ4IAcIjakWGZI2h6V2MDBYDAq6iqDSLaYQsoi2XlAacuuLVM1Jog8IumTEo4AuaN-qq2uldBPJN8ccWalac7TG1lpyN3tnE8fzqGgDOsAYUjm9wCbRftURO90DUxMRqhjrLNfBmkwb8RC2PwP5jQL5_mN-NmzrqHOHD9oXDnkgn0XniQ9S4S4V-NLEKhkyg5FR1r11caJagVPoCxAjK8zUTFGGAYuMMVDDBt8z9lrzaQKm5iGPFbclE7X9IPAscM57Qo19imLGSKgmee1Tr052Ro_Z7aybu-n1gPFXgyGqGWIx6Qk7ttKPKSvNpccOouYSFzlW9H4H98Qy8cWrlhVJK5kfmdLogRnNGtmTBNUurCty9mV2sg3-n-qz2ItUezrWaetlvFpbyDq_0fpjujuiU05TPUyfHA65AhdqLg7HvN-LsOx2bMVb-AhQfwG4oAHt)Set Up the Example

1. Add the following script to the PingGateway configuration:

   * Linux

     `$HOME/.openig/scripts/groovy/BasicAuthResourceServerFilter.groovy`

   * Windows

     `%appdata%\OpenIG\scripts\groovy\BasicAuthResourceServerFilter.groovy`

   ```groovy
   /*
    * This script is a simple implementation of HTTP basic access authentication on
    * server side.
    * It expects the following arguments:
    *  - realm: the realm to display when the user agent prompts for
    *    username and password if none were provided.
    *  - username: the expected username
    *  - passwordSecretId: the secretId to find the password
    *  - secretsProvider: the SecretsProvider to query for the password
   */
   import static org.forgerock.util.promise.Promises.newResultPromise;

   import java.nio.charset.Charset;
   import org.forgerock.util.encode.Base64;
   import org.forgerock.secrets.Purpose;
   import org.forgerock.secrets.GenericSecret;

   String authorizationHeader = request.getHeaders().getFirst("Authorization");
   if (authorizationHeader == null) {
       // No credentials provided, return 401 Unauthorized
       Response response = new Response(Status.UNAUTHORIZED);
       response.getHeaders().put("WWW-Authenticate", "Basic realm=\"" + realm + "\"");
       return newResultPromise(response);
   }

   return secretsProvider.getNamed(Purpose.PASSWORD, passwordSecretId)
           .thenAsync(password -> {
               // Build basic authentication string -> username:password
               StringBuilder basicAuthString = new StringBuilder(username).append(":");
               password.revealAsUtf8{ p -> basicAuthString.append(new String(p).trim()) };
               String expectedAuthorization = "Basic " + Base64.encode(basicAuthString.toString().getBytes(Charset.defaultCharset()));
               // Incorrect credentials provided, return 403 forbidden
               if (!expectedAuthorization.equals(authorizationHeader)) {
                   return newResultPromise(new Response(Status.FORBIDDEN));
               }
               // Correct credentials provided, continue.
               return next.handle(context, request);
           },
                   noSuchSecretException -> { throw new RuntimeException(noSuchSecretException); });
   ```

   Source: [BasicAuthResourceServerFilter.groovy](../_attachments/scripts/groovy/BasicAuthResourceServerFilter.groovy)

   The script is a simple implementation of the HTTP basic access authentication scheme. Learn more about scripting filters and handlers in [Extending PingGateway](../configure/extending.html).

2. Add the following route to PingGateway:

   * Linux

     `$HOME/.openig/config/routes/http-basic-access.json`

   * Windows

     `%appdata%\OpenIG\config\routes\http-basic-access.json`

   ```json
   {
     "name": "http-basic-access",
     "baseURI": "http://ig.example.com:8080",
     "condition" : "${find(request.uri.path, '^/http-basic-access')}",
     "heap": [
       {
         "name": "httpBasicAuthEnabledClientHandler",
         "type": "Chain",
         "capture": "all",
         "config": {
           "filters": [
             {
               "type": "HttpBasicAuthenticationClientFilter",
               "config": {
                 "username": "myclient",
                 "passwordSecretId": "password.secret.id",
                 "secretsProvider": {
                   "type": "Base64EncodedSecretStore",
                   "config": {
                     "secrets": {
                       "password.secret.id": "cGFzc3dvcmQ="
                     }
                   }
                 }
               }
             }
           ],
           "handler": "ForgeRockClientHandler"
         }
       }
     ],
     "handler": {
       "type": "ScriptableHandler",
       "config": {
         "type": "application/x-groovy",
         "clientHandler": "httpBasicAuthEnabledClientHandler",
         "source": [
           "request.uri.path = '/http-basic-protected-resource'",
           "return http.send(context, request);"
         ]
       }
     }
   }
   ```

   Source: [http-basic-access.json](../_attachments/config/routes/http-basic-access.json)

   Note the following features of the route:

   * The route matches requests to `/http-basic-access`.

   * The ScriptableHandler rewrites the request to target it to `/http-basic-protected-resource` and calls the HTTP client that uses the httpBasicAuthEnabledClientHandler.

   * The httpBasicAuthEnabledClientHandler calls the HttpBasicAuthenticationClientFilter to authenticate the client using the client's credentials.

3. Add the following route to PingGateway:

   * Linux

     `$HOME/.openig/config/routes/http-basic-protected-resource.json`

   * Windows

     `%appdata%\OpenIG\config\routes\http-basic-protected-resource.json`

   ```json
   {
     "heap": [
       {
         "name": "mySecretsProvider",
         "type": "Base64EncodedSecretStore",
         "config": {
           "secrets": {
             "password.secret.id": "cGFzc3dvcmQ="
           }
         }
       }
     ],
     "name": "http-basic-protected-resource",
     "condition": "${find(request.uri.path, '^/http-basic-protected-resource')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "HttpBasicAuthResourceServerFilter",
             "type": "ScriptableFilter",
             "config": {
               "type": "application/x-groovy",
               "file": "BasicAuthResourceServerFilter.groovy",
               "args": {
                 "realm": "IG Protected Area",
                 "username": "myclient",
                 "passwordSecretId": "password.secret.id",
                 "secretsProvider": "${heap['mySecretsProvider']}"

               }
             }
           }
         ],
         "handler": {
           "type": "StaticResponseHandler",
           "config": {
             "status": 200,
             "headers": {
               "Content-Type": [ "text/html; charset=UTF-8" ]
             },
             "entity": "<html><body><h2>Access Granted</h2></body></html>"
           }
         }
       }
     }
   }
   ```

   Source: [http-basic-protected-resource.json](../_attachments/config/routes/http-basic-protected-resource.json)

   Notice the following features of the route:

   * The route matches requests to `/http-basic-protected-resource`.

   * The ScriptableFilter provides a script to implement a simple HTTP basic access authentication scheme that compares the provided credentials with the expected credentials.

   * When the client is authenticated, the StaticResponseHandler returns a message that access is granted.

4. Access the route on <http://ig.example.com:8080/http-basic-access>.

   Because the expected credentials were provided in the request, a message shows that access is granted.

## More information

[org.forgerock.openig.filter.HttpBasicAuthenticationClientFilterHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/HttpBasicAuthenticationClientFilterHeaplet.html)