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

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

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

HttpBasicAuthenticationClientFilter
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 ):

    /*
     * Copyright 2020 ForgeRock AS. All Rights Reserved
     *
     * Use of this code requires a commercial software license with ForgeRock AS.
     * or with one of its affiliates. All use shall be exclusively subject
     * to such license between the licensee and ForgeRock AS.
     */
    /**
     * 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 Extend IG.

  2. Add the following route to IG:

    • Linux

    • Windows

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

    • Linux

    • Windows

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