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.

Compare the purpose of this filter with that of the following filters:

ClientCredentialsOAuth2ClientFilter, which authenticates clients by their OAuth 2.0 credentials to obtain an access token from an Authorization Server.
ClientSecretBasicAuthenticationFilter, 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

{
  "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>, required: The username of the client to authenticate.
"passwordSecretId": configuration expression<string>, required: The secret ID required to obtain the client password.

This secret ID must point to a GenericSecret.
"secretsProvider": SecretsProvider reference, required: The SecretsProvider to query for the passwordSecretId.
"urlEncodeCredentials": configuration expression<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:

Set Up the Example

Add the following script to the PingGateway configuration:

Linux
Windows

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

%appdata%\OpenIG\scripts\groovy\BasicAuthResourceServerFilter.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); });

The script is a simple implementation of the HTTP basic access authentication scheme. For information about scripting filters and handlers, refer to Extend.

Add the following route to PingGateway:

Linux
Windows

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

%appdata%\OpenIG\config\routes\http-basic-access.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);"
      ]
    }
  }
}

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 then calls the HTTP client, that has been redefined to use the httpBasicAuthEnabledClientHandler.
The httpBasicAuthEnabledClientHandler calls the HttpBasicAuthenticationClientFilter to authenticate the client, using the client’s credentials.

Add the following route to PingGateway:

Linux
Windows

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

%appdata%\OpenIG\config\routes\http-basic-protected-resource.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>"
        }
      }
    }
  }
}

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.

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