HttpBasicAuthenticationClientFilter

Authenticate clients according to HTTP Basic Authentication protocol, using the client's credentials.

Use this filter in a service-to-service context, where services need to access resources protected by HTTP Basic Authentication.

Usage

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

For information about supported formats for secret-id, see secret-id.

"secretsProvider": SecretsProvider reference, required

The "SecretsProvider" to use to obtain the passwordSecretId. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

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

Accessing a Resource Protected by HTTP Basic Authentication
Set Up the Example

  1. Add the following script to the IG configuration as $HOME/.openig/scripts/groovy/BasicAuthResourceServerFilter.groovy (on Windows, %appdata%\OpenIG\scripts\groovy\BasicAuthResourceServerFilter.groovy): 

    /**
 * This script is a simple implementation of HTTP Basic 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
 *  - password: the expected password
 */

import static org.forgerock.util.promise.Promises.newResultPromise;

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

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

String expectedAuthorization = "Basic " + Base64.encode((username + ":" + password).getBytes(Charset.defaultCharset()))
if (!expectedAuthorization.equals(authorizationHeader)) {
    return newResultPromise(new Response(Status.FORBIDDEN));
}
// Credentials are as expected, let's continue
return next.handle(context, request);

    The script is a simple implementation of the HTTP Basic Authentication mechanism.

    For information about scripting filters and handlers, see Extending IG.

  2. Add the following route to IG: 

    $HOME/.openig/config/routes/http-basic-access.json
    %appdata%\OpenIG\config\routes\http-basic-access.json
    {
  "name": "http-basic-access",
  "baseURI": "http://openig.example.com:8080",
  "condition" : "${matches(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.

  3. Add the following route to IG: 

    $HOME/.openig/config/routes/http-basic-protected-resource.json
    %appdata%\OpenIG\config\routes\http-basic-protected-resource.json
    {
  "name": "http-basic-protected-resource",
  "condition": "${matches(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",
              "password": "password"
            }
          }
        }
      ],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": ["text/html"]
          },
          "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 Authentication mechanism, 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://openig.example.com:8080/http-basic-access.

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

Read a different version of :