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

Domain Property Description Required

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 (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_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.
Journeys	`forgerock_auth_service_name`	The name of the user *authentication* tree configured in AM.
`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.
`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.

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

Journeys

forgerock_auth_service_name

The name of the user authentication tree configured in AM.

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.

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.

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.

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

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.

ForgeRock SDKs

Dynamic configuration

Dynamic settings

Session and token lifecycle

Limitations

Example