Configure the SDKs dynamically

Applies to:

ForgeRock SDK for Android
ForgeRock SDK for iOS
ForgeRock SDK for JavaScript

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.

Android
iOS

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:

ForgeRock SDK for Android dynamic properties
Domain	Property	Description
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. Default: `root`
	`forgerock_timeout`	A timeout, in seconds, for each request that communicates with AM. Default: `30`
	`forgerock_cookie_name`	The name of the cookie that contains the session token, for example, `iPlanetDirectoryPro`. To locate the cookie name in an Identity Cloud tenant, go to Tenant settings > Global Settings > Cookie. Default: `iPlanetDirectoryPro`
	`forgerock_cookie_cache`	Time, in seconds, to cache the session token cookie in memory. Default: `0`
Journeys	`forgerock_auth_service`	The name of the user *authentication* tree configured in AM.
Journeys	`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.
SSL pinning	`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.

Use the FROptions interface to build an options object and pass the object to the FRAuth.start() method.

The options object provides access to the settings defined by the following properties. These settings are the same as the properties in FRAuthConfig.plist:

ForgeRock SDK for iOS dynamic properties
Domain	Property	Description
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. Default: `root`
	`forgerock_timeout`	A timeout, in seconds, for each request that communicates with AM (defaults to `30` seconds).
	`forgerock_enable_cookie`	When `true`, enables cookie use (defaults to `true`).
	`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. Default: `iPlanetDirectoryPro`
Journeys	`forgerock_auth_service_name`	The name of the user *authentication* tree configured in AM.
Journeys	`forgerock_registration_service_name`	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).
SSL pinning	`forgerock_ssl_pinning_public_key_hashes`	An array of public key certificate hashes (strings) for trusted sites and services.
SSL pinning	`forgerock_keychain_access_group`	Keychain access group for the shared keychain.
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.

You must provide a value for properties that are marked as required.

The SDK throws an exception if you provide an empty string for a required property.

Session and token lifecycle

The SDK revokes and removes persisted tokens if you change any of the following properties dynamically:

forgerock_cookie_name
forgerock_oauth_client_id
forgerock_oauth_redirect_uri
forgerock_oauth_scope
forgerock_realm
forgerock_url

Android example

The following examples use dynamic configuration.

Android - Java
Android - Kotlin

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);

val options = FROptionsBuilder.build {
    server {
       url = "https://openam-forgerock-sdks.forgeblocks.com/am"
       realm = "alpha"
       cookieName = "iPlanetDirectoryPro"
    }
    oauth {
       oauthClientId = "sdkPublicClient"
       oauthRedirectUri = "https://sdkapp.example.com:8443/callback"
       oauthScope = "openid profile email address phone"
    }
    service {
       authServiceName = "Login"
       registrationServiceName = "Registration"
    }
}

FRAuth.start(this, options);

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.

iOS example

The following Swift example uses dynamic configuration.

let options = FROptions(url: "https://tenant.forgeblocks.com/am",
                        realm: "alpha",
                        cookieName: "46b42b4229cd7a3",
                        oauthClientId: "iosClient",
                        oauthRedirectUri: "frauth://com.forgerock.ios.frexample",
                        oauthScope: "openid profile email address phone",
                        authServiceName: "Login",
                        registrationServiceName: "Register")
try FRAuth.start(options: options)

When the application calls FRAuth.start(), the FRAuth class checks for the presence of an FROptions object. If the object is not present, the static initialization from FRAuthConfig.plist happens. If the object is present, the FRAuth class converts it to a [String, Any] dictionary and calls the same internal initialization method.