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:
-
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.
-
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.
-
-
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": "${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", "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.
-
-
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.