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 |
---|---|---|---|
Server |
|
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; |
||
|
A timeout, in seconds, for each request that communicates with AM (defaults to |
||
|
When |
||
|
The name of the cookie that contains the SSO token, for example, |
||
Journeys |
|
The name of the user authentication tree configured in AM. |
|
|
The name of the user registration tree configured in AM. |
||
OAuth 2.0 |
|
The |
|
|
The |
||
|
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 |
||
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 |
|
|
Override the default path to the AM’s |
||
|
Override the default path to AM’s |
||
|
Override the default path to AM’s |
||
|
Override the default path to AM’s |
||
|
Override the default path to AM’s |
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.