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



The base URL of the AM instance to connect to, including port and deployment path; for example,


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


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


When true, enables cookie use (defaults to true).


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.



The name of the user authentication tree configured in AM.


The name of the user registration tree configured in AM.

OAuth 2.0


The client_id of the OAuth 2.0 client profile to use.


The redirect_uri as configured in the OAuth 2.0 client profile.


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


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

SSL pinning


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


Keychain access group for the shared keychain.

Custom endpoints


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


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


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


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


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


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


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


The following Swift example uses dynamic configuration.

let options = FROptions(url: "",
                        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.

Copyright © 2010-2023 ForgeRock, all rights reserved.