Ping SDKs with OIDC login

Introducing the Ping SDKs for OIDC login

Server support:

PingOne
PingOne Advanced Identity Cloud
PingAM
PingFederate

SDK support:

Ping SDK for Android
Ping SDK for iOS
Ping SDK for JavaScript

The Ping SDKs can help you to login to your authorization server using an OpenID Connect flow, and leveraging the server’s own UI to authenticate your users in your apps.

We call this OIDC login, but it was previously known as centralized login.

With this option, you reuse the same, centralized UI for login requests in multiple apps and sites.

When a user attempts to log in to your app they are redirected to your server’s central login UI. After the user authenticates, they are redirected back to your app.

Changes to authentication journeys or DaVinci flows are immediately reflected in all apps that use OIDC login without the need to rebuild or update the client app.

Likewise, any features your server’s UI supports are also available for use in your web or mobile apps.

Figure 1. Centralized login in Android

Use cases

If you require a consistent UI and user experience (UX) in all your apps and sites, using centralized login may be the best option.

Simple branding and control over your authentication UX is sufficient.

Your mobile apps use browser-based single sign-on.

Security considerations

Using centralized login in apps built by a third party is safer than using embedded login.

Third parties cannot access user credentials.

User credentials are authenticated in one domain/origin and not sent elsewhere for authentication.

Your apps and sites can use browser-based single sign-on.

Next steps

Configure the Ping SDKs for OIDC login

Tutorials

Configure the Ping SDKs for OIDC login

The Ping SDKs are designed to be flexible and can be customized to suit many different situations.

Learn more about configuring and customizing the Ping SDKs in the sections below:

Configure OIDC login

Learn how to configure your apps to use your authorization server’s UI or your own web application for login requests.

Learn more

Configure ACR parameters

Utilize an Authentication Context Class Reference (ACR) parameter to choose which authentication journey or DaVinci flow the user should complete.

Learn more

Configure OIDC login

You can configure your apps to use your authorization server’s UI or your own web application for login requests.

When a user attempts to log in to your app it redirects them to the central login UI. After the user authenticates, the authorization server redirects them back to your application or site.

Changes to authentication journeys or flows on your authorization server are available to all your apps that use the OIDC login method. Your app does not need to access user credentials directly, just the result of the authentication from the server - usually an access token.

Select your platform below to learn how to configure your app to use OIDC login:

Android

Configure Ping SDK for Android apps to perform OIDC login.

iOS

Configure Ping SDK for iOS apps to perform OIDC login.

JavaScript

Configure Ping SDK for JavaScript apps to perform OIDC login.

Configure Android apps for OIDC login

This section describes how to configure your Ping SDK for Android application to use centralized login by leveraging the AppAuth library:

Add the build dependency to the build.gradle file:
```
implementation 'net.openid:appauth:0.11.1'
```
Associate your application with the scheme your redirect URIs use.

To ensure that only your app is able to obtain authorization tokens during centralized login we recommend you configure it to use Android App Links.

If you do not want to implement Android App Links, you can instead use a custom scheme for your redirect URIs.
- Android App Links
- Custom Scheme
Complete the following steps to configure App Links:
In your application, configure the AppAuth library to use the HTTP scheme for capturing redirect URIs, by adding an <intent-filter> for AppAuth.RedirectUriReceiverActivity to your AndroidManifest.xml:

AndroidManifest.xml

<activity android:name="net.openid.appauth.RedirectUriReceiverActivity" android:exported="true" tools:node="replace"> <intent-filter android:autoVerify="true"> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="https" /> <data android:host="android.example.com" /> <data android:path="/oauth2redirect" /> </intent-filter> </activity>

You must set android:autoVerify to true. This instructs Android to verify the against the assetlinks.json file you update in the next step.

Specify the scheme, hosts, and path parameters that will be used in your redirect URIs. The host value must match the domain where you upload the assetlinks.json file.

To learn more about intents, refer to Add intent filters in the Android Developer documentation.

To learn more about redirects and the AppAuth library, refer to Capturing the authorization redirect.

For Android 11 or higher, add the following to the AndroidManfest.xml file:

<queries> <intent> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="https" /> </intent> </queries>

Create or update a Digital Asset Links (assetlinks.json) file that associates your app with the domain.

You must host the file in a .well-known folder on the same host that you entered in the intent filter earlier.

The file will resemble the following:

https://android.example.com/.well-known/assetlinks.json

[ { "relation": [ "delegate_permission/common.handle_all_urls", ], "target": { "namespace": "android_app", "package_name": "com.example.app", "sha256_cert_fingerprints": [ "c4:15:c8:f1:...:fe:ce:d7:37" ] } } ]

To learn more, refer to Associate your app with your website in the Android Developer documentation.

Upload the completed file to the domain that matches the host value you configured in the earlier step.

For information on uploading an assetLinks.json file to an Advanced PingOne Advanced Identity Cloud instance, refer to Upload an Android assetlinks.json file.

Add the following to the strings.xml file:

<string name="forgerock_oauth_redirect_uri" translatable="false">https://android.example.com/oauth2redirect</string>

Add the App Link to the Redirection URIs property of your OAuth 2.0 client. For example, https://android.example.com/oauth2redirect
Complete the following steps to configure a custom scheme:
Configure the AppAuth library to use the custom scheme for capturing redirect URIs by using either of these two methods:

Add the custom scheme your app will use to your build.gradle file:

android.defaultConfig.manifestPlaceholders = [ 'appAuthRedirectScheme': 'com.forgerock.android' ]

Or:

Add an <intent-filter> for AppAuth.RedirectUriReceiverActivity to your AndroidManifest.xml:

<activity android:name="net.openid.appauth.RedirectUriReceiverActivity" tools:node="replace"> <intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:scheme="com.forgerock.android"/> </intent-filter> </activity>

For more information, refer to Capturing the authorization redirect.

For Android 11 or higher, add the following to the AndroidManfest.xml file:

<queries> <intent> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="com.forgerock.android" /> </intent> </queries>

Configure your application to use the redirect URI, either in the strings.xml file, or by using FROptions:

strings.xml:

<string name="forgerock_oauth_redirect_uri" translatable="false">com.forgerock.android:/oauth2redirect</string>

FROptions:

let options = FROptions( ..., oauthRedirectUri: "com.forgerock.android:/oauth2redirect", ..., )

Add the custom scheme to the Redirection URIs property of your OAuth 2.0 client. For example, com.forgerock.android:/oauth2redirect

Configure your application to use browser mode:

// Use FRUser.browser() to enable browser mode:
FRUser.browser().login(context, new FRListener<FRUser>());

// Use standard SDK interface to retrieve an AccessToken:
FRUser.getCurrentUser().getAccessToken()

// Use standard SDK interface to logout a user:
FRUser.getCurrentUser().logout()

The SDK uses the OAuth 2.0 parameters you configured in your application.

You can amend the example code above to customize the integration with AppAuth; for example, adding OAuth 2.0 or OpenID Connect parameters, and browser colors:

 FRUser.browser().appAuthConfigurer()
     .authorizationRequest(r -> {
         // Add a login hint parameter about the user:
         r.setLoginHint("demo@example.com");
         // Request that the user re-authenticates:
         r.setPrompt("login");
     })
     .customTabsIntent(t -> {
         // Customize the browser:
         t.setShowTitle(true);
         t.setToolbarColor(getResources().getColor(R.color.colorAccent));
     }).done()
     .login(this, new FRListener<FRUser>() {
         @Override
         public void onSuccess(FRUser result) {
             //success
         }

         @Override
         public void onException(Exception e) {
             //fail
         }
     });

Configure iOS apps for OIDC login

This section describes how to configure your Ping SDK for iOS application to use centralized login:

Associate your application with the scheme your redirect URIs use.

To ensure that only your app is able to obtain authorization tokens during centralized login we recommend you configure it to use Universal Links.

If you do not want to implement Universal Links, you can instead use a custom scheme for your redirect URIs.
- Apple Universal Links
- Custom scheme
Complete the following steps to configure Universal Links:
In Xcode, in the Project Navigator, double-click your application to open the Project pane.

On the Signing & Capabilities tab, click Capability, type Associated Domains, and then double click the result to add the capability.

In Domains, click the Add () button, and enter applinks:, followed by the hostname that will be used in your redirect URIs.

The host value must match the domain where you upload the apple-app-site-association file.

Create or update an apple-app-site-association file that associates your app with the domain.

You must host the file in a .well-known folder on the same host that you entered in the intent filter earlier.

The file will resemble the following:

https://ios.example.com/.well-known/apple-app-site-association

{ "applinks": { "details": [ { "appIDs": [ "XXXXXXXXXX.com.example.AppName" ], "components": [ { "/": "/oauth2redirect", "comment": "Associate my app with the OAuth 2.0 redirect URI." } ] } ] } }

Upload the completed file to the domain that matches the host value you configured in the earlier step.

For information on uploading an apple-app-site-association file to an Advanced PingOne Advanced Identity Cloud instance, refer to Upload an iOS apple-app-site-association file.

For learn more information about Universal Links and associating domains, refer to the following in the Apple Developer documentation:

Supporting universal links in your app

Supporting associated domains

Add the Universal Link to the Redirection URIs property of your OAuth 2.0 client. For example, https://ios.example.com/oauth2redirect
Configure a custom URL type, for example frauth, so that users are redirected to your application:
In Xcode, in the Project Navigator, double-click your application to open the Project pane.

On the Info tab, in the URL Types panel, configure your custom URL scheme:

Add the custom URL scheme to the Redirection URIs property of your OAuth 2.0 client:

Update your application to call the validateBrowserLogin() function:

In your AppDelegate.swift file, call the validateBrowserLogin() function:

AppDelegate.swift

class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    // Parse and validate URL, extract authorization code, and continue the flow:
    Browser.validateBrowserLogin(url)
  }
}

If you are using Universal Links, also add code similar to the following to set the URL:

AppDelegate.swift

func application(
  _ application: UIApplication,
  continue userActivity: NSUserActivity,
  restorationHandler:
  @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool
  {
    // Get URL components from the incoming user activity.
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
    let incomingURL = userActivity.webpageURL else {
      return false
    }
    Browser.validateBrowserLogin(url)
  }
)

If your application is using SceneDelegate, in your SceneDelegate.swift file call the validateBrowserLogin() function:

SceneDelegate.swift

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    if let url = URLContexts.first?.url {
      Browser.validateBrowserLogin(url)
    }
  }
}

To enable centralized login, add code similar to the following to your app:

//  BrowserBuilder
let browserBuilder = FRUser.browser()
browserBuilder.set(presentingViewController: self)
browserBuilder.set(browserType: .authSession)
browserBuilder.setCustomParam(key: "custom_key", value: "custom_val")

//  Browser
let browser = browserBuilder.build()

// Login
browser.login{ (user, error) in
  if let error = error {
    // Handle error
  }
  else if let user = user {
    // Handle authenticated status
  }
}

You can specify what type of browser the client iOS device opens to handle centralized login.

+ Each browser has slightly different characteristics, which make them suitable to different scenarios, as outlined in this table:

Browser type Characteristics

Browser type	Characteristics
`.authSession`	Opens a web authentication session browser. Designed specifically for authentication sessions, however it prompts the user before opening the browser with a modal that asks them to confirm the domain is allowed to authenticate them. This is the default option in the Ping SDK for iOS.
`.ephemeralAuthSession`	Opens a web authentication session browser, but enables the `prefersEphemeralWebBrowserSession` parameter. This browser type does not prompt the user before opening the browser with a modal. The difference between this and `.authSession` is that the browser does not include any existing data such as cookies in the request, and also discards any data obtained during the browser session. This means that an `ephemeralAuthSession` is not suitable when you require single sign-on (SSO) between your iOS apps. Use this browser type when you do not want the user’s existing sessions to affect the authentication.
`.nativeBrowserApp`	Opens the installed browser that is marked as the default by the user. Often Safari. The browser opens without any interaction from the user. However, the browser does display a modal when returning to your application.
`.sfViewController`	Opens a Safari view controller browser. Your client app is *not* able to interact with the pages in the `sfViewController` or access the data or browsing history. The view controller opens within your app without any interaction from the user. As the user does not leave your app, the view controller does not need to display a warning modal when authentication is complete and control returns to your application.

.authSession

Opens a web authentication session browser.

Designed specifically for authentication sessions, however it prompts the user before opening the browser with a modal that asks them to confirm the domain is allowed to authenticate them.

This is the default option in the Ping SDK for iOS.

.ephemeralAuthSession

Opens a web authentication session browser, but enables the prefersEphemeralWebBrowserSession parameter.

This browser type does not prompt the user before opening the browser with a modal.

The difference between this and .authSession is that the browser does not include any existing data such as cookies in the request, and also discards any data obtained during the browser session. This means that an ephemeralAuthSession is not suitable when you require single sign-on (SSO) between your iOS apps.

Use this browser type when you do not want the user’s existing sessions to affect the authentication.

.nativeBrowserApp

Opens the installed browser that is marked as the default by the user. Often Safari.

The browser opens without any interaction from the user. However, the browser does display a modal when returning to your application.

.sfViewController

Opens a Safari view controller browser.

Your client app is not able to interact with the pages in the sfViewController or access the data or browsing history.

The view controller opens within your app without any interaction from the user. As the user does not leave your app, the view controller does not need to display a warning modal when authentication is complete and control returns to your application.

Configure JavaScript apps for OIDC login

This section describes how to configure your Ping SDK for JavaScript application with centralized login:

To initiate authentication by redirecting to the centralized login UI, add a login property that specifies how authentication happens in your app:

const tokens = TokenManager.getTokens({
  forceRenew: false, // Immediately return stored tokens, if they exist
  login: 'redirect' // Redirect to {am_name} or the web app that handles authentication
});

Supported values are as follows:

Setting Description

Setting	Description
`redirect`	Your app uses a redirect to PingAM, or another web application, to handle authentication.
`embedded`	Your app handles authentication natively, using SDK functionality.

redirect

Your app uses a redirect to PingAM, or another web application, to handle authentication.

embedded

Your app handles authentication natively, using SDK functionality.

If you do not specify a value, embedded is assumed, for backwards-compatibility.

When the user is returned to your app, complete the OAuth 2.0 flow by passing in the code and state values that were returned.

Use the query property to complete the flow:

const tokens = TokenManager.getTokens({
  query: {
    code: 'lFJQYdoQG1u7nUm8 ... ', // Authorization code from redirect URL
    state: 'MTY2NDkxNTQ2Nde3D ... ', // State from redirect URL
  },
});

Specifying authentication journeys using ACR values

The Ping SDKs for Android, iOS, and JavaScript leverage the standards-based authorization code flow with PKCE.

When using OIDC login the client app can request which flow the authorization server uses by adding an Authentication Context Class Reference (ACR) parameter during the process.

In the OpenID Connect specification the ACR parameter identifies a set of criteria that the user must satisfy when authenticating to the OpenID provider. For example, which authentication journey or DaVinci flow the user should complete.

Adding ACR parameters

Select your platform below to learn how to add an ACR parameter to your applications.

Android
iOS
JavaScript

In the FRUser.browser() method, use the setAdditionalParameters function to add an acr_values parameter, and one or more ACR values:

FRUser.browser().appAuthConfigurer()
 .authorizationRequest(r → {
     Map<String, String> additionalParameters = new HashMap<>();
     additionalParameters.put("acr_values", "RegistrationJourney");
     r.setAdditionalParameters(additionalParameters)
 })
 .done()
 .login(this, new FRListener<FRUser>() {
     @Override
     public void onSuccess(FRUser result) {
         userinfo();
     }

     @Override
     public void onException(Exception e) {
         System.out.println(e);
     }
 });

Replace RegistrationJourney with the ACR key that your authorization server requires.

PingOne

Enter a single DaVinci policy, by using its flow policy ID, or one or more PingOne policies by specifying the policy names, separated by spaces or the encoded space character %20.

Examples:

DaVinci flow policy ID: "d1210a6b0b2665dbaa5b652221badba2"
PingOne policy names: "Single_Factor%20Multi_Factor"

PingOne Advanced Identity Cloud or PingAM

Enter one or more of the ACR mapping keys as configured in the OAuth 2.0 provider service.

To learn more, refer to Configure acr claims.

You can list the available keys by inspecting the acr_values_supported property in the output of your OAuth 2.0 client’s /oauth2/.well-known/openid-configuration endpoint.

In the FRUser.browser() method, use the setCustomParam function to add an acr_values key parameter, and one or more ACR values:

func performCentralizedLogin() {
     FRUser.browser()?
         .set(presentingViewController: self)
         .set(
            browserType: .authSession)
         #.setCustomParam(
            key: "acr_values",
            value: "RegistrationJourney")
         .build().login { (user, error) in
             self.displayLog("User: \(String(describing: user)) || Error: \(String(describing: error))")
     }
     return
 }

Replace RegistrationJourney with the ACR key that your authorization server requires.

PingOne

Enter a single DaVinci policy, by using its flow policy ID, or one or more PingOne policies by specifying the policy names, separated by spaces or the encoded space character %20.

Examples:

DaVinci flow policy ID: "d1210a6b0b2665dbaa5b652221badba2"
PingOne policy names: "Single_Factor%20Multi_Factor"

PingOne Advanced Identity Cloud or PingAM

Enter one or more of the ACR mapping keys as configured in the OAuth 2.0 provider service.

To learn more, refer to Configure acr claims.

You can list the available keys by inspecting the acr_values_supported property in the output of your OAuth 2.0 client’s /oauth2/.well-known/openid-configuration endpoint.

In the TokenManager.getTokens() method, add an acr_values query parameter, and one or more ACR values:

await TokenManager.getTokens({
  login: 'redirect',
  query: {
    acr_values: "RegistrationJourney"
  }
});

Replace RegistrationJourney with the ACR key that your authorization server requires.

PingOne

Enter a single DaVinci policy, by using its flow policy ID, or one or more PingOne policies by specifying the policy names, separated by spaces or the encoded space character %20.

Examples:

DaVinci flow policy ID: "d1210a6b0b2665dbaa5b652221badba2"
PingOne policy names: "Single_Factor%20Multi_Factor"

PingOne Advanced Identity Cloud or PingAM

Enter one or more of the ACR mapping keys as configured in the OAuth 2.0 provider service.

To learn more, refer to Configure acr claims.

You can list the available keys by inspecting the acr_values_supported property in the output of your OAuth 2.0 client’s /oauth2/.well-known/openid-configuration endpoint.

Ping SDK OIDC login tutorials

Learn how your apps can authenticate users with an OpenID Connect flow.

The tutorials show how your apps can leverage the user interface each server provides, centralizing the experience across your apps.

To start, choose the platform to host your app:

Android

Android OIDC login tutorials

iOS

iOS OIDC login tutorials

JavaScript

JavaScript OIDC login tutorials

Android OIDC login tutorials

Follow these Android tutorials to integrate your apps using OpenID Connect login to the following servers:

PingOne

PingOne Advanced Identity Cloud

PingAM

PingFederate

OIDC login to PingOne tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingOne UI for authentication.

The sample connects to the .well-known endpoint of your PingOne server to obtain the correct URIs to authenticate the user, and redirects to your PingOne server’s login UI.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingOne server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne.

Start step 2

Step 3. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingOne server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne server.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingOne instance.

Compatibility

Android: This sample requires at least Android API 23 (Android 6.0)
Java: This sample requires at least Java 8 (v1.8).

Prerequisites

Android Studio: Download and install Android Studio, which is available for many popular operating systems.
An Android emulator or physical device: To try the quick start application as you develop it, you need an Android device. To add a virtual, emulated Android device to Android Studio, refer to Create and manage virtual devices, on the Android Developers website.

Server configuration

This tutorial requires you to configure your PingOne server as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingOne, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Directory > Users.
Next to the Users label, click the plus icon ().

PingOne displays the Add User panel.
Enter the following details:
- Given Name = Demo
- Family Name = User
- Username = demo
- Email = demo.user@example.com
- Population = Default
- Password = Ch4ng3it!
Click Save.

Task 2. Create a revoke resource

To allow the Ping SDKs to revoke access tokens issued by PingOne, you must create a custom resource that is assigned the revoke scope in your PingOne tenant.

To create a custom resource and assign the revoke scope, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Applications > Resources.
Next to the Resources label, click the plus icon ().

PingOne displays the Add Custom Resource panel.
In Resource Name, enter a name for the custom resource, for example SDK Revoke Resource, and then click Next.
On the Attributes page, click Next.
On the Scopes page, click Add Scope.
In Scope Name, enter revoke, and then click Save.

When you have created the custom resource in your PingOne instance, continue with the next step.

For more information on resources in PingOne, refer to Adding a custom resource.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application in PingOne for use with the Ping SDKs for Android and iOS, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Applications > Applications.
Next to the Applications label, click the plus icon ().

PingOne displays the Add Application panel.
In Application Name, enter a name for the profile, for example sdkNativeClient
Select Native as the Application Type, and then click Save.
On the Configuration tab, click the pencil icon ().
1. In Grant Type, select the following values:
  
  Authorization Code
  
  Refresh Token
2. In Redirect URIs, enter the following value:
  
  org.forgerock.demo://oauth2redirect
3. In Token Endpoint Authentication Method, select None.
4. In Signoff URLs, enter the following value:
  
  org.forgerock.demo://oauth2redirect
5. Click Save.
On the Resources tab, next to Allowed Scopes, click the pencil icon ().
1. In Scopes, select the following values:
  
  email
  
  phone
  
  profile
  
  SDK Revoke Resource
  
  The openid scope is selected by default.
  
  The result resembles the following:
  
  Figure 2. Adding scopes, including the custom "revoke" scope to an application.
Optionally, on the Policies tab, click the pencil icon () to select the authentication policies for the application.

Applications that have no authentication policy assignments use the environment’s default authentication policy to authenticate users.

If you have a DaVinci license, you can select PingOne policies or DaVinci Flow policies, but not both. If you do not have a DaVinci license, the page only displays PingOne policies.

To use a PingOne policy:
1. Click Add policies and then select the policies that you want to apply to the application.
2. Click Save.
  
  PingOne applies the policies in the order in which they appear in the list. PingOne evaluates the first policy in the list first. If the requirements are not met, PingOne moves to the next one.
  
  For more information, see Authentication policies for applications.
To use a DaVinci Flow policy:
1. You must clear all PingOne policies. Click Deselect all PingOne Policies.
2. In the confirmation message, click Continue.
3. On the DaVinci Policies tab, select the policies that you want to apply to the application.
4. Click Save.
  
  PingOne applies the first policy in the list.
Click Save.
Enable the OAuth 2.0 client application by using the toggle next to its name:

Figure 3. Enable the application using the toggle.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Android and iOS PingOne example applications and tutorials covered by this documentation.

Step 1. Download the samples

To start this tutorial, you need to download the ForgeRock SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the "kotlin-ui-prototype" sample to connect to the OAuth 2.0 application you created in PingOne, using OIDC login.

In Android Studio, open the sdk-sample-apps/android/kotlin-ui-prototype project you cloned in the previous step.
In the Project pane, switch to the Android view.
In the Android view, navigate to app > kotlin+java > com.example.app > env, and open EnvViewModel.kt.

This file contains the server environments the sample app can use. Each specifies the properties using the FROptionsBuilder.build method.

Add the following after any existing environments, with a suitable name. For example, you could use the name of the OAuth 2.0 client, sdkNativeClient:

val sdkNativeClient = FROptionsBuilder.build {
    server {
        url = "<PingOne Issuer URL>"
    }
    oauth {
        oauthClientId = "<PingOne Client ID>"
        oauthRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthSignOutRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthScope = "openid profile email address revoke"
    }
}

Replace the following strings with the values you obtained when you registered an OAuth 2.0 application for native mobile apps in PingOne.

<PingOne Client ID>

The client ID from your OAuth 2.0 native mobile application in PingOne.

For example, 6c7eb89a-66e9-ab12-cd34-eeaf795650b2

<PingOne Issuer URL>

The Issuer endpoint from your OAuth 2.0 application in PingOne.

For example, https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as

The issuer URL is the same as the OIDC Discovery Endpoint, after removing /.well-known/openid-configuration.

The result resembles the following:

val sdkNativeClient = FROptionsBuilder.build {
    server {
        url = "https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as"
    }
    oauth {
        oauthClientId = "6c7eb89a-66e9-ab12-cd34-eeaf795650b2"
        oauthRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthSignOutRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthScope = "openid profile email address revoke"
    }
}

In the init object, add your configuration to the list of servers available to the app:
The result resembles the following:
init { servers.add(localhost) // ... servers.add(sdkNativeClient) }

Optionally, specify which of the configured policies PingOne uses to authenticate users.

In /app/kotlin+java/com.example.app/centralize/CentralizeLoginViewModel, in the login(fragmentActivity: FragmentActivity) function, add an acr_values parameter to the authorization request by using the setAdditionalParameters() method:

fun login(fragmentActivity: FragmentActivity) {
  FRUser.browser().appAuthConfigurer()
    // Add acr values to the authorization request
    .authorizationRequest{
      it.setAdditionalParameters(
        mapOf(
          "acr_values" to "<Policy IDs>"
        )
      )
    }
    .customTabsIntent {
      it.setColorScheme(CustomTabsIntent.COLOR_SCHEME_DARK)
    }.appAuthConfiguration { appAuthConfiguration → }
    .done()
    .login(fragmentActivity,
        object : FRListener<FRUser> {
            override fun onSuccess(result: FRUser) {
              state.update {
                  it.copy(user = result, exception = null)
              }
            }

            override fun onException(e: Exception) {
                state.update {
                    it.copy(user = null, exception = e)
                }
            }
        }
    )
}

Replace <Policy IDs> with either a single DaVinci policy, by using its flow policy ID, or one or more PingOne policies by specifying the policy names, separated by spaces or the encoded space character %20.

Examples:

DaVinci flow policy ID: "acr_values" to "d1210a6b0b2665dbaa5b652221badba2"
PingOne policy names: "acr_values" to "Single_Factor%20Multi_Factor"

For more information, refer to Editing an application - OIDC.

With the sample configured, you can proceed to Step 3. Test the app.

Step 3. Test the app

In the following procedure, you run the sample app that you configured in the previous step. The app performs a centralized login on your PingOne instance.

Log in as a demo user

In Android Studio, select Run Run 'app'.
On the Environment screen, ensure the PingOne environment you added in the previous step is selected.

Figure 4. Select the PingOne environment
Tap the menu icon (), and then tap Centralize Login:

Figure 5. From the menu, select Centralize Login.

The app launches a web browser and redirects to your PingOne environment:

Figure 6. Browser launched and redirected to PingOne
Sign on as a demo user:
- Name: demo
- Password: Ch4ng3it!
If authentication is successful, the application returns to the user info screen.
Tap Show Userinfo to display the details of the token issues to the demo user:

Figure 7. User info of the demo user

Tap the menu icon (), and then tap Logout.

The app briefly opens a browser to log the user out of PingOne, and revoke the tokens.

To verify the user is logged out:

In the PingOne administration console, navigate to Directory > Users.
Select the user you signed in as.
From the Sevices dropdown, select Authentication:

Figure 8. Checking a user’s sessions in PingOne.

The Sessions section displays any existing sessions the user has, and whether they originate from a mobile device.

OIDC login to PingOne Advanced Identity Cloud tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingOne Advanced Identity Cloud UI for authentication.

The sample connects to the .well-known endpoint of your PingOne Advanced Identity Cloud server to obtain the correct URIs to authenticate the user, and redirects to your PingOne Advanced Identity Cloud server’s login UI.

After authentication, PingOne Advanced Identity Cloud redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingOne Advanced Identity Cloud server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud.

Start step 2

Step 3. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingOne Advanced Identity Cloud server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne Advanced Identity Cloud server.

After authentication, PingOne Advanced Identity Cloud redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingOne Advanced Identity Cloud tenant.

Compatibility

Android: This sample requires at least Android API 23 (Android 6.0)
Java: This sample requires at least Java 8 (v1.8).

Prerequisites

Android Studio: Download and install Android Studio, which is available for many popular operating systems.
An Android emulator or physical device: To try the quick start application as you develop it, you need an Android device. To add a virtual, emulated Android device to Android Studio, refer to Create and manage virtual devices, on the Android Developers website.

Server configuration

This tutorial requires you to configure your PingOne Advanced Identity Cloud tenant as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
In the left panel, click Identities > Manage.
Click New Alpha realm - User.
Enter the following details:
- Username = demo
- First Name = Demo
- Last Name = User
- Email Address = demo.user@example.com
- Password = Ch4ng3it!
Click Save.

Task 2. Create an authentication journey

Authentication journeys provide fine-grained authentication by allowing multiple paths and decision points throughout the flow. Authentication journeys are made up of nodes that define actions taken during authentication.

Each node performs a single task, such as collecting a username or making a simple decision. Nodes can have multiple outcomes rather than just success or failure. For details, see the Authentication nodes configuration reference in the PingAM documentation.

To create a simple journey for use when testing the Ping SDKs, follow these steps:

In your PingOne Advanced Identity Cloud tenant, navigate to Journeys, and click New Journey.
Enter a name, such as sdkUsernamePasswordJourney and click Save.

The authentication journey designer appears.
Drag the following nodes into the designer area:
- Page Node
- Platform Username
- Platform Password
- Data Store Decision
Drag and drop the Platform Username and Platform Password nodes onto the Page Node, so that they both appear on the same page when logging in.
Connect the nodes as follows:

Figure 9. Example username and password authentication journey
Click Save.

Task 3. Register a public OAuth 2.0 client

Public clients do not use a client secret to obtain tokens because they are unable to keep them hidden. The Ping SDKs commonly use this type of client to obtain tokens, as they cannot guarantee safekeeping of the client credentials in a browser or on a mobile device.

To register a public OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
In the left panel, click Applications.
Click Custom Application.
Select OIDC - OpenId Connect as the sign-in method, and then click Next.
Select Native / SPA as the application type, and then click Next.
In Name, enter a name for the application, such as Public SDK Client.
In Owners, select a user that is responsible for maintaining the application, and then click Next.

When trying out the SDKs, you could select the demo user you created previously.
In Client ID, enter sdkPublicClient, and then click Create Application.

PingOne Advanced Identity Cloud creates the application and displays the details screen.
On the Sign On tab:
1. In Sign-In URLs, enter the following values:
  
  org.forgerock.demo://oauth2redirect
  
  Also add any other domains where you host SDK applications.
2. In Grant Types, enter the following values:
  
  Authorization Code
  
  Refresh Token
3. In Scopes, enter the following values:
  
  openid profile email address
Click Show advanced settings, and on the Authentication tab:
1. In Token Endpoint Authentication Method, select none.
2. In Client Type, select Public.
3. Enable the Implied Consent property.
Click Save.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the example applications and tutorials covered by this documentation.

Task 4. Configure the OAuth 2.0 provider

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingOne Advanced Identity Cloud OAuth 2.0 provider service is configured for use with the Ping SDKs, follow these steps:

In your PingOne Advanced Identity Cloud tenant, navigate to Native Consoles > Access Management.
In the left panel, click Services.
In the list of services, click OAuth2 Provider.
On the Core tab, ensure Issue Refresh Tokens is enabled.
On the Consent tab, ensure Allow Clients to Skip Consent is enabled.
Click Save Changes.

Step 1. Download the samples

To start this tutorial, you need to download the ForgeRock SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the kotlin-central-login-oidc sample to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud, using OIDC login.

In Android Studio, open the sdk-sample-apps/android/kotlin-central-login-oidc project you cloned in the previous step.
In the Project pane, switch to the Android view.
In the Android view, navigate to app > kotlin+java > com.example.app, and open Config.kt.
Edit the default values provided in the PingConfig class with the values from your PingOne Advanced Identity Cloud tenant:
```
data class PingConfig(
    var discoveryEndpoint: String = "https://openam-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration",
    var oauthClientId: String = "AndroidTest",
    var oauthRedirectUri: String = "org.forgerock.demo:/oauth2redirect",
    var oauthSignOutRedirectUri: String = "",
    var cookieName: String = "5421aeddf91aa20",
    var oauthScope: String = "openid profile email address"
)
```
discoveryEndpoint

The .well-known endpoint from your PingOne Advanced Identity Cloud tenant.

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:

Log in to your PingOne Advanced Identity Cloud administration console.

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

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

oauthClientId

The client ID from your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, sdkPublicClient

oauthRedirectUri

The redirect_uri as configured in the OAuth 2.0 client profile.

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

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

oauthSignOutRedirectUri

Leave this property empty.

It signals that the SDK does not need to open and return from a web page to perform log out.

cookieName

The name of the cookie your PingOne Advanced Identity Cloud tenant uses to store SSO tokens in client browsers.

How do I find my PingOne Advanced Identity Cloud cookie name?

To locate the cookie name in an PingOne Advanced Identity Cloud tenant:

Navigate to Tenant settings > Global Settings

Copy the value of the Cookie property.

For example, ch15fefc5407912

oauthScope

The scopes you added to your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, openid profile email address
The result resembles the following:
```
data class PingConfig(
    var discoveryEndpoint: String = "https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration",
    var oauthClientId: String = "sdkNativeClient",
    var oauthRedirectUri: String = "org.forgerock.demo://oauth2redirect",
    var oauthSignOutRedirectUri: String = "",
    var cookieName: String = "ch15fefc5407912",
    var oauthScope: String = "openid profile email address"
)
```
Save your changes.

Step 3. Test the app

In the following procedure, you run the sample app that you configured in the previous step. The app performs a centralized login on your PingOne Advanced Identity Cloud instance.

Log in as a demo user

In Android Studio, select Run > Run 'ping-oidc.app'.
On the Environment screen, ensure the PingOne Advanced Identity Cloud environment you added earlier is correct.

You can edit any of the values in the app if required.

Figure 10. Confirm the PingOne Advanced Identity Cloud connection properties
Tap Centralized Login.

The app launches a web browser and redirects to your PingOne Advanced Identity Cloud environment:

Figure 11. Browser launched and redirected to PingOne Advanced Identity Cloud
Sign on as a demo user:
- Name: demo
- Password: Ch4ng3it!
If authentication is successful, the application returns to the access token screen.
Tap the menu icon (), and then tap User Profile:

Figure 12. User info of the demo user
Tap the menu icon (), and then tap Logout.

The app logs the user out of PingOne Advanced Identity Cloud, revokes the tokens, and returns to the config page.

OIDC login to PingAM tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingAM UI for authentication.

The sample connects to the .well-known endpoint of your PingAM server to obtain the correct URIs to authenticate the user, and redirects to your PingAM server’s login UI.

After authentication, PingAM redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingAM server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingAM.

Start step 2

Step 3. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingAM server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingAM server.

After authentication, PingAM redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingAM server.

Compatibility

Android: This sample requires at least Android API 23 (Android 6.0)
Java: This sample requires at least Java 8 (v1.8).

Prerequisites

Android Studio: Download and install Android Studio, which is available for many popular operating systems.
An Android emulator or physical device: To try the quick start application as you develop it, you need an Android device. To add a virtual, emulated Android device to Android Studio, refer to Create and manage virtual devices, on the Android Developers website.

Server configuration

This tutorial requires you to configure your PingAM server as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingAM, follow these steps:

Log in to the PingAM admin UI as an administrator.
Navigate to Identities, and then click Add Identity.
Enter the following details:
- User ID = demo
- Password = Ch4ng3it!
- Email Address = demo.user@example.com
Click Create.

Task 2. Create an authentication tree

Authentication trees provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow. Authentication trees are made up of nodes that define actions taken during authentication.

To create a simple tree for use when testing the Ping SDKs, follow these steps:

Under Realm Overview, click Authentication Trees, then click Create Tree.
Enter a tree name, for example sdkUsernamePasswordJourney, and then click Create.

The authentication tree designer appears, showing the Start entry point connected to the Failure exit point.
Drag the following nodes from the Components panel on the left side into the designer area:
- Page Node
- Username Collector
- Password Collector
- Data Store Decision
Drag and drop the Username Collector and Password Collector nodes onto the Page Node, so that they both appear on the same page when logging in.
Connect the nodes as follows:

Figure 13. Example username and password authentication tree
Select the Page Node, and in the Properties pane, set the Stage property to UsernamePassword.

You can configure the node properties by selecting a node and altering properties in the right-hand panel.

One of the samples uses this specific value to determine the custom UI to display.
Click Save.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
In the left panel, click Applications.
Click Custom Application.
Select OIDC - OpenId Connect as the sign-in method, and then click Next.
Select Native / SPA as the application type, and then click Next.
In Name, enter a name for the application, such as Public SDK Client.
In Owners, select a user that is responsible for maintaining the application, and then click Next.

When trying out the SDKs, you could select the demo user you created previously.
In Client ID, enter sdkPublicClient, and then click Create Application.

PingOne Advanced Identity Cloud creates the application and displays the details screen.
On the Sign On tab:
1. In Sign-In URLs, enter the following values:
  
  org.forgerock.demo://oauth2redirect
  
  Also add any other domains where you host SDK applications.
2. In Grant Types, enter the following values:
  
  Authorization Code
  
  Refresh Token
3. In Scopes, enter the following values:
  
  openid profile email address
Click Show advanced settings, and on the Authentication tab:
1. In Token Endpoint Authentication Method, select none.
2. In Client Type, select Public.
3. Enable the Implied Consent property.
Click Save.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the example applications and tutorials covered by this documentation.

Task 4. Configure the OAuth 2.0 provider

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingOne Advanced Identity Cloud OAuth 2.0 provider service is configured for use with the Ping SDKs, follow these steps:

In your PingOne Advanced Identity Cloud tenant, navigate to Native Consoles > Access Management.
In the left panel, click Services.
In the list of services, click OAuth2 Provider.
On the Core tab, ensure Issue Refresh Tokens is enabled.
On the Consent tab, ensure Allow Clients to Skip Consent is enabled.
Click Save Changes.

Step 1. Download the samples

To start this tutorial, you need to download the ForgeRock SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the kotlin-central-login-oidc sample to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud, using OIDC login.

In Android Studio, open the sdk-sample-apps/android/kotlin-central-login-oidc project you cloned in the previous step.
In the Project pane, switch to the Android view.
In the Android view, navigate to app > kotlin+java > com.example.app, and open Config.kt.
Edit the default values provided in the PingConfig class with the values from your PingOne Advanced Identity Cloud tenant:
```
data class PingConfig(
    var discoveryEndpoint: String = "https://openam-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration",
    var oauthClientId: String = "AndroidTest",
    var oauthRedirectUri: String = "org.forgerock.demo:/oauth2redirect",
    var oauthSignOutRedirectUri: String = "",
    var cookieName: String = "5421aeddf91aa20",
    var oauthScope: String = "openid profile email address"
)
```
discoveryEndpoint

The .well-known endpoint from your PingOne Advanced Identity Cloud tenant.

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:

Log in to your PingOne Advanced Identity Cloud administration console.

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

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

oauthClientId

The client ID from your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, sdkPublicClient

oauthRedirectUri

The redirect_uri as configured in the OAuth 2.0 client profile.

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

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

oauthSignOutRedirectUri

Leave this property empty.

It signals that the SDK does not need to open and return from a web page to perform log out.

cookieName

The name of the cookie your PingOne Advanced Identity Cloud tenant uses to store SSO tokens in client browsers.

How do I find my PingOne Advanced Identity Cloud cookie name?

To locate the cookie name in an PingOne Advanced Identity Cloud tenant:

Navigate to Tenant settings > Global Settings

Copy the value of the Cookie property.

For example, ch15fefc5407912

oauthScope

The scopes you added to your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, openid profile email address
The result resembles the following:
```
data class PingConfig(
    var discoveryEndpoint: String = "https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration",
    var oauthClientId: String = "sdkNativeClient",
    var oauthRedirectUri: String = "org.forgerock.demo://oauth2redirect",
    var oauthSignOutRedirectUri: String = "",
    var cookieName: String = "ch15fefc5407912",
    var oauthScope: String = "openid profile email address"
)
```
Save your changes.

Step 3. Test the app

In the following procedure, you run the sample app that you configured in the previous step. The app performs a centralized login on your PingAM instance.

Log in as a demo user

In Android Studio, select Run > Run 'ping-oidc.app'.
On the Environment screen, ensure the PingAM environment you added earlier is correct.

You can edit any of the values in the app if required.

Figure 14. Confirm the PingAM connection properties
Tap Centralized Login.

The app launches a web browser and redirects to your PingAM environment:

Figure 15. Browser launched and redirected to PingAM
Sign on as a demo user:
- Name: demo
- Password: Ch4ng3it!
If authentication is successful, the application returns to the access token screen.
Tap the menu icon (), and then tap User Profile:

Figure 16. User info of the demo user
Tap the menu icon (), and then tap Logout.

The app logs the user out of PingAM, revokes the tokens, and returns to the config page.

OIDC login to PingFederate tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingFederate UI for authentication.

The sample connects to the .well-known endpoint of your PingFederate server to obtain the correct URIs to authenticate the user, and redirects to your PingFederate server’s login UI.

After authentication, PingFederate redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingFederate server with the required configuration.

For example, you will need to configure an OAuth 2.0 client application.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingFederate.

Start step 3

Step 3. Test the app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingFederate server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingFederate server.

After authentication, PingFederate redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites and compatibility requirements in this section.

The tutorial also requires a configured PingFederate server.

Compatibility

Android: This sample requires at least Android API 23 (Android 6.0)
Java: This sample requires at least Java 8 (v1.8).

Prerequisites

Android Studio: Download and install Android Studio, which is available for many popular operating systems.
An Android emulator or physical device: To try the quick start application as you develop it, you need an Android device. To add a virtual, emulated Android device to Android Studio, refer to Create and manage virtual devices, on the Android Developers website.

Server configuration

This tutorial requires you to configure your PingFederate server as follows:

Task 1. Register a public OAuth 2.0 client

OAuth 2.0 client application profiles define how applications connect to PingFederate and obtain OAuth 2.0 tokens.

To allow the Ping SDKs to connect to PingFederate and obtain OAuth 2.0 tokens, you must register an OAuth 2.0 client application:

Log in to the PingFederate administration console as an administrator.
Navigate to Applications OAuth Clients.
Click Add Client.

PingFederate displays the Clients | Client page.
In Client ID and Name, enter a name for the profile, for example sdkPublicClient

Make a note of the Client ID value, you will need it when you configure the sample code.
In Client Authentication, select None.

In Redirect URIs, add the following values:

org.forgerock.demo://oauth2redirect

Also add any other URLs where you host SDK applications.

Failure to add redirect URLs that exactly match your client app’s values can cause PingFederate to display an error message such as Redirect URI mismatch when attempting to end a session by redirecting from the SDK.

In Allowed Grant Types, select the following values:

Authorization Code

Refresh Token

In the OpenID Connect section:

In Logout Mode, select Ping Front-Channel

In Front-Channel Logout URIs, add the following values:

org.forgerock.demo://oauth2redirect

Also add any other URLs that redirect users to PingFederate to end their session.

Failure to add sign off URLs that exactly match your client app’s values can cause PingFederate to display an error message such as invalid post logout redirect URI when attempting to end a session by redirecting from the SDK.

In Post-Logout Redirect URIs, add the following values:

org.forgerock.demo://oauth2redirect

Click Save.

After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.

In the PingFederate administration console, navigate to System > Server > Cluster Management, and click Replicate.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Ping SDK PingFederate example applications and tutorials covered by this documentation.

Task 2. Configure CORS

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In PingFederate, you can configure CORS to allow browsers or apps from trusted domains to access protected resources.

To configure CORS in PingFederate follow these steps:

Log in to the PingFederate administration console as an administrator.
Navigate to System OAuth Settings Authorization Server Settings.
In the Cross-Origin Resource Sharing Settings section, in the Allowed Origin field, enter any DNS aliases you use for your SDK apps.

This documentation assumes the following configuration:

Property Values

Allowed Origin

org.forgerock.demo://oauth2redirect

Property	Values
`Allowed Origin`	`org.forgerock.demo://oauth2redirect`

Click Save.

After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.

In the PingFederate administration console, navigate to System > Server > Cluster Management, and click Replicate.

Your PingFederate server is now able to accept connections from origins hosting apps built with the Ping SDKs.

Step 1. Download the samples

To start this tutorial, you need to download the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the "kotlin-ui-prototype" sample to connect to the OAuth 2.0 application you created in PingFederate, using OIDC login.

In Android Studio, open the sdk-sample-apps/android/kotlin-ui-prototype folder you cloned in the previous step.
In the Project pane, switch to the Android view.
In the Android view, navigate to app > kotlin+java > com.example.app > env, and open EnvViewModel.kt.

This file has the server environments the sample app uses. Each specifies the properties using the FROptionsBuilder.build method.
Update the PingFederate example configuration with your environment’s details:
```
// Example values for a PingFederate instance
val PingFederate = FROptionsBuilder.build {
    server {
        url = "<PingFederate Base URL>"
    }
    oauth {
        oauthClientId = "<PingFederate Client ID>"
        oauthRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthSignOutRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthScope = "openid profile email address"
    }
}
```
Replace the following string with the value you obtained when you registered an OAuth 2.0 application in PingFederate.
<PingFederate Client ID>

The client ID from your OAuth 2.0 application in PingFederate.

For example, sdkPublicClient

<PingFederate Base URL>

The Base URL of your PingFederate server.

How do I find my PingFederate Base URL?

To verify the base URL of your PingFederate server:

Log in to your PingFederate administration console.

Navigate to System Server Protocol Settings.

Make a note of the Base URL value.

For example, https://pingfed.example.com

Do not use the admin console URL.

The sample code adds /.well-known/openid-configuration after the base URL value to form the .well-known endpoint of your server. The SDK reads the OAuth 2.0 paths it requires from this endpoint.
The result resembles the following:
```
val PingFederate = FROptionsBuilder.build {
    server {
        url = "https://pingfed.example.com"
    }
    oauth {
        oauthClientId = "sdkPublicClient"
        oauthRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthSignOutRedirectUri = "org.forgerock.demo://oauth2redirect"
        oauthScope = "openid profile email address"
    }
}
```

In the init object, check that PingFederate is in the list of server configurations available to the sample app:

For example:

init {
    servers.add(PingAM)
    servers.add(PingAdvancedIdentityCloud)
    servers.add(PingOne)
    servers.add(PingFederate)
}

With the sample configured, you can proceed to Step 3. Test the app.

Step 3. Test the app

In the following procedure, you run the sample app that you configured in an earlier step. The app performs a centralized login on your PingFederate instance.

Log in as a demo user

In Android Studio, select Run Run 'app'.
On the Environment screen, select the PingFederate .well-known endpoint you added in the earlier step.

Figure 17. Select the PingFederate environment
Tap the menu icon (), and then tap Centralize Login:

Figure 18. From the menu, select Centralize Login.

The app launches a web browser and redirects to your PingFederate environment:

Figure 19. Browser launched and redirected to PingFederate
Sign on using your PingFederate credentials

If authentication is successful, the application returns to the user info screen.
Tap Show Userinfo to display the details of the token issues to the demo user:

Figure 20. User info of the demo user
Tap the menu icon (), and then tap Logout.

The app opens a browser momentarily to log the user out of PingFederate, and revoke the tokens.

Apple iOS OIDC login tutorials

Follow these iOS tutorials to integrate your apps using OpenID Connect login to the following servers:

PingOne

PingOne Advanced Identity Cloud

PingAM

PingFederate

Authentication journey tutorial for iOS

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingOne UI for authentication.

The sample connects to the .well-known endpoint of your PingOne server to obtain the correct URIs to authenticate the user, and redirects to your PingOne server’s login UI.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingOne server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne.

Start step 2

Step 3. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingOne server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne server.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites and compatibility requirements in this section.

The tutorial also requires a configured PingOne instance.

Compatibility

iOS: This sample app is compatible with iOS 12 and later.

Prerequisites

Xcode: You can download the latest version for free from https://developer.apple.com/xcode/.

Server configuration

This tutorial requires you to configure your PingOne server as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingOne, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Directory > Users.
Next to the Users label, click the plus icon ().

PingOne displays the Add User panel.
Enter the following details:
- Given Name = Demo
- Family Name = User
- Username = demo
- Email = demo.user@example.com
- Population = Default
- Password = Ch4ng3it!
Click Save.

Task 2. Create a revoke resource

To allow the Ping SDKs to revoke access tokens issued by PingOne, you must create a custom resource that is assigned the revoke scope in your PingOne tenant.

To create a custom resource and assign the revoke scope, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Applications > Resources.
Next to the Resources label, click the plus icon ().

PingOne displays the Add Custom Resource panel.
In Resource Name, enter a name for the custom resource, for example SDK Revoke Resource, and then click Next.
On the Attributes page, click Next.
On the Scopes page, click Add Scope.
In Scope Name, enter revoke, and then click Save.

When you have created the custom resource in your PingOne instance, continue with the next step.

For more information on resources in PingOne, refer to Adding a custom resource.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application in PingOne for use with the Ping SDKs for Android and iOS, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Applications > Applications.
Next to the Applications label, click the plus icon ().

PingOne displays the Add Application panel.
In Application Name, enter a name for the profile, for example sdkNativeClient
Select Native as the Application Type, and then click Save.
On the Configuration tab, click the pencil icon ().
1. In Grant Type, select the following values:
  
  Authorization Code
  
  Refresh Token
2. In Redirect URIs, enter the following value:
  
  org.forgerock.demo://oauth2redirect
3. In Token Endpoint Authentication Method, select None.
4. In Signoff URLs, enter the following value:
  
  org.forgerock.demo://oauth2redirect
5. Click Save.
On the Resources tab, next to Allowed Scopes, click the pencil icon ().
1. In Scopes, select the following values:
  
  email
  
  phone
  
  profile
  
  SDK Revoke Resource
  
  The openid scope is selected by default.
  
  The result resembles the following:
  
  Figure 21. Adding scopes, including the custom "revoke" scope to an application.
Optionally, on the Policies tab, click the pencil icon () to select the authentication policies for the application.

Applications that have no authentication policy assignments use the environment’s default authentication policy to authenticate users.

If you have a DaVinci license, you can select PingOne policies or DaVinci Flow policies, but not both. If you do not have a DaVinci license, the page only displays PingOne policies.

To use a PingOne policy:
1. Click Add policies and then select the policies that you want to apply to the application.
2. Click Save.
  
  PingOne applies the policies in the order in which they appear in the list. PingOne evaluates the first policy in the list first. If the requirements are not met, PingOne moves to the next one.
  
  For more information, see Authentication policies for applications.
To use a DaVinci Flow policy:
1. You must clear all PingOne policies. Click Deselect all PingOne Policies.
2. In the confirmation message, click Continue.
3. On the DaVinci Policies tab, select the policies that you want to apply to the application.
4. Click Save.
  
  PingOne applies the first policy in the list.
Click Save.
Enable the OAuth 2.0 client application by using the toggle next to its name:

Figure 22. Enable the application using the toggle.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Android and iOS PingOne example applications and tutorials covered by this documentation.

Step 1. Download the samples

To start this tutorial, you need to download the ForgeRock SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the "FRExample" app to connect to the OAuth 2.0 application you created in PingOne, using OIDC login.

In Xcode, on the File menu, click Open.
Navigate to the sdk-sample-apps folder you cloned in the previous step, navigate to iOS > uikit-frexamples > FrExample > FrExample > FRExample.xcodeproj, and then click Open.
In the Project Navigator pane, navigate to FRExample > FRExample, and open the ViewController file.
In the ViewController file:
1. Change the useDiscoveryURL variable to true:
  let useDiscoveryURL = true
  Changing the variable causes the sample to use the discover method to get many of the required configuration values from your PingOne OIDC .well-known endpoint.
2. Replace CLIENT_ID_PLACEHOLDER with the ID of the OAuth 2.0 client application you created previously in PingOne:
  let config = ["forgerock_oauth_client_id": "6c7eb89a-66e9-ab12-cd34-eeaf795650b2", "forgerock_oauth_redirect_uri": "org.forgerock.demo://oauth2redirect", "forgerock_oauth_scope" : "openid profile email address revoke", "forgerock_ssl_pinning_public_key_hashes": ["SSL_PINNING_HASH_PLACEHOLDER"]]
3. Remove or comment out the forgerock_ssl_pinning_public_key_hashes line.
  
  For information on SSL pinning, refer to Enable SSL pinning.
4. Replace DISCOVERY_URL_PLACEHOLDER with the .well-known endpoint from your OAuth 2.0 native mobile application in PingOne.
  How do I find my PingOne .well-known URL?
  To find the .well-known endpoint for an OAuth 2.0 client in PingOne:
  
  Log in to your PingOne administration console.
  
  Go to Applications > Applications, and then select the OAuth 2.0 client you created earlier.
  
  For example, sdkPublicClient.
  
  On the Configuration tab, expand the URLs section, and then copy the OIDC Discovery Endpoint value.
  For example:
  let discoveryURL = "https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration"
5. Optionally, specify which of the configured policies PingOne uses to authenticate users.
  
  In the performCentralizedLogin function, add an acr_values parameter to the authorization request by using the setCustomParam() method:
  func performCentralizedLogin() { FRUser.browser()? .set(presentingViewController: self) .set(browserType: .authSession) // Add acr values to the authorization request .setCustomParam(key: "acr_values", value: "<Policy IDs>") .build().login { (user, error) in self.displayLog("User: \(String(describing: user)) || Error: \(String(describing: error))") } return }
  Replace <Policy IDs> with either a single DaVinci policy, by using its flow policy ID, or one or more PingOne policies by specifying the policy names, separated by spaces or the encoded space character %20.
  
  Examples:
  
  DaVinci flow policy ID
  
  .setCustomParam(key: "acr_values", value: "d1210a6b0b2665dbaa5b652221badba2")
  
  PingOne policy names
  
  .setCustomParam(key: "acr_values", value: "Single_Factor%20Multi_Factor")
For more information, refer to Editing an application - OIDC.

With the sample configured, you can proceed to Step 3. Test the app.

Step 3. Test the app

In the following procedure, you run the sample app that you configured in the previous step. The app performs a centralized login on your PingOne instance.

Log in as a demo user

In Xcode, select Product Run.

Xcode launches the sample app in the iPhone simulator.
In the sample app on the iPhone simulator, in the Select an action menu, select Login with Browser, and then click Perform Action.

Figure 23. Select the PingOne environment

You might see a dialog asking if you want to open a browser. If you do, tap Continue.

The app launches a web browser and redirects to your PingOne environment:

Figure 24. Browser launched and redirected to PingOne
Sign on as a demo user:
- Name: demo
- Password: Ch4ng3it!
If authentication is successful, the application displays the tokens issued by PingOne.

Tap Login with Browser to open the drop-down menu, select User Logout, and then tap Perform Action.

The app briefly opens a browser to sign the user out of PingOne, and revoke the tokens.

To verify the user is signed out:

In the PingOne administration console, navigate to Directory > Users.
Select the user you signed in as.
From the Sevices dropdown, select Authentication:

Figure 25. Checking a user’s sessions in PingOne.

The Sessions section displays any existing sessions the user has, and whether they originate from a mobile device.

OIDC login to PingOne Advanced Identity Cloud tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingOne Advanced Identity Cloud UI for authentication.

After authentication, PingOne Advanced Identity Cloud redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingOne Advanced Identity Cloud server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud.

Start step 2

Step 3. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingOne Advanced Identity Cloud server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne Advanced Identity Cloud server.

After authentication, PingOne Advanced Identity Cloud redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingOne Advanced Identity Cloud tenant.

Compatibility

iOS: This sample app is compatible with iOS 12 and later.

Prerequisites

Xcode: You can download the latest version for free from https://developer.apple.com/xcode/.

Server configuration

This tutorial requires you to configure your PingOne Advanced Identity Cloud tenant as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
In the left panel, click Identities > Manage.
Click New Alpha realm - User.
Enter the following details:
- Username = demo
- First Name = Demo
- Last Name = User
- Email Address = demo.user@example.com
- Password = Ch4ng3it!
Click Save.

Task 2. Create an authentication journey

To create a simple journey for use when testing the Ping SDKs, follow these steps:

In your PingOne Advanced Identity Cloud tenant, navigate to Journeys, and click New Journey.
Enter a name, such as sdkUsernamePasswordJourney and click Save.

The authentication journey designer appears.
Drag the following nodes into the designer area:
- Page Node
- Platform Username
- Platform Password
- Data Store Decision
Drag and drop the Platform Username and Platform Password nodes onto the Page Node, so that they both appear on the same page when logging in.
Connect the nodes as follows:

Figure 26. Example username and password authentication journey
Click Save.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
In the left panel, click Applications.
Click Custom Application.
Select OIDC - OpenId Connect as the sign-in method, and then click Next.
Select Native / SPA as the application type, and then click Next.
In Name, enter a name for the application, such as Public SDK Client.
In Owners, select a user that is responsible for maintaining the application, and then click Next.

When trying out the SDKs, you could select the demo user you created previously.
In Client ID, enter sdkPublicClient, and then click Create Application.

PingOne Advanced Identity Cloud creates the application and displays the details screen.
On the Sign On tab:
1. In Sign-In URLs, enter the following values:
  
  org.forgerock.demo://oauth2redirect
  
  Also add any other domains where you host SDK applications.
2. In Grant Types, enter the following values:
  
  Authorization Code
  
  Refresh Token
3. In Scopes, enter the following values:
  
  openid profile email address
Click Show advanced settings, and on the Authentication tab:
1. In Token Endpoint Authentication Method, select none.
2. In Client Type, select Public.
3. Enable the Implied Consent property.
Click Save.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the example applications and tutorials covered by this documentation.

Task 4. Configure the OAuth 2.0 provider

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingOne Advanced Identity Cloud OAuth 2.0 provider service is configured for use with the Ping SDKs, follow these steps:

In your PingOne Advanced Identity Cloud tenant, navigate to Native Consoles > Access Management.
In the left panel, click Services.
In the list of services, click OAuth2 Provider.
On the Core tab, ensure Issue Refresh Tokens is enabled.
On the Consent tab, ensure Allow Clients to Skip Consent is enabled.
Click Save Changes.

Step 1. Download the samples

To start this tutorial, you need to download the ForgeRock SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the "swiftui-oidc" app to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud, and display the login UI of the server.

In Xcode, on the File menu, click Open.
Navigate to the sdk-sample-apps folder you cloned in the previous step, navigate to iOS > swiftui-oidc > PingExample > PingExample.xcodeproj, and then click Open.
In the Project Navigator pane, navigate to PingExample > PingExample > Utilities, and open the ConfigurationManager file.

Locate the ConfigurationViewModel function which contains placeholder configuration properties.

The function is commented with //TODO: in the source to make it easier to locate.

return ConfigurationViewModel(
    clientId: "[CLIENT ID]",
    scopes: ["openid", "email", "address", "phone", "profile"],
    redirectUri: "[REDIRECT URI]",
    signOutUri: "[SIGN OUT URI]",
    discoveryEndpoint: "[DISCOVERY ENDPOINT URL]",
    environment: "[ENVIRONMENT - EITHER AIC OR PingOne]",
    cookieName: "[COOKIE NAME - OPTIONAL (Applicable for AIC only)]",
    browserSeletorType: .authSession
)

In the ConfigurationViewModel function, update the following properties with the values you obtained when preparing your environment.

clientId

The client ID from your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, sdkPublicClient

scopes

The scopes you added to your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, address email openid phone profile

redirectUri

The redirect_uri to return to after logging in with the server UI, for example the URI to your client app.

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

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

signOutUri

The URI to redirect to after logging out of the authorization server, for example the URI to your client app.

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

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

discoveryEndpoint

The .well-known endpoint from your PingOne Advanced Identity Cloud tenant.

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:

Log in to your PingOne Advanced Identity Cloud administration console.
Click Applications, and then select the OAuth 2.0 client you created earlier. For example, sdkPublicClient.
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

environment

Ensures the sample app uses the correct behavior for the different servers it supports, for example what logout parameters to use.

For PingOne Advanced Identity Cloud and PingAM servers, specify AIC.

cookieName

The name of the cookie your PingOne Advanced Identity Cloud tenant uses to store SSO tokens in client browsers.

How do I find my PingOne Advanced Identity Cloud cookie name?

To locate the cookie name in an PingOne Advanced Identity Cloud tenant:

Navigate to Tenant settings > Global Settings
Copy the value of the Cookie property.

For example, ch15fefc5407912

browserSeletorType

You can specify what type of browser the client iOS device opens to handle centralized login.

Each browser has slightly different characteristics, which make them suitable to different scenarios, as outlined in this table:

Browser type Characteristics

Browser type	Characteristics
`.authSession`	Opens a web authentication session browser. Designed specifically for authentication sessions, however it prompts the user before opening the browser with a modal that asks them to confirm the domain is allowed to authenticate them. This is the default option in the Ping SDK for iOS.
`.ephemeralAuthSession`	Opens a web authentication session browser, but enables the `prefersEphemeralWebBrowserSession` parameter. This browser type does not prompt the user before opening the browser with a modal. The difference between this and `.authSession` is that the browser does not include any existing data such as cookies in the request, and also discards any data obtained during the browser session. This means that an `ephemeralAuthSession` is not suitable when you require single sign-on (SSO) between your iOS apps. Use this browser type when you do not want the user’s existing sessions to affect the authentication.
`.nativeBrowserApp`	Opens the installed browser that is marked as the default by the user. Often Safari. The browser opens without any interaction from the user. However, the browser does display a modal when returning to your application.
`.sfViewController`	Opens a Safari view controller browser. Your client app is *not* able to interact with the pages in the `sfViewController` or access the data or browsing history. The view controller opens within your app without any interaction from the user. As the user does not leave your app, the view controller does not need to display a warning modal when authentication is complete and control returns to your application.

.authSession

Opens a web authentication session browser.

Designed specifically for authentication sessions, however it prompts the user before opening the browser with a modal that asks them to confirm the domain is allowed to authenticate them.

This is the default option in the Ping SDK for iOS.

.ephemeralAuthSession

Opens a web authentication session browser, but enables the prefersEphemeralWebBrowserSession parameter.

This browser type does not prompt the user before opening the browser with a modal.

Use this browser type when you do not want the user’s existing sessions to affect the authentication.

.nativeBrowserApp

Opens the installed browser that is marked as the default by the user. Often Safari.

The browser opens without any interaction from the user. However, the browser does display a modal when returning to your application.

.sfViewController

Opens a Safari view controller browser.

Your client app is not able to interact with the pages in the sfViewController or access the data or browsing history.

The result resembles the following:

return ConfigurationViewModel(
    clientId: "sdkPublicClient",
    scopes: ["openid", "email", "address", "phone", "profile"],
    redirectUri: "org.forgerock.demo://oauth2redirect",
    signOutUri: "org.forgerock.demo://oauth2redirect",
    discoveryEndpoint: "https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration",
    environment: "AIC",
    cookieName: "ch15fefc5407912",
    browserSeletorType: .authSession
)

Optionally, specify ACR values to choose which authentication journey the server uses.

Navigate to PingExample > PingExample > ViewModels, and open the OIDCViewModel file.

In the startOIDC() function, add an acr_values parameter to the authorization request by using the setCustomParam() method:

public func startOIDC() async throws → FRUser {
    return try await withCheckedThrowingContinuation({
        (continuation: CheckedContinuation<FRUser, Error>) in
        Task { @MainActor in
            FRUser.browser()?
                .set(presentingViewController: self.topViewController!)
                .set(browserType: ConfigurationManager.shared.currentConfigurationViewModel?.getBrowserType() ?? .authSession)
                .setCustomParam(key: "acr_values", value: "sdkUsernamePasswordJourney")
                .build().login { (user, error) in
                    if let frUser = user {
                        Task { @MainActor in
                            self.status = "User is authenticated"
                        }
                        continuation.resume(returning: frUser)
                    } else {
                        Task { @MainActor in
                            self.status = error?.localizedDescription ?? "Error was nil"
                        }
                        continuation.resume(throwing: error!)
                    }
                }
        }
    })
}

Enter one or more of the ACR mapping keys as configured in the OAuth 2.0 provider service.

To learn more, refer to Choose journeys with ACR values.

You can list the available keys by inspecting the acr_values_supported property in the output of your /oauth2/.well-known/openid-configuration endpoint.

Step 3. Test the app

In this step, run the sample app that you configured in the previous step. The app performs OIDC login to your PingOne Advanced Identity Cloud instance.

In Xcode, select Product Run.

Xcode launches the sample app in the iPhone simulator.

Figure 27. iOS OIDC login sample home screen
In the sample app on the iPhone simulator, tap Edit configuration, and verify or edit the configuration you entered in the previous step.

Figure 28. Verify the configuration settings
Tap Ping OIDC to go back to the main menu, and then tap Launch OIDC.

You might see a dialog asking if you want to open a browser. If you do, tap Continue.

The app launches a web browser and redirects to your PingOne Advanced Identity Cloud login UI:

Figure 29. Browser launched and redirected to PingOne Advanced Identity Cloud
Sign on as a demo user:
- Name: demo
- Password: Ch4ng3it!
If authentication is successful, the application displays the access token issued by PingOne Advanced Identity Cloud.

Figure 30. Access token after successful authentication
Tap Ping OIDC to go back to the main menu, and then tap User Info.

The app displays the information relating to the access token:

Figure 31. User info relating to the access token

Tap Ping OIDC to go back to the main menu, and then tap Logout.

The app logs the user out of the authorization server and prints a message to the Xcode console:

[FRCore][4.6.0] [🌐 - Network] Response | [✅ 204] :
  https://openam-forgerock-sdks.forgeblocks.com:443/am/oauth2/alpha/connect/endSession?id_token_hint=eyJ0...sbrA&client_id=sdkPublicClient in 34 ms
[FRAuth][4.6.0] [FRUser.swift:211 : logout()] [Verbose]
  Invalidating OIDC Session successful

OIDC login to PingAM tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingAM UI for authentication.

The sample connects to the .well-known endpoint of your PingAM server to obtain the correct URIs to authenticate the user, and redirects to your PingAM server’s login UI.

After authentication, PingAM redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingAM server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingAM.

Start step 2

Step 3. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingAM server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingAM server.

After authentication, PingAM redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingAM server.

Compatibility

iOS: This sample app is compatible with iOS 12 and later.

Prerequisites

Xcode: You can download the latest version for free from https://developer.apple.com/xcode/.

Server configuration

This tutorial requires you to configure your PingAM server as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingAM, follow these steps:

Log in to the PingAM admin UI as an administrator.
Navigate to Identities, and then click Add Identity.
Enter the following details:
- User ID = demo
- Password = Ch4ng3it!
- Email Address = demo.user@example.com
Click Create.

Task 2. Create an authentication journey

To create a simple tree for use when testing the Ping SDKs, follow these steps:

Under Realm Overview, click Authentication Trees, then click Create Tree.
Enter a tree name, for example sdkUsernamePasswordJourney, and then click Create.

The authentication tree designer appears, showing the Start entry point connected to the Failure exit point.
Drag the following nodes from the Components panel on the left side into the designer area:
- Page Node
- Username Collector
- Password Collector
- Data Store Decision
Drag and drop the Username Collector and Password Collector nodes onto the Page Node, so that they both appear on the same page when logging in.
Connect the nodes as follows:

Figure 32. Example username and password authentication tree
Select the Page Node, and in the Properties pane, set the Stage property to UsernamePassword.

You can configure the node properties by selecting a node and altering properties in the right-hand panel.

One of the samples uses this specific value to determine the custom UI to display.
Click Save.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application for use with the SDKs in AM, follow these steps:

Log in to the PingAM admin UI as an administrator.
Navigate to Applications > OAuth 2.0 > Clients, and then click Add Client.
In Client ID, enter sdkPublicClient.
Leave Client secret empty.
In Redirection URIs, enter the following values:

org.forgerock.demo://oauth2redirect

Also add any other domains where you will be hosting SDK applications.
In Scopes, enter the following values:

openid profile email address
Click Create.

PingAM creates the new OAuth 2.0 client, and displays the properties for further configuration.
On the Core tab:
1. In Client type, select Public.
2. Disable Allow wildcard ports in redirect URIs.
3. Click Save Changes.
On the Advanced tab:
1. In Grant Types, enter the following values:
  Authorization Code Refresh Token
2. In Token Endpoint Authentication Method, select None.
3. Enable the Implied consent property.
Click Save Changes.

Task 4. Configure the OAuth 2.0 provider

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingAM OAuth 2.0 provider service is configured for use with the Ping SDKs, follow these steps:

Log in to the PingAM admin UI as an administrator.
In the left panel, click Services.
In the list of services, click OAuth2 Provider.
On the Core tab, ensure Issue Refresh Tokens is enabled.
On the Consent tab, ensure Allow Clients to Skip Consent is enabled.
Click Save Changes.

Step 1. Download the samples

To start this tutorial, you need to download the ForgeRock SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the "swiftui-oidc" app to connect to the OAuth 2.0 application you created in PingAM, and display the login UI of the server.

In Xcode, on the File menu, click Open.
Navigate to the sdk-sample-apps folder you cloned in the previous step, navigate to iOS > swiftui-oidc > PingExample > PingExample.xcodeproj, and then click Open.
In the Project Navigator pane, navigate to PingExample > PingExample > Utilities, and open the ConfigurationManager file.

Locate the ConfigurationViewModel function which contains placeholder configuration properties.

The function is commented with //TODO: in the source to make it easier to locate.

return ConfigurationViewModel(
    clientId: "[CLIENT ID]",
    scopes: ["openid", "email", "address", "phone", "profile"],
    redirectUri: "[REDIRECT URI]",
    signOutUri: "[SIGN OUT URI]",
    discoveryEndpoint: "[DISCOVERY ENDPOINT URL]",
    environment: "[ENVIRONMENT - EITHER AIC OR PingOne]",
    cookieName: "[COOKIE NAME - OPTIONAL (Applicable for AIC only)]",
    browserSeletorType: .authSession
)

In the ConfigurationViewModel function, update the following properties with the values you obtained when preparing your environment.

clientId

The client ID from your OAuth 2.0 application in PingAM.

For example, sdkPublicClient

scopes

The scopes you added to your OAuth 2.0 application in PingAM.

For example, address email openid phone profile

redirectUri

The redirect_uri to return to after logging in with the server UI, for example the URI to your client app.

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

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

signOutUri

The URI to redirect to after logging out of the authorization server, for example the URI to your client app.

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

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

discoveryEndpoint

The .well-known endpoint from your PingAM server.

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

environment

Ensures the sample app uses the correct behavior for the different servers it supports, for example what logout parameters to use.

For PingAM servers, specify AIC.

cookieName

The name of the cookie your PingAM server uses to store SSO tokens in client browsers.

For example, iPlanetDirectoryPro

browserSeletorType

You can specify what type of browser the client iOS device opens to handle centralized login.

Each browser has slightly different characteristics, which make them suitable to different scenarios, as outlined in this table:

Browser type Characteristics

Browser type	Characteristics
`.authSession`	Opens a web authentication session browser. Designed specifically for authentication sessions, however it prompts the user before opening the browser with a modal that asks them to confirm the domain is allowed to authenticate them. This is the default option in the Ping SDK for iOS.
`.ephemeralAuthSession`	Opens a web authentication session browser, but enables the `prefersEphemeralWebBrowserSession` parameter. This browser type does not prompt the user before opening the browser with a modal. The difference between this and `.authSession` is that the browser does not include any existing data such as cookies in the request, and also discards any data obtained during the browser session. This means that an `ephemeralAuthSession` is not suitable when you require single sign-on (SSO) between your iOS apps. Use this browser type when you do not want the user’s existing sessions to affect the authentication.
`.nativeBrowserApp`	Opens the installed browser that is marked as the default by the user. Often Safari. The browser opens without any interaction from the user. However, the browser does display a modal when returning to your application.
`.sfViewController`	Opens a Safari view controller browser. Your client app is *not* able to interact with the pages in the `sfViewController` or access the data or browsing history. The view controller opens within your app without any interaction from the user. As the user does not leave your app, the view controller does not need to display a warning modal when authentication is complete and control returns to your application.

.authSession

Opens a web authentication session browser.

Designed specifically for authentication sessions, however it prompts the user before opening the browser with a modal that asks them to confirm the domain is allowed to authenticate them.

This is the default option in the Ping SDK for iOS.

.ephemeralAuthSession

Opens a web authentication session browser, but enables the prefersEphemeralWebBrowserSession parameter.

This browser type does not prompt the user before opening the browser with a modal.

Use this browser type when you do not want the user’s existing sessions to affect the authentication.

.nativeBrowserApp

Opens the installed browser that is marked as the default by the user. Often Safari.

The browser opens without any interaction from the user. However, the browser does display a modal when returning to your application.

.sfViewController

Opens a Safari view controller browser.

Your client app is not able to interact with the pages in the sfViewController or access the data or browsing history.

The result resembles the following:

return ConfigurationViewModel(
    clientId: "sdkPublicClient",
    scopes: ["openid", "email", "address", "phone", "profile"],
    redirectUri: "org.forgerock.demo://oauth2redirect",
    signOutUri: "org.forgerock.demo://oauth2redirect",
    discoveryEndpoint: "https://openam.example.com:8443/openam/oauth2/.well-known/openid-configuration",
    environment: "AIC",
    cookieName: "iPlanetDirectoryPro",
    browserSeletorType: .authSession
)

Optionally, specify ACR values to choose which authentication journey the server uses.

Navigate to PingExample > PingExample > ViewModels, and open the OIDCViewModel file.

In the startOIDC() function, add an acr_values parameter to the authorization request by using the setCustomParam() method:

public func startOIDC() async throws → FRUser {
    return try await withCheckedThrowingContinuation({
        (continuation: CheckedContinuation<FRUser, Error>) in
        Task { @MainActor in
            FRUser.browser()?
                .set(presentingViewController: self.topViewController!)
                .set(browserType: ConfigurationManager.shared.currentConfigurationViewModel?.getBrowserType() ?? .authSession)
                .setCustomParam(key: "acr_values", value: "sdkUsernamePasswordJourney")
                .build().login { (user, error) in
                    if let frUser = user {
                        Task { @MainActor in
                            self.status = "User is authenticated"
                        }
                        continuation.resume(returning: frUser)
                    } else {
                        Task { @MainActor in
                            self.status = error?.localizedDescription ?? "Error was nil"
                        }
                        continuation.resume(throwing: error!)
                    }
                }
        }
    })
}

Enter one or more of the ACR mapping keys as configured in the OAuth 2.0 provider service.

To learn more, refer to Choose journeys with ACR values.

You can list the available keys by inspecting the acr_values_supported property in the output of your /oauth2/.well-known/openid-configuration endpoint.

Step 3. Test the app

In this step, run the sample app that you configured in the previous step. The app performs OIDC login to your PingAM server.

In Xcode, select Product Run.

Xcode launches the sample app in the iPhone simulator.

Figure 33. iOS OIDC login sample home screen
In the sample app on the iPhone simulator, tap Edit configuration, and verify or edit the configuration you entered in the previous step.

Figure 34. Verify the configuration settings
Tap Ping OIDC to go back to the main menu, and then tap Launch OIDC.

You might see a dialog asking if you want to open a browser. If you do, tap Continue.

The app launches a web browser and redirects to your PingAM login UI:

Figure 35. Browser launched and redirected to PingAM
Sign on as a demo user:
- Name: demo
- Password: Ch4ng3it!
If authentication is successful, the application displays the access token issued by PingAM.

Figure 36. Access token after successful authentication
Tap Ping OIDC to go back to the main menu, and then tap User Info.

The app displays the information relating to the access token:

Figure 37. User info relating to the access token

Tap Ping OIDC to go back to the main menu, and then tap Logout.

The app logs the user out of the authorization server and prints a message to the Xcode console:

[FRCore][4.6.0] [🌐 - Network] Response | [✅ 204] :
  https://openam.example.com:443/am/oauth2/connect/endSession?id_token_hint=eyJ0...sbrA&client_id=sdkPublicClient in 34 ms
[FRAuth][4.6.0] [FRUser.swift:211 : logout()] [Verbose]
  Invalidating OIDC Session successful

Authentication journey tutorial for iOS

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingFederate UI for authentication.

The sample connects to the .well-known endpoint of your PingFederate server to obtain the correct URIs to authenticate the user, and redirects to your PingFederate server’s login UI.

After authentication, PingFederate redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingFederate server with the required configuration.

For example, you will need to configure an OAuth 2.0 client application.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingFederate.

Start step 2

Step 3. Test the app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingFederate server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingFederate server.

After authentication, PingFederate redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites and compatibility requirements in this section.

The tutorial also requires a configured PingFederate server.

Compatibility

iOS: This sample app is compatible with iOS 12 and later.

Prerequisites

Xcode: You can download the latest version for free from https://developer.apple.com/xcode/.

Server configuration

This tutorial requires you to configure your PingFederate server as follows:

Task 1. Register a public OAuth 2.0 client

OAuth 2.0 client application profiles define how applications connect to PingFederate and obtain OAuth 2.0 tokens.

To allow the Ping SDKs to connect to PingFederate and obtain OAuth 2.0 tokens, you must register an OAuth 2.0 client application:

Log in to the PingFederate administration console as an administrator.
Navigate to Applications OAuth Clients.
Click Add Client.

PingFederate displays the Clients | Client page.
In Client ID and Name, enter a name for the profile, for example sdkPublicClient

Make a note of the Client ID value, you will need it when you configure the sample code.
In Client Authentication, select None.

In Redirect URIs, add the following values:

org.forgerock.demo://oauth2redirect

Also add any other URLs where you host SDK applications.

In Allowed Grant Types, select the following values:

Authorization Code

Refresh Token

In the OpenID Connect section:

In Logout Mode, select Ping Front-Channel

In Front-Channel Logout URIs, add the following values:

org.forgerock.demo://oauth2redirect

Also add any other URLs that redirect users to PingFederate to end their session.

In Post-Logout Redirect URIs, add the following values:

org.forgerock.demo://oauth2redirect

Click Save.

After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.

In the PingFederate administration console, navigate to System > Server > Cluster Management, and click Replicate.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Ping SDK PingFederate example applications and tutorials covered by this documentation.

Task 2. Configure CORS

To configure CORS in PingFederate follow these steps:

Log in to the PingFederate administration console as an administrator.
Navigate to System OAuth Settings Authorization Server Settings.
In the Cross-Origin Resource Sharing Settings section, in the Allowed Origin field, enter any DNS aliases you use for your SDK apps.

This documentation assumes the following configuration:

Property Values

Allowed Origin

org.forgerock.demo://oauth2redirect

Property	Values
`Allowed Origin`	`org.forgerock.demo://oauth2redirect`

Click Save.

After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.

In the PingFederate administration console, navigate to System > Server > Cluster Management, and click Replicate.

Your PingFederate server is now able to accept connections from origins hosting apps built with the Ping SDKs.

Step 1. Download the samples

To start this tutorial, you need to download the ForgeRock SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the SDK Sample Apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Configure connection properties

In this step, you configure the "FRExample" app to connect to the OAuth 2.0 application you created in PingFederate, using OIC login method.

In Xcode, on the File menu, click Open.
Navigate to the sdk-sample-apps folder you cloned in the previous step, navigate to iOS > uikit-frexamples > FrExample > FrExample > FRExample.xcodeproj, and then click Open.
In the Project Navigator pane, navigate to FRExample > FRExample, and open the ViewController file.
In the ViewController file:
1. Change the useDiscoveryURL variable to true:
  let useDiscoveryURL = true
  Changing the variable causes the sample to use the discover method to get many of the required configuration values from your PingFederate OIDC .well-known endpoint.
2. Replace CLIENT_ID_PLACEHOLDER with the ID of the OAuth 2.0 client application you created previously in PingFederate:
  let config = ["forgerock_oauth_client_id": "sdkPublicClient", "forgerock_oauth_redirect_uri": "org.forgerock.demo://oauth2redirect", "forgerock_oauth_scope" : "openid profile email address", "forgerock_ssl_pinning_public_key_hashes": ["SSL_PINNING_HASH_PLACEHOLDER"]]
3. Remove or comment out the forgerock_ssl_pinning_public_key_hashes line.
  
  For information on SSL pinning, refer to Enable SSL pinning.
4. Replace DISCOVERY_URL_PLACEHOLDER with the .well-known endpoint from your PingFederate server.
  
  The .well-known endpoint is the base URL of your PingFederate server, with /.well-known/openid-configuration appended.
  How do I find my PingFederate Base URL?
  To verify the base URL of your PingFederate server:
  
  Log in to your PingFederate administration console.
  
  Navigate to System Server Protocol Settings.
  
  Make a note of the Base URL value.
  
  For example, https://pingfed.example.com
  
  Do not use the admin console URL.
  For example:
  let discoveryURL = "https://pingfed.example.com/as/.well-known/openid-configuration"

For more information, refer to Editing an application - OIDC.

With the sample configured, you can proceed to Step 3. Test the app.

Step 3. Test the app

In the following procedure, you run the sample app that you configured in the previous step. The app performs a centralized login on your PingFederate server.

Log in as a demo user

In Xcode, select Product Run.

Xcode launches the sample app in the iPhone simulator.
In the sample app on the iPhone simulator, in the Select an action menu, select Login with Browser, and then click Perform Action.

Figure 38. Select the PingFederate environment

You might see a dialog asking if you want to open a browser. If you do, tap Continue.

The app launches a web browser and redirects to your PingFederate environment:

Figure 39. Browser launched and redirected to PingFederate
Sign on using your PingFederate credentials

If authentication is successful, the application displays the token issued by PingFederate:

Figure 40. Sample app showing the token returned from PingFederate
Tap Login with Browser to open the drop-down menu, select User Logout, and then tap Perform Action.

The app briefly opens a browser to sign the user out of PingFederate, and revoke the tokens.

JavaScript OIDC login tutorials

Follow these JavaScript tutorials to integrate your apps using OpenID Connect login to the following servers:

PingOne

PingOne Advanced Identity Cloud

PingAM

PingFederate

OIDC login to PingOne tutorial for JavaScript

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingOne UI for authentication.

The sample connects to the .well-known endpoint of your PingOne server to obtain the correct URIs to authenticate the user, and redirects to your PingOne server’s login UI.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingOne server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Install the Ping SDK

The sample projects need a number of dependencies that you can install by using the npm command.

For example, the Ping SDK for JavaScript itself is one of the dependencies.

Start step 2

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne.

Start step 3

Step 4. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingOne server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne server.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingOne instance.

Prerequisites

Node and NPM: This sample requires a minimum Node.js version of 18, and is tested on versions 18 and 20. To get a supported version of Node.js, refer to the Node.js download page.

You will also need npm to build the code and run the samples.

Server configuration

This tutorial requires you to configure your PingOne server as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingOne, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Directory > Users.
Next to the Users label, click the plus icon ().

PingOne displays the Add User panel.
Enter the following details:
- Given Name = Demo
- Family Name = User
- Username = demo
- Email = demo.user@example.com
- Population = Default
- Password = Ch4ng3it!
Click Save.

Task 2. Create a revoke resource

To allow the Ping SDKs to revoke access tokens issued by PingOne, you must create a custom resource that is assigned the revoke scope in your PingOne tenant.

To create a custom resource and assign the revoke scope, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Applications > Resources.
Next to the Resources label, click the plus icon ().

PingOne displays the Add Custom Resource panel.
In Resource Name, enter a name for the custom resource, for example SDK Revoke Resource, and then click Next.
On the Attributes page, click Next.
On the Scopes page, click Add Scope.
In Scope Name, enter revoke, and then click Save.

When you have created the custom resource in your PingOne instance, continue with the next step.

For more information on resources in PingOne, refer to Adding a custom resource.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application in PingOne for use with the Ping SDK for JavaScript, follow these steps:

Log in to your PingOne administration console.
In the left panel, navigate to Applications > Applications.
Next to the Applications label, click the plus icon ().

PingOne displays the Add Application panel.
In Application Name, enter a name for the profile, for example sdkPublicClient
Select OIDC Web App as the Application Type, and then click Save.

On the Configuration tab, click the pencil icon ().

In Grant Type, select the following values:

Authorization Code

Refresh Token
In Redirect URIs, enter the following value:

org.forgerock.demo://oauth2redirect

https://localhost:8443

Also add any other URLs where you host SDK applications.

Failure to add redirect URLs that exactly match your client app’s values can cause PingOne to display an error message such as Redirect URI mismatch when attempting to end a session by redirecting from the SDK.

In Token Endpoint Authentication Method, select None.

In Signoff URLs, enter the following value:

org.forgerock.demo://oauth2redirect

https://localhost:8443

Also add any other URLs that redirect users to PingOne to end their session.

Failure to add sign off URLs that exactly match your client app’s values can cause PingOne to display an error message such as invalid post logout redirect URI when attempting to end a session by redirecting from the SDK.

In CORS Settings, in the drop-down select Allow specific origins, and in the Allowed Origins field, enter the URL where you will be running the sample app.

For example:

https://localhost:8443
Click Save.

On the Resources tab, next to Allowed Scopes, click the pencil icon ().
1. In Scopes, select the following values:
  
  email
  
  phone
  
  profile
  
  SDK Revoke Resource
  
  The openid scope is selected by default.
  
  The result resembles the following:
  
  Figure 41. Adding scopes, including the custom "revoke" scope to an application.
Optionally, on the Policies tab, click the pencil icon () to select the authentication policies for the application.

Applications that have no authentication policy assignments use the environment’s default authentication policy to authenticate users.

If you have a DaVinci license, you can select PingOne policies or DaVinci Flow policies, but not both. If you do not have a DaVinci license, the page only displays PingOne policies.

To use a PingOne policy:
1. Click Add policies and then select the policies that you want to apply to the application.
2. Click Save.
  
  PingOne applies the policies in the order in which they appear in the list. PingOne evaluates the first policy in the list first. If the requirements are not met, PingOne moves to the next one.
  
  For more information, see Authentication policies for applications.
To use a DaVinci Flow policy:
1. You must clear all PingOne policies. Click Deselect all PingOne Policies.
2. In the confirmation message, click Continue.
3. On the DaVinci Policies tab, select the policies that you want to apply to the application.
4. Click Save.
  
  PingOne applies the first policy in the list.
Click Save.
Enable the OAuth 2.0 client application by using the toggle next to its name:

Figure 42. Enable the application using the toggle.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the JavaScript example PingOne applications and tutorials covered by this documentation.

Step 1. Download the samples

To start this tutorial, you need to download the Ping SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the Ping SDK sample apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Install the Ping SDK

In the following procedure, you install the Ping SDK for JavaScript.

In a terminal window, navigate to the sdk-sample-apps folder.
To install the required packages, enter the following:
```
npm install
```
The npm tool downloads the required packages, and places them inside a node_modules folder.

More information

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne.

In the IDE of your choice, open the sdk-sample-apps folder you cloned in the previous step.
Open the /central-login/src/main.js file.
Replace the forgerock.Config.set method with this code:
```
await Config.setAsync({
  clientId: "<PingOne Client ID>",
  redirectUri: `${window.location.origin}`,
  scope: "openid profile email address revoke",
  serverConfig: {
    wellknown: "<OIDC Discovery Endpoint>",
  },
});
```
Replace the following strings with the values you obtained when you registered an OAuth 2.0 application in PingOne.
<PingOne Client ID>

The client ID from your OAuth 2.0 application in PingOne.

For example, 6c7eb89a-66e9-ab12-cd34-eeaf795650b2

<OIDC Discovery Endpoint>

The .well-known endpoint from your OAuth 2.0 application in PingOne.

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

To find the .well-known endpoint for an OAuth 2.0 client in PingOne:

Log in to your PingOne administration console.

Go to Applications > Applications, and then select the OAuth 2.0 client you created earlier.

For example, sdkPublicClient.

On the Configuration tab, expand the URLs section, and then copy the OIDC Discovery Endpoint value.

For example, https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration
The result resembles the following:
```
await Config.setAsync({
  clientId: "6c7eb89a-66e9-ab12-cd34-eeaf795650b2",
  redirectUri: `${window.location.origin}`,
  scope: "openid profile email address revoke",
  serverConfig: {
    wellknown: "https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration",
  },
});
```
Alter the logout object as follows:
1. In the forgerock.FRUser.logout() method, add the following parameter:
  
  {logoutRedirectUri: `${window.location.origin}`}
  
  The presence of this parameter causes the SDK to use a redirect flow for ending the session and revoking the tokens, which PingOne servers require.
2. Remove or comment out the following line:
  
  location.assign(`${document.location.origin}/`);
The result resembles the following:
const logout = async () => { try { await FRUser.logout({ logoutRedirectUri: `${window.location.origin}` }); // location.assign(`${document.location.origin}/`); } catch (error) { console.error(error); } };
Optionally, specify which of the configured policies PingOne uses to authenticate users.

In the /central-login/src/main.js file, on line 80, add an acr_values query parameter to the getTokens() call:
```
await TokenManager.getTokens({
  login: 'redirect',
  query: {
    acr_values: "<Policy IDs>"
  }
});
```
Replace <Policy IDs> with either a single DaVinci policy, by using its flow policy ID, or one or more PingOne policies by specifying the policy names, separated by spaces or the encoded space character %20.

Examples:

DaVinci flow policy ID

acr_values: "d1210a6b0b2665dbaa5b652221badba2"

PingOne policy names

acr_values: "Single_Factor%20Multi_Factor"

For more information, refer to Authentication policies.

Step 4. Test the app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingOne server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne server.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Run the sample

In a terminal window, navigate to the root of your sdk-sample-apps project.
To run the embedded login sample, enter the following:
```
npm run start:central-login
```
In a web browser, navigate to the following URL:

https://localhost:8443

The sample displays a page with two buttons:

Click Login.

The sample app redirects the browser to your PingOne instance.

To see the application calling the authorize endpoint, and the redirect back from PingOne with the code and state OAuth 2.0 parameters, open the Network tab of your browser’s developer tools.

Authenticate as a known user in your PingOne system.

After successful authentication, PingOne redirects the browser to the client application.

If the app displays the user information, authentication was successful:
To revoke the OAuth 2.0 token, click the Sign Out button.

The application redirects to the PingOne server to revoke the OAuth 2.0 token and end the session, and then returns to the URI specified by the logoutRedirectUri parameter of the logout method.

In this tutorial, PingOne redirects users back to the client application, ready to authenticate again.

Recap

Congratulations!

You have now used the Ping SDK for JavaScript to obtain an OAuth 2.0 access token on behalf of a user from your PingOne server.

You have seen how to obtain OAuth 2.0 tokens, and view the related user information.

More information

OIDC login to PingOne Advanced Identity Cloud tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingOne Advanced Identity Cloud UI for authentication.

The sample connects to the .well-known endpoint of your PingOne Advanced Identity Cloud tenant to obtain the correct URIs to authenticate the user, and redirects to your PingOne Advanced Identity Cloud tenant’s login UI.

After authentication, PingOne Advanced Identity Cloud redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingOne Advanced Identity Cloud tenant with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Install the Ping SDK

The sample projects need a number of dependencies that you can install by using the npm command.

For example, the Ping SDK for JavaScript itself is one of the dependencies.

Start step 2

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud.

Start step 3

Step 4. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingOne Advanced Identity Cloud tenant to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne Advanced Identity Cloud tenant.

After authentication, PingOne Advanced Identity Cloud redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingOne Advanced Identity Cloud tenant.

Node and NPM: This sample requires a minimum Node.js version of 18, and is tested on versions 18 and 20. To get a supported version of Node.js, refer to the Node.js download page.

You will also need npm to build the code and run the samples.

Server configuration

This tutorial requires you to configure your PingOne Advanced Identity Cloud tenant as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
In the left panel, click Identities > Manage.
Click New Alpha realm - User.
Enter the following details:
- Username = demo
- First Name = Demo
- Last Name = User
- Email Address = demo.user@example.com
- Password = Ch4ng3it!
Click Save.

Task 2. Create an authentication journey

To create a simple journey for use when testing the Ping SDKs, follow these steps:

In your PingOne Advanced Identity Cloud tenant, navigate to Journeys, and click New Journey.
Enter a name, such as sdkUsernamePasswordJourney and click Save.

The authentication journey designer appears.
Drag the following nodes into the designer area:
- Page Node
- Platform Username
- Platform Password
- Data Store Decision
Drag and drop the Platform Username and Platform Password nodes onto the Page Node, so that they both appear on the same page when logging in.
Connect the nodes as follows:

Figure 43. Example username and password authentication journey
Click Save.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
In the left panel, click Applications.
Click Custom Application.
Select OIDC - OpenId Connect as the sign-in method, and then click Next.
Select Native / SPA as the application type, and then click Next.
In Name, enter a name for the application, such as Public SDK Client.
In Owners, select a user that is responsible for maintaining the application, and then click Next.

When trying out the SDKs, you could select the demo user you created previously.
In Client ID, enter sdkPublicClient, and then click Create Application.

PingOne Advanced Identity Cloud creates the application and displays the details screen.
On the Sign On tab:
1. In Sign-In URLs, enter the following values:
  
  https://localhost:8443/callback.html
  
  org.forgerock.demo://oauth2redirect
  
  Also add any other domains where you host SDK applications.
2. In Grant Types, enter the following values:
  
  Authorization Code
  
  Refresh Token
3. In Scopes, enter the following values:
  
  openid profile email address
Click Show advanced settings, and on the Authentication tab:
1. In Token Endpoint Authentication Method, select none.
2. In Client Type, select Public.
3. Enable the Implied Consent property.
Click Save.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the example applications and tutorials covered by this documentation.

Task 4. Configure the OAuth 2.0 provider

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingOne Advanced Identity Cloud OAuth 2.0 provider service is configured for use with the Ping SDKs, follow these steps:

In your PingOne Advanced Identity Cloud tenant, navigate to Native Consoles > Access Management.
In the left panel, click Services.
In the list of services, click OAuth2 Provider.
On the Core tab, ensure Issue Refresh Tokens is enabled.
On the Consent tab, ensure Allow Clients to Skip Consent is enabled.
Click Save Changes.

Task 5. Configure CORS

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In PingOne Advanced Identity Cloud, you can configure CORS to allow browsers from trusted domains to access PingOne Advanced Identity Cloud protected resources. For example, you might want a custom web application running on your own domain to get an end-user’s profile information using the PingOne Advanced Identity Cloud REST API.

The Ping SDK for JavaScript samples and tutorials use https://localhost:8443 as the host domain, which you should add to your CORS configuration.

If you are using a different domain for hosting SDK applications, ensure you add them to the CORS configuration as accepted origin domains.

To update the CORS configuration in PingOne Advanced Identity Cloud, follow these steps:

Log in to your PingOne Advanced Identity Cloud tenant.
At the top right of the screen, click your name, and then select Tenant settings.
On the Global Settings tab, click Cross-Origin Resource Sharing (CORS).
Perform one of the following actions:
- If available, click ForgeRockSDK.
- If you haven’t added any CORS configurations to the tenant, click Add a CORS Configuration, select Ping SDK, and then click Next.
Add https://localhost:8443 and any DNS aliases you use to host your Ping SDK for JavaScript applications to the Accepted Origins property.

Complete the remaining fields to suit your environment.

This documentation assumes the following configuration, required for the tutorials and sample applications:

Property Values

Accepted Origins

https://localhost:8443

Accepted Methods

GET

POST

Accepted Headers

accept-api-version

x-requested-with

content-type

authorization

if-match

x-requested-platform

iPlanetDirectoryPro ^[1]

ch15fefc5407912 ^[2]

Exposed Headers

authorization

content-type

Enable Caching

True

Max Age

600

Allow Credentials

True

Click Show advanced settings to be able to edit all available fields.

Click Save CORS Configuration.

Step 1. Download the samples

To start this tutorial, you need to download the Ping SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the Ping SDK sample apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Install the Ping SDK

In the following procedure, you install the Ping SDK for JavaScript.

In a terminal window, navigate to the sdk-sample-apps folder.
To install the required packages, enter the following:
```
npm install
```
The npm tool downloads the required packages, and places them inside a node_modules folder.

More information

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud.

In the IDE of your choice, open the sdk-sample-apps folder you cloned in the previous step.
Make a copy of the /javascript/central-login-oidc/.env.example file, and name it .env.

The .env file provides the values used by the forgerock.Config.setAsync() method in javascript/central-login-oidc/src/main.js.
Update the .env file with the details of your PingOne Advanced Identity Cloud instance.
```
SCOPE="$SCOPE"
TIMEOUT=$TIMEOUT
WEB_OAUTH_CLIENT="$WEB_OAUTH_CLIENT"
WELL_KNOWN="$WELL_KNOWN"
SERVER_TYPE="$SERVER_TYPE"
```
Replace the following strings with the values you obtained when preparing your environment.
$SCOPE

The scopes you added to your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, address email openid phone profile

$TIMEOUT

How long to wait for OAuth 2.0 timeouts, in milliseconds.

For example, 3000

$WEB_OAUTH_CLIENT

The client ID from your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, sdkPublicClient

$WELL_KNOWN

The .well-known endpoint from your PingOne Advanced Identity Cloud tenant.

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:

Log in to your PingOne Advanced Identity Cloud administration console.

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

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

$SERVER_TYPE

Ensures the sample app uses the correct behavior for the different servers it supports, for example what logout parameters to use.

For PingOne Advanced Identity Cloud and PingAM servers, specify AIC.
The result resembles the following:
.env
```
SCOPE="address email openid phone profile"
TIMEOUT=3000
WEB_OAUTH_CLIENT="sdkPublicClient"
WELL_KNOWN="https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration"
SERVER_TYPE="AIC"
```

Step 4. Test the app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingOne Advanced Identity Cloud tenant to obtain the correct URIs to authenticate the user, and redirects the browser to your PingOne Advanced Identity Cloud tenant.

After authentication, PingOne Advanced Identity Cloud redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Run the sample

In a terminal window, navigate to the root of your sdk-sample-apps project.
To run the embedded login sample, enter the following:
```
npm run start:central-login-oidc
```
In a web browser, navigate to the following URL:

https://localhost:8443

The sample displays a page with two buttons:

Click Login.

The sample app redirects the browser to your PingOne Advanced Identity Cloud instance.

To see the application calling the authorize endpoint, and the redirect back from PingOne Advanced Identity Cloud with the code and state OAuth 2.0 parameters, open the Network tab of your browser’s developer tools.

Authenticate as a known user in your PingOne Advanced Identity Cloud tenant.

After successful authentication, PingOne Advanced Identity Cloud redirects the browser to the client application.

If the app displays the user information, authentication was successful:
To revoke the OAuth 2.0 token, click the Sign Out button.

In this tutorial, PingOne Advanced Identity Cloud redirects users back to the client application, ready to authenticate again.

Recap

Congratulations!

You have now used the Ping SDK for JavaScript to obtain an OAuth 2.0 access token on behalf of a user from your PingOne Advanced Identity Cloud tenant.

You have seen how to obtain OAuth 2.0 tokens, and view the related user information.

More information

OIDC login to PingAM tutorial for Android

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingAM UI for authentication.

The sample connects to the .well-known endpoint of your PingAM server to obtain the correct URIs to authenticate the user, and redirects to your PingAM server’s login UI.

After authentication, PingAM redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingAM server with the required configuration.

For example, you will need to have an OAuth 2.0 client application set up, and a demo user to authenticate.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Install the Ping SDK

The sample projects need a number of dependencies that you can install by using the npm command.

For example, the Ping SDK for JavaScript itself is one of the dependencies.

Start step 2

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingAM.

Start step 3

Step 4. Test the app

To test the app, run the sample that you configured in the previous step.

The sample connects to your PingAM server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingAM server.

After authentication, PingAM redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingAM server.

Node and NPM: This sample requires a minimum Node.js version of 18, and is tested on versions 18 and 20. To get a supported version of Node.js, refer to the Node.js download page.

You will also need npm to build the code and run the samples.

Server configuration

This tutorial requires you to configure your PingAM server as follows:

Task 1. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingAM, follow these steps:

Log in to the PingAM admin UI as an administrator.
Navigate to Identities, and then click Add Identity.
Enter the following details:
- User ID = demo
- Password = Ch4ng3it!
- Email Address = demo.user@example.com
Click Create.

Task 2. Create an authentication journey

To create a simple tree for use when testing the Ping SDKs, follow these steps:

Under Realm Overview, click Authentication Trees, then click Create Tree.
Enter a tree name, for example sdkUsernamePasswordJourney, and then click Create.

The authentication tree designer appears, showing the Start entry point connected to the Failure exit point.
Drag the following nodes from the Components panel on the left side into the designer area:
- Page Node
- Username Collector
- Password Collector
- Data Store Decision
Drag and drop the Username Collector and Password Collector nodes onto the Page Node, so that they both appear on the same page when logging in.
Connect the nodes as follows:

Figure 44. Example username and password authentication tree
Select the Page Node, and in the Properties pane, set the Stage property to UsernamePassword.

You can configure the node properties by selecting a node and altering properties in the right-hand panel.

One of the samples uses this specific value to determine the custom UI to display.
Click Save.

Task 3. Register a public OAuth 2.0 client

To register a public OAuth 2.0 client application for use with the SDKs in AM, follow these steps:

Log in to the PingAM admin UI as an administrator.
Navigate to Applications > OAuth 2.0 > Clients, and then click Add Client.
In Client ID, enter sdkPublicClient.
Leave Client secret empty.
In Redirection URIs, enter the following values:

org.forgerock.demo://oauth2redirect

https://localhost:8443/callback.html

The Ping SDK for JavaScript attempts to load the redirect page to capture the OAuth 2.0 code and state query parameters that the server appended to the redirect URL.

If the page you redirect to does not exist, takes a long time to load, or runs any JavaScript you might get a timeout, delayed authentication, or unexpected errors.

To ensure the best user experience, we highly recommend that you redirect to a static HTML page with minimal HTML and no JavaScript when obtaining OAuth 2.0 tokens.

Also add any other domains where you will be hosting SDK applications. . In Scopes, enter the following values:

+ openid profile email address . Click Create.

+ PingAM creates the new OAuth 2.0 client, and displays the properties for further configuration. . On the Core tab: .. In Client type, select Public. .. Disable Allow wildcard ports in redirect URIs. .. Click Save Changes. . On the Advanced tab: .. In Grant Types, enter the following values:

Authorization Code
Refresh Token

In Token Endpoint Authentication Method, select None.
Enable the Implied consent property.
1. Click Save Changes.

Task 4. Configure the OAuth 2.0 provider

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingAM OAuth 2.0 provider service is configured for use with the Ping SDKs, follow these steps:

Log in to the PingAM admin UI as an administrator.
In the left panel, click Services.
In the list of services, click OAuth2 Provider.
On the Core tab, ensure Issue Refresh Tokens is enabled.
On the Consent tab, ensure Allow Clients to Skip Consent is enabled.
Click Save Changes.

Task 5. Configure CORS

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In PingAM, you can configure CORS to allow browsers from trusted domains to access PingAM protected resources. For example, you might want a custom web application running on your own domain to get an end-user’s profile information using the PingAM REST API.

The Ping SDK for JavaScript samples and tutorials all use https://localhost:8443 as the host domain, which you should add to your CORS configuration.

If you are using a different URL for hosting SDK applications, ensure you add them to the CORS configuration as accepted origin domains.

To enable CORS in PingAM, and create a CORS filter to allow requests from your configured domain names, follow these steps:

Log in to the PingAM admin UI as an administrator.
Navigate to Configure > Global Services > CORS Service > Configuration, and set the Enable the CORS filter property to true.

If this property is not enabled, CORS headers are not added to responses from PingAM, and CORS is disabled entirely.
On the Secondary Configurations tab, click Click Add a Secondary Configuration.
In the Name field, enter ForgeRockSDK.

in the Accepted Origins field, enter any DNS aliases you use for your SDK apps.

This documentation assumes the following configuration:

Property Values

Accepted Origins

https://localhost:8443

Accepted Methods

GET

POST

Accepted Headers

accept-api-version

x-requested-with

content-type

authorization

if-match

x-requested-platform

iPlanetDirectoryPro ^[1]

ch15fefc5407912 ^[2]

Exposed Headers

authorization

content-type

Click Create.

PingAM displays the configuration of your new CORS filter.
On the CORS filter configuration page:
1. Ensure Enable the CORS filter is enabled.
2. Set the Max Age property to 600
3. Ensure Allow Credentials is enabled.
Click Save Changes.

Step 1. Download the samples

To start this tutorial, you need to download the Ping SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the Ping SDK sample apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Install the Ping SDK

In the following procedure, you install the Ping SDK for JavaScript.

In a terminal window, navigate to the sdk-sample-apps folder.
To install the required packages, enter the following:
```
npm install
```
The npm tool downloads the required packages, and places them inside a node_modules folder.

More information

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne Advanced Identity Cloud.

In the IDE of your choice, open the sdk-sample-apps folder you cloned in the previous step.
Make a copy of the /javascript/central-login-oidc/.env.example file, and name it .env.

The .env file provides the values used by the forgerock.Config.setAsync() method in javascript/central-login-oidc/src/main.js.
Update the .env file with the details of your PingAM server.
```
SCOPE="$SCOPE"
TIMEOUT=$TIMEOUT
WEB_OAUTH_CLIENT="$WEB_OAUTH_CLIENT"
WELL_KNOWN="$WELL_KNOWN"
SERVER_TYPE="$SERVER_TYPE"
```
Replace the following strings with the values you obtained when preparing your environment.

$SCOPE

The scopes you added to your OAuth 2.0 application in PingOne Advanced Identity Cloud.

For example, address email openid phone profile

$TIMEOUT

How long to wait for OAuth 2.0 timeouts, in milliseconds.

For example, 3000

$WEB_OAUTH_CLIENT

The client ID from your OAuth 2.0 application in PingAM.

For example, sdkPublicClient

$WELL_KNOWN

The .well-known endpoint from your PingAM tenant.

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

$SERVER_TYPE

Ensures the sample app uses the correct behavior for the different servers it supports, for example what logout parameters to use.

For PingOne Advanced Identity Cloud and PingAM servers, specify AIC.

The result resembles the following:
.env
```
SCOPE="address email openid phone profile"
TIMEOUT=3000
WEB_OAUTH_CLIENT="sdkPublicClient"
WELL_KNOWN="https://openam.example.com:8443/openam/oauth2/.well-known/openid-configuration"
SERVER_TYPE="AIC"
```

Step 4. Test the app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingAM server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingAM server.

After authentication, PingAM redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Run the sample

In a terminal window, navigate to sdk-sample-apps/javascript in your project.
To run the embedded login sample, enter the following:
```
npm run start:central-login-oidc
```
In a web browser, navigate to the following URL:

https://localhost:8443

The sample displays a page with two buttons:

Click Login.

The sample app redirects the browser to your PingAM instance.

To see the application calling the authorize endpoint, and the redirect back from PingAM with the code and state OAuth 2.0 parameters, open the Network tab of your browser’s developer tools.

Authenticate as a known user in your PingAM system.

After successful authentication, PingAM redirects the browser to the client application.

If the app displays the user information, authentication was successful:
To revoke the OAuth 2.0 token, click the Sign Out button.

In this tutorial, PingAM redirects users back to the client application, ready to authenticate again.

Recap

Congratulations!

You have now used the Ping SDK for JavaScript to obtain an OAuth 2.0 access token on behalf of a user from your PingAM server.

You have seen how to obtain OAuth 2.0 tokens, and view the related user information.

More information

OIDC login to PingFederate tutorial for JavaScript

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the PingFederate UI for authentication.

The sample connects to the .well-known endpoint of your PingFederate server to obtain the correct URIs to authenticate the user, and redirects to your PingFederate server’s login UI.

After authentication, PingFederate redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Before you begin

Before you begin this tutorial ensure you have set up your PingFederate server with the required configuration.

For example, you will need to configure CORS, have an OAuth 2.0 client application set up.

Complete prerequisites

Step 1. Download the samples

To start this tutorial, you need to download the SDK sample apps repo, which contains the projects you will use.

Start step 1

Step 2. Install the Ping SDK

The sample projects need a number of dependencies that you can install by using the npm command.

For example, the Ping SDK for JavaScript itself is one of the dependencies.

Start step 2

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingFederate.

Start step 3

Step 4. Test the app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingFederate server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingFederate server.

After authentication, PingFederate redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Test app

Before you begin

To successfully complete this tutorial refer to the prerequisites in this section.

The tutorial also requires a configured PingFederate server.

Prerequisites

Node and NPM: This sample requires a minimum Node.js version of 18, and is tested on versions 18 and 20. To get a supported version of Node.js, refer to the Node.js download page.

You will also need npm to build the code and run the samples.

Server configuration

This tutorial requires you to configure your PingFederate server as follows:

Task 1. Register a public OAuth 2.0 client

OAuth 2.0 client application profiles define how applications connect to PingFederate and obtain OAuth 2.0 tokens.

To allow the Ping SDKs to connect to PingFederate and obtain OAuth 2.0 tokens, you must register an OAuth 2.0 client application:

Log in to the PingFederate administration console as an administrator.
Navigate to Applications OAuth Clients.
Click Add Client.

PingFederate displays the Clients | Client page.
In Client ID and Name, enter a name for the profile, for example sdkPublicClient

Make a note of the Client ID value, you will need it when you configure the sample code.
In Client Authentication, select None.

In Redirect URIs, add the following values:

org.forgerock.demo://oauth2redirect

https://localhost:8443

Also add any other URLs where you host SDK applications.

In Allowed Grant Types, select the following values:

Authorization Code

Refresh Token

In the OpenID Connect section:

In Logout Mode, select Ping Front-Channel

In Front-Channel Logout URIs, add the following values:

org.forgerock.demo://oauth2redirect

https://localhost:8443

Also add any other URLs that redirect users to PingFederate to end their session.

In Post-Logout Redirect URIs, add the following values:

org.forgerock.demo://oauth2redirect

https://localhost:8443

Click Save.

After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.

In the PingFederate administration console, navigate to System > Server > Cluster Management, and click Replicate.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Ping SDK PingFederate example applications and tutorials covered by this documentation.

Task 2. Configure CORS

To configure CORS in PingFederate follow these steps:

Log in to the PingFederate administration console as an administrator.
Navigate to System OAuth Settings Authorization Server Settings.
In the Cross-Origin Resource Sharing Settings section, in the Allowed Origin field, enter any DNS aliases you use for your SDK apps.

This documentation assumes the following configuration:

Property Values

Allowed Origin

org.forgerock.demo://oauth2redirect https://localhost:8443

Click Save.

After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.

In the PingFederate administration console, navigate to System > Server > Cluster Management, and click Replicate.

Your PingFederate server is now able to accept connections from origins hosting apps built with the Ping SDKs.

Step 1. Download the samples

To start this tutorial, you need to download the Ping SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the Ping SDK sample apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Install the Ping SDK

In the following procedure, you install the Ping SDK for JavaScript.

In a terminal window, navigate to the sdk-sample-apps folder.
To install the required packages, enter the following:
```
npm install
```
The npm tool downloads the required packages, and places them inside a node_modules folder.

More information

Step 3. Configure connection properties

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingFederate.

In the IDE of your choice, open the sdk-sample-apps folder you cloned in the previous step.
Open the /central-login/src/main.js file.
Replace the forgerock.Config.set method with this code:
```
await Config.setAsync({
  clientId: "<PingFederate Client ID>",
  redirectUri: `${window.location.origin}`,
  scope: "address email openid phone profile",
  serverConfig: {
    wellknown: "<PingFederate .well-known URL>",
  },
});
```
Replace the following strings with the values you obtained when you registered an OAuth 2.0 application in PingFederate.
<PingFederate Client ID>

The client ID from your OAuth 2.0 application in PingFederate.

For example, sdkPublicClient

<PingFederate .well-known URL>

The .well-known endpoint of your PingFederate server.

How do I find my PingFederate .well-known URL?

You can form your .well-known endpoint by adding /.well-known/openid-configuration to your server’s base URL.

To view the base URL of your PingFederate server:

Log in to your PingFederate administration console.

Navigate to System Server Protocol Settings.

Make a note of the Base URL value.

For example, https://pingfed.example.com

Do not use the admin console URL.

Append `/.well-known/openid-configuration ` to your base URL.

For example, https://pingfed.example.com/.well-known/openid-configuration
The result resembles the following:
```
await Config.setAsync({
  clientId: "sdkPublicClient",
  redirectUri: `${window.location.origin}`,
  scope: "address email openid phone profile",
  serverConfig: {
    wellknown: "https://pingfed.example.com/.well-known/openid-configuration",
  },
});
```

Step 4. Test the app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingFederate server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingFederate server.

After authentication, PingFederate redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Run the sample

In a terminal window, navigate to the root of your sdk-sample-apps project.
To run the embedded login sample, enter the following:
```
npm run start:central-login
```
In a web browser, navigate to the following URL:

https://localhost:8443

The sample displays a page with two buttons:

Click Login.

The sample app redirects the browser to your PingFederate instance.

To see the application calling the authorize endpoint, and the redirect back from PingFederate with the code and state OAuth 2.0 parameters, open the Network tab of your browser’s developer tools.

Authenticate as a known user in your PingFederate system.

After successful authentication, PingFederate redirects the browser to the client application.

If the app displays the user information, authentication was successful:
To revoke the OAuth 2.0 token, click the Sign Out button.

In this tutorial, PingFederate redirects users back to the client application, ready to authenticate again.

Recap

Congratulations!

You have now used the Ping SDK for JavaScript to obtain an OAuth 2.0 access token on behalf of a user from your PingFederate server.

You have seen how to obtain OAuth 2.0 tokens, and view the related user information.

More information

1. Cookie name value in PingAM servers.

2. In PingOne Advanced Identity Cloud tenants, go to Tenant Settings > Global Settings > Cookie to find this dynamic cookie name value.