Ping SDKs

Configure Ping SDK for iOS properties

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

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

Properties

The following properties are available for configuring the Ping SDK for iOS:

Server

Properties
Property name Description Required
FROptions

url

Properties file

forgerock_url

The base URL of the PingAM instance to connect to, including port and deployment path.

Identity Cloud example:

https://openam-forgerock-sdks.forgeblocks.com/am

Self-hosted example:

https://openam.example.com:8443/openam

Required 1
FROptions

realm

Properties file

forgerock_realm

The realm in which the OAuth 2.0 client profile and authentication journeys are configured.

For example, alpha.

Defaults to the self-hosted top-level realm root.

Required 1
FROptions

timeout

Properties file

forgerock_timeout

A timeout, in seconds, for each request that communicates with PingAM.

Default: 30

FROptions

cookieName

Properties file

forgerock_cookie_name

The name of the cookie that contains the session token.

For example, with a self-hosted PingAM server this value might be iPlanetDirectoryPro.

PingOne Advanced Identity Cloud tenants use a random alpha-numeric string.

To locate the cookie name in an PingOne Advanced Identity Cloud tenant, navigate to Tenant settings > Global Settings, and copy the value of the Cookie property.

Default: iPlanetDirectoryPro

Required 1
FROptions

enableCookie

Properties file

forgerock_enable_cookie

When true, enables cookie use.

Default: true

Journeys

Properties
FROptions

authServiceName

Properties file

forgerock_auth_service_name

The name of a user authentication tree configured in your server.

For example, sdkUsernamePasswordJourney.

FROptions

registrationServiceName

Properties file

forgerock_registration_service_name

The name of a user registration tree configured in your server.

For example, sdkRegistrationJourney.

OAuth 2.0

Properties
FROptions

oauthClientId

Properties file

forgerock_oauth_client_id

The client_id of the OAuth 2.0 client profile to use.

For example, sdkNativeClient.

1
FROptions

oauthRedirectUri

Properties file

forgerock_oauth_redirect_uri

The redirect_uri as configured in the OAuth 2.0 client profile.

This value must match a value configured in your OAuth 2.0 client.

For example, org.forgerock.demo://oauth2redirect.

1
FROptions

oauthSignoutRedirectUri

Properties file

forgerock_oauth_sign_out_redirect_uri

The URI to redirect to after signing the user out of the authorization server.

For example, org.forgerock.demo://oauth2redirect.

FROptions

oauthScope

Properties file

forgerock_oauth_scope

A list of scopes to request when performing an OAuth 2.0 authorization flow, separated by spaces.

For example, openid profile email address.

1
FROptions

oauthThreshold

Properties file

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

Properties
FROptions

sslPinningPublicKeyHashes

Properties file

forgerock_ssl_pinning_public_key_hashes

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

FROptions

keychainAccessGroup

Properties file

forgerock_keychain_access_group

Keychain access group for the shared keychain.

Endpoints

Properties
FROptions

authenticateEndpoint

Properties file

forgerock_authenticate_endpoint

Override the path to the authorization server’s authenticate endpoint.

Default: /json/realms/{forgerock_realm}/authenticate

FROptions

authorizeEndpoint

Properties file

forgerock_authorize_endpoint

Override the path to the authorization server’s authorize endpoint.

Default: /oauth2/realms/{forgerock_realm}/authorize

FROptions

tokenEndpoint

Properties file

forgerock_token_endpoint

Override the path to the authorization server’s access_token endpoint.

Default: /oauth2/realms/{forgerock_realm}/access_token

FROptions

revokeEndpoint

Properties file

forgerock_revoke_endpoint

Override the path to the authorization server’s token/revoke endpoint.

Default: /oauth2/realms/{forgerock_realm}/token/revoke

FROptions

userinfoEndpoint

Properties file

forgerock_userinfo_endpoint

Override the path to the authorization server’s userinfo endpoint.

Default: /oauth2/realms/{forgerock_realm}/userinfo

FROptions

sessionEndpoint

Properties file

forgerock_session_endpoint

Override the path to the authorization server’s sessions endpoint.

FROptions

endSessionEndpoint

Properties file

forgerock_endsession_endpoint

Override the path to the authorization server’s endSession endpoint.

Session and token lifecycle

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

  • url

  • realm

  • cookieName

  • oauthClientId

  • oauthRedirectUri

  • oauthScope

Example

The following Swift example shows how to configure the Ping SDK in your iOS applications:

let options = FROptions(
  url: "https://tenant.forgeblocks.com/am",
  realm: "alpha",
  cookieName: "46b42b4229cd7a3",
  oauthClientId: "sdkNativeClient",
  oauthRedirectUri: "org.forgerock.demo://oauth2redirect",
  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.

Using the .well-known endpoint

You can configure the SDKs to obtain many required settings from your authorization server’s .well-known OpenID Connect endpoint.

How do I find my PingOne Advanced Identity Cloud .well-known URL?

You can view the .well-known endpoint for an OAuth 2.0 client in the PingOne Advanced Identity Cloud admin console:

  1. Log in to your PingOne Advanced Identity Cloud administration console.

  2. Click Applications, and then select the OAuth 2.0 client you created earlier. For example, sdkPublicClient.

  3. On the Sign On tab, in the Client Credentials section, copy the Discovery URI value.

    For example, https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration

If you are using a custom domain, your .well-known is formed as follows:

https://<custom-domain-fqdn>/.well-known/openid-configuration

Learn more in Access OIDC configuration discovery endpoint.
How do I find my PingAM .well-known URL?

To form the .well-known URL for an PingAM server, concatenate the following information into a single URL:

  1. The base URL of the PingAM component of your deployment, including the port number and deployment path.

    For example, https://openam.example.com:8443/openam

  2. The string /oauth2

  3. The hierarchy of the realm that contains the OAuth 2.0 client.

    You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword.

    For example, /realms/root/realms/customers

    If you omit the realm hierarchy, the top level ROOT realm is used by default.

  4. The string /.well-known/openid-configuration

For example, https://openam.example.com:8443/openam/oauth2/realms/root/.well-known/openid-configuration

Settings gathered from the endpoint include the paths to use for OAuth 2.0 authorization requests, and login endpoints.

Use the FROptions.discover method to use the .well-known endpoint to configure OAuth 2.0 paths:

let options = try await FROptions(config: config).discover(
  discoveryURL: "https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration")

try FRAuth.start(options: options)