Ping SDKs

Set up user profile self service

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

The Ping SDKs support many of the callbacks used by authentication journeys, including ones that enable your users to manage their own profile information, such as name, address, phone numbers and marketing preferences.

To update a user’s profile information you must have already authenticated them and issued a session token. You can then use that session token to start a new journey which allows the user to update their profile data.

Compatibility

PingIDM is responsible for profile management. Therefore this tutorial is only compatible with the following server environments:

Before you begin

You must create an authentication journey that checks for the presence of a user session and then displays the user profile fields for editing. The journey must also update the profile with any changed values.

Create a user profile management journey

Follow the steps below to create a user profile management journey:

  1. Create a new journey or tree and give it a name:

    PingOne Advanced Identity Cloud

    1. In your PingOne Advanced Identity Cloud tenant, navigate to Journeys, and click New Journey.

    2. Enter a name, such as sdkProfileManagement and click Save.

      The authentication journey designer appears.

    PingAM

    1. Under Realm Overview, click Authentication Trees, then click Create Tree.

    2. Enter a tree name, for example sdkProfileManagement, and then click Create.

      The authentication tree designer appears, showing the Start entry point connected to the Failure exit point.

  2. Drag the following nodes into the designer area:

    • Get Session Data

    • Attribute Collector

    • Patch Object

    • Data Store Decision

  3. Connect the nodes as follows:

    sdk profile management journey idcloud en
    Figure 1. Example profile management authentication journey

  4. Select the Get Session Data node and configure it to obtain the user’s account name from the session and store it in shared state, as follows:

    1. In Session Data Key, enter UserToken.

      This field is case-sensitive. The value must exactly match the name of a property in the user’s session.

      For a list of properties, refer to Get Session Data node.

    2. In Shared State Key, enter userName.

    The result resembles the following:

    journey profile management get session data config
    Figure 2. Configure the Get Session Data node for profile management.

  5. Select the Attribute Collector node and configure it with the profile attributes you want the user to view and edit:

    1. In Attributes to Collect, enter the profile attributes to display. For example:

      • givenName

      • sn

      • mail

      • telephoneNumber

      • postalAddress

      • city

      • country

      • preferences/marketing

    2. In Identity Attribute, enter userName.

    The result resembles the following:

    journey profile management attribute collector config
    Figure 3. Configure the Attribute Collector node for profile management.

  6. Select the Patch Object node and configure it to update the user’s profile:

    1. In Identity Resource, enter managed/alpha_user.

    2. In Identity Attribute, enter userName.

    The result resembles the following:

    journey profile management patch object config
    Figure 4. Configure the Patch Object node for profile management.

  7. Click Save.

Server configuration

This tutorial requires you to configure one of the following servers:

PingOneAICStacked

PingOne Advanced Identity Cloud
PingAM

PingAM

PingOne Advanced Identity Cloud

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:

  1. Log in to your PingOne Advanced Identity Cloud tenant.

  2. In the left panel, click Identities > Manage.

  3. Click New Alpha realm - User.

  4. Enter the following details:

    • Username = demo

    • First Name = Demo

    • Last Name = User

    • Email Address = demo.user@example.com

    • Password = Ch4ng3it!

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

  1. In your PingOne Advanced Identity Cloud tenant, navigate to Journeys, and click New Journey.

  2. Enter a name, such as sdkUsernamePasswordJourney and click Save.

    The authentication journey designer appears.

  3. Drag the following nodes into the designer area:

    • Page Node

    • Platform Username

    • Platform Password

    • Data Store Decision

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

  5. Connect the nodes as follows:

    sdk username password journey idcloud en
    Figure 5. Example username and password authentication journey

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

  1. Log in to your PingOne Advanced Identity Cloud tenant.

  2. In the left panel, click Applications.

  3. Click Custom Application.

  4. Select OIDC - OpenId Connect as the sign-in method, and then click Next.

  5. Select Native / SPA as the application type, and then click Next.

  6. In Name, enter a name for the application, such as Public SDK Client.

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

  8. In Client ID, enter sdkPublicClient, and then click Create Application.

    PingOne Advanced Identity Cloud creates the application and displays the details screen.

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

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

  11. 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 service

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:

  1. In your PingOne Advanced Identity Cloud tenant, navigate to Native Consoles > Access Management.

  2. In the left panel, click Services.

  3. In the list of services, click OAuth2 Provider.

  4. On the Core tab, ensure Issue Refresh Tokens is enabled.

  5. On the Consent tab, ensure Allow Clients to Skip Consent is enabled.

  6. Click Save Changes.

PingAM

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:

  1. Log in to the PingAM admin UI as an administrator.

  2. Navigate to Identities, and then click Add Identity.

  3. Enter the following details:

    • User ID = demo

    • Password = Ch4ng3it!

    • Email Address = demo.user@example.com

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

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 tree for use when testing the Ping SDKs, follow these steps:

  1. Under Realm Overview, click Authentication Trees, then click Create Tree.

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

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

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

  5. Connect the nodes as follows:

    trees node login example
    Figure 6. Example username and password authentication tree

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

  7. 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 AM, follow these steps:

  1. Log in to the PingAM admin UI as an administrator.

  2. Navigate to Applications > OAuth 2.0 > Clients, and then click Add Client.

  3. In Client ID, enter sdkPublicClient.

  4. Leave Client secret empty.

  5. In Redirection URIs, enter the following values:

    org.forgerock.demo://oauth2redirect

    Also add any other domains where you will be hosting SDK applications.

  6. In Scopes, enter the following values:

    openid profile email address

  7. Click Create.

    PingAM creates the new OAuth 2.0 client, and displays the properties for further configuration.

  8. On the Core tab:

    1. In Client type, select Public.

    2. Disable Allow wildcard ports in redirect URIs.

    3. Click Save Changes.

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

  10. Click Save Changes.

Task 4. Configure the OAuth 2.0 provider service

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:

  1. Log in to the PingAM admin UI as an administrator.

  2. In the left panel, click Services.

  3. In the list of services, click OAuth2 Provider.

  4. On the Core tab, ensure Issue Refresh Tokens is enabled.

  5. On the Consent tab, ensure Allow Clients to Skip Consent is enabled.

  6. Click Save Changes.

Try it out

Follow the steps below to configure and run one of our sample applications to test profile self-management.

Step 1. Download the sample apps

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

  1. In a web browser, navigate to the Ping SDK sample apps repository.

  2. Download the source code using one of the following methods:

    Download a ZIP file

    1. Click Code, and then click Download ZIP.

    2. Extract the contents of the downloaded ZIP file to a suitable location.

    Use a Git-compatible tool to clone the repo locally

    1. Click Code, and then copy the HTTPS URL.

    2. 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 sample apps

Depending on the platform you are using, follow the steps below to configure a sample application to connect to your server.

  • Android

  • iOS

In this step, you configure the "kotlin-ui-prototype" sample to connect to your server.

  1. In Android Studio, open the sdk-sample-apps/android/kotlin-ui-prototype folder you cloned in the previous step.

  2. In the Project pane, switch to the Android view.

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

  4. Update the PingAM or PingAdvancedIdentityCloud example configuration values to match your server environment:

    url

    The URL of the server to connect to.

    Identity Cloud example:

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

    Self-hosted example:

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

    cookieName

    The name of the cookie that contains the session token.

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

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

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

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

    Usually, root for AM and alpha or beta for Advanced Identity Cloud.

    oauthClientId

    The client ID of your OAuth 2.0 application in PingOne Advanced Identity Cloud or PingAM.

    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.

  5. Update the USER_PROFILE_JOURNEY variable with the name of the profile management journey you created earlier.

    For example, sdkProfileManagement

  6. Save your changes.

In this step, you configure the "FRExample" sample app to connect to your server.

  1. In Xcode, on the File menu, click Open.

  2. Navigate to the sdk-sample-apps folder you cloned in the previous step, navigate to iOS > uikit-frexamples > FRExample > FRExample.xcodeproj, and then click Open.

  3. In the navigator pane in Xcode, right-click FRExample/Configs/FRAuthConfig and select Open As > Source Code.

  4. Update the following key values to match your server environment:

    forgerock_url

    The URL of the server to connect to.

    Identity Cloud example:

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

    Self-hosted example:

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

    forgerock_cookie_name

    The name of the cookie that contains the session token.

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

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

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

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

    Usually, root for AM and alpha or beta for Advanced Identity Cloud.

    forgerock_oauth_client_id

    The client ID of your OAuth 2.0 application in PingOne Advanced Identity Cloud or PingAM.

    For example, sdkPublicClient

    forgerock_oauth_redirect_uri

    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.

  5. Save your changes.

Step 3. Run the sample app

Depending on the platform you are using, follow the steps below to run the sample application, obtain a session token, and use it to complete the self-registration journey you created earlier.

  • Android

  • iOS

  1. In Android Studio, select Run > Run 'app'.

  2. Tap the menu icon (), and then tap rocket_launch Launch Journey.

  3. In Journey Name enter the name of a journey that will authenticate the user and issue a session, and then click Submit.

    For example, enter sdkUsernamePasswordJourney to use the authentication tree you created earlier.

  4. Sign on as a demo user:

    • Name: demo

    • Password: Ch4ng3it!

  5. After successful authentication, tap the menu icon (), and then tap account_box User Profile.

    The app sends the session token to the journey which extracts the username and returns their profile information:

    android sample app profile page en
    Figure 7. Viewing a user’s profile information in an Android sample app.

  6. Update any of the presented properties and then click Next.

  7. To verify the profile was updated, tap the menu icon (), and then tap account_box User Profile.

    The app displays the updated profile values.

  1. In Xcode, select Product > Run.

    Xcode launches the FRExample app in the iPhone simulator.

  2. In the sample app on the iPhone simulator, in the Select an action menu, select Login with UI (FRUser), and then click Perform Action.

  3. Sign on as a demo user:

    • Name: demo

    • Password: Ch4ng3it!

  4. After successful authentication, in the Select an action menu, select FRSession.authenticate with UI (Token), and then click Perform Action.

  5. In the popup window, enter the name of the profile management journey you created earlier, and then click Continue.

    For example, sdkProfileManagement

  6. Update any of the presented properties and then click Next.

    The app sends the session token to the journey which extracts the username and returns their profile information:

    ios sample app profile page en
    Figure 8. Viewing a user’s profile information in an iOS sample app.

  7. Update any of the presented properties and then click Next.

  8. To verify the profile was updated, tap Perform Action again, enter the name of your profile management tree and then click Continue.

    The app displays the updated profile values.