ForgeRock SDKs

Dynamic configuration

It can sometimes be convenient to change configurations without reinstalling your app. For example, to switch test environments on the fly or to switch to a different service, change the app settings programmatically with dynamic configuration.

Dynamic settings

Use the FROptionsBuilder methods to build an FROptions object, and pass the object to the FRAuth.start() method.

The builder provides access to the settings defined by the following properties:

Domain Property Description Required

Server

forgerock_url

The base URL of the AM instance to connect to, including port and deployment path; for example, https://openam.example.com:8443/openam.

forgerock_realm

The realm where the OAuth 2.0 client profile is configured (defaults to the top-level realm; root).

forgerock_timeout

A timeout, in seconds, for each request that communicates with AM (defaults to 30 seconds).

forgerock_cookie_name

The name of the cookie that contains the SSO token, for example, iPlanetDirectoryPro. To locate the cookie name in an Identity Cloud tenant, go to Tenant Settings > Global Settings > Server.

forgerock_cookie_cache

Time, in seconds, to cache the SSO token cookie in memory (defaults to 0 seconds).

Journeys

forgerock_auth_service

The name of the user authentication tree configured in AM.

forgerock_registration_service

The name of the user registration tree configured in AM.

OAuth 2.0

forgerock_oauth_client_id

The client_id of the OAuth 2.0 client profile to use.

forgerock_oauth_redirect_uri

The redirect_uri as configured in the OAuth 2.0 client profile.

forgerock_oauth_scope

A list of scopes to request when performing an OAuth 2.0 authorization flow.

forgerock_oauth_threshold

A threshold, in seconds, to refresh an OAuth 2.0 token before the access_token expires (defaults to 30 seconds).

forgerock_oauth_cache

Time, in seconds, to cache an OAuth 2.0 token in memory (defaults to 0 seconds).

SSL pinning

forgerock_ssl_pinning_public_key_hashes

An array of public key certificate hashes (strings) for trusted sites and services.

buildSteps

An array of BuildStep objects to provide additional SSL pinning parameters to OkHttpClient instances.

Custom endpoints

forgerock_authenticate_endpoint

Override the default path to AM’s /json/authenticate endpoint.
Default: /json/realms/{forgerock_realm}/authenticate

forgerock_authorize_endpoint

Override the default path to the AM’s /oauth2/authorize endpoint.
Default: /oauth2/realms/{forgerock_realm}/authorize

forgerock_token_endpoint

Override the default path to AM’s /oauth2/access_token endpoint.
Default: /oauth2/realms/{forgerock_realm}/access_token

forgerock_revoke_endpoint

Override the default path to AM’s /oauth2/token/revoke endpoint.
Default: /oauth2/realms/{forgerock_realm}/token/revoke

forgerock_userinfo_endpoint

Override the default path to AM’s /oauth2/userinfo endpoint.
Default: /oauth2/realms/{forgerock_realm}/userinfo

forgerock_session_endpoint

Override the default path to AM’s /json/sessions endpoint.

In addition, the Android SDK lets you configure the log level and a custom logger.

Session and token lifecycle

The SDK revokes and removes persisted tokens when any of the following change during initialization:

  • forgerock_cookie_name

  • forgerock_oauth_client_id

  • forgerock_oauth_redirect_uri

  • forgerock_oauth_scope

  • forgerock_realm

  • forgerock_url

Limitations

  • Apps do not manage tokens from multiple servers, only those of the currently active server.

  • Dynamic configuration is not persistent.

  • Dynamic configuration applies to core configuration, not extensions such as callback overrides, device profile configuration, and request interception.

  • FRUI pre-defined UI elements do not use dynamic configuration.

Examples

The following examples use dynamic configuration.

When the application calls FRAuth.start(), the FRAuth class checks for the presence of an FROptions object. If the object is not present, static initialization from strings.xml happens. If the object is present, the FRAuth class uses the options object and calls the same internal initialization method.

The app can call FRAuth.start() multiple times in its lifecycle:

  • When the app calls FRAuth.start() for the first time in its lifecycle, the SDK checks for the presence of session and access tokens in the local storage. If an existing session is present, initialization does not log the user out.

  • If the app calls FRAuth.start() again, the SDK checks whether session managers and token managers are initialized, and cleans the existing session and token storage. This ensures that changes to the app configuration remove and revoke existing sessions and tokens.

Java

FROptions options = FROptionsBuilder.build(frOptionsBuilder -> {
    frOptionsBuilder.server(serverBuilder -> {
        serverBuilder.setUrl("https://tenant.forgeblocks.com/am");
        serverBuilder.setRealm("alpha");
        serverBuilder.setCookieName("46b42b4229cd7a3");
        return null;
    });
    frOptionsBuilder.oauth(oAuthBuilder -> {
        oAuthBuilder.setOauthClientId("androidClient");
        oAuthBuilder.setOauthRedirectUri("https://sdkapp.example.com:8443/callback");
        oAuthBuilder.setOauthScope("openid profile email address");
        return null;
    });
    frOptionsBuilder.service(serviceBuilder -> {
        serviceBuilder.setAuthServiceName("Login");
        serviceBuilder.setRegistrationServiceName("Registration");
        return null;
    });
    return null;
});
FRAuth.start(this, options);

Kotlin

val options = FROptionsBuilder.build {
    server {
       url = "https://tenant.forgeblocks.com/am"
       realm = "alpha"
       cookieName = "46b42b4229cd7a3"
    }
    oauth {
       oauthClientId = "androidClient"
       oauthRedirectUri = "https://sdkapp.example.com:8443/callback"
       oauthScope = "openid profile email address"
    }
    service {
       authServiceName = "Login"
       registrationServiceName = "Registration"
    }
}

FRAuth.start(this, options);
Copyright © 2010-2022 ForgeRock, all rights reserved.