Ping SDKs

Part 3. Running a client sample app

In this section you configure one of the OIDC (centralized login) sample apps to test out your custom UI.

Running the JavaScript sample OIDC client app

  1. In a JavaScript-capable IDE, open the sdk-sample-apps folder you downloaded earlier.

  2. Open the /javascript/central-login-oidc sample.

  3. Edit the values in the .env.sample file to match your environment:

    1. In SCOPE, enter the list of scopes to request are present in the issued OAuth 2.0 token.

      For example, "openid profile email phone address"

    2. In WEB_OAUTH_CLIENT, enter the client ID of the OAuth 2.0 client you configured earlier.

      For example, sdkCustomUI

    3. In WELL_KNOWN, enter the .well-known URL of the realm in which you created the OAuth 2.0 client.

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

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

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

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

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

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

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

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

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

      2. The string /oauth2

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

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

        For example, /realms/root/realms/customers

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

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

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

    The result will resemble the following:

    Example .env.example file
    SCOPE="openid profile email phone address"
TIMEOUT=1000
WEB_OAUTH_CLIENT=sdkCustomUI
WELL_KNOWN=https://openam-docs-regular.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration
SERVER_TYPE=AIC

  4. Save the file as .env in the same folder.

  5. Edit the webpack.config.js file.

    1. In the devServer section, add the DNS alias you created earlier, for example sdkapp.example.com in a new allowedHosts property:

      devServer: {
    port: 8443,
    host: 'localhost',
    allowedHosts: 'sdkapp.example.com',
    …​
}

  6. From the /javascript folder, run the central login OIDC sample app as follows:

    cd javascript
npm run start:central-login-oidc

    Webpack compiles the code and serves it on the local IP address of your computer.

Try it out

To test that your custom UI app is acting as the centralized login pages, perform the following steps.

  1. In a browser, open the local IP address of your computer, with the port number you edited earlier.

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

  2. As the custom UI sample app is running on a self-signed SSL certificate on your local IP address, your browser might display a warning message.

    You can ignore this warning for this tutorial:

    • In Chrome, click Advanced and then click Proceed to sdkapp.example.com (unsafe).

    • In Firefox, click Advanced and then click Accept the risk and continue.

    • In Safari, click Show Details and then click visit this website.

    The sample OIDC login app displays Login and Force Renew buttons:

    js central sample page 1 en
    Figure 1. JavaScript OIDC sample app showing Login and Force Renew buttons.

  3. Click the Login button.

    The client app connects to the OAuth 2.0 client you created earlier, and is redirected to the custom UI sample running on your local computer.

    The URL contains a goto parameter that contains the URL that the UI sample app redirects to after successful authentication. That URL will be the authorize endpoint of your authorization server.

  4. Enter the credentials of a known user, and then click Sign In.

    1. If authentication is successful, the custom UI app redirects the browser to the goto URL, which points to your authorization server. The authorization server redirects back to your client app with the necessary code parameter.

    2. The sample client app uses the code parameter to contact the authorization server access_token endpoint to obtain the OAuth 2.0 access and ID tokens.

    3. Using the access token as a bearer token, the sample app calls the userinfo endpoint and displays them on the page:

      aic am oidc login userinfo
      Figure 2. Userinfo of the authenticated user.

Running the Android sample OIDC client app

  1. In Android Studio, open the /android/kotlin-central-login-oidc sample from the repo you downloaded earlier.

  2. Edit the app > kotlin+java > Config.kt file to match your environment:

    1. In discoveryEndpoint, enter the .well-known URI of the realm in which you created the OAuth 2.0 client.

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

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

      1. Log in to your PingAM administration console.

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

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

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

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

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

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

      2. The string /oauth2

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

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

        For example, /realms/root/realms/customers

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

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

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

    2. In oauthClientId, enter the client ID of the OAuth 2.0 client you configured earlier.

      For example, sdkCustomUI

    3. In oauthRedirectUri, enter the redirect URI you configured in the OAuth 2.0 client.

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

    4. In cookieName, enter the name of the cookie your authorization server uses to store session tokens on the client.

      For example, PingAM servers use iPlanetDirectoryPro

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

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

      1. Navigate to Tenant settings > Global Settings

      2. Copy the value of the Cookie property.

    5. In oauthScope, enter the list of scopes to request are present in the issued OAuth 2.0 token.

      For example, openid profile email phone address

    The result will resemble 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 = "sdkCustomUI",
    var oauthRedirectUri: String = "org.forgerock.demo://oauth2redirect",
    var oauthSignOutRedirectUri: String = "",
    var cookieName: String = "ch15fefc5407912",
    var oauthScope: String = "openid profile email phone address"
)

  3. Save your changes.

Try it out

To test that your custom UI app is acting as the centralized login pages, perform the following steps.

  1. In Android Studio, on the Run menu, select Run 'ping-oidc.app'.

    Android Studio compiles and launches the app in either your connected device or a simulator, and displays the configuration you entered earlier:

    kotlin oidc app android config
    Figure 3. Android sample app showing the configuration.

    You can alter the values in the app if required.

  2. Click Centralized Login.

  3. As the custom UI sample app is running on a self-signed SSL certificate on your local IP address, your browser might display a warning message.

    You can ignore this warning for this tutorial:

    • In Chrome, click Advanced and then click Proceed to 192.168.0.35 (unsafe).

    • In Firefox, click Advanced and then click Accept the risk and continue.

    The client app connects to the OAuth 2.0 client you created earlier, and is redirected to the custom UI sample running on your local computer.

    The URL contains a goto parameter that contains the URL that the UI sample app redirects to after successful authentication. That URL will be the authorize endpoint of your authorization server.

  4. Enter the credentials of a known user, and then click Sign In.

    1. If authentication is successful, the custom UI app redirects the browser to the goto URL, which points to your authorization server. The authorization server redirects back to your client app with the necessary code parameter.

    2. The sample client app uses the code parameter to contact the authorization server access_token endpoint to obtain the OAuth 2.0 access and ID tokens:

      kotlin oidc app android access token
      Figure 4. Android OIDC sample app showing the access and ID tokens.

    3. Tap the menu icon (), and then tap User Profile:

      The OIDC sample app uses the access token as a bearer token and calls the userinfo endpoint, displaying the result:

      kotlin oidc app android userinfo
      Figure 5. Userinfo of the authenticated user.

Running the iOS sample OIDC client app

  1. In Xcode, in the sdk-sample-apps folder you cloned in the previous step, open the iOS > swiftui-oidc > PingExample > PingExample.xcodeproj file.

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

    1. In clientId, enter the client ID of the OAuth 2.0 client you configured earlier.

      For example, sdkCustomUI

    2. In scopes, enter an array of scopes to request are present in the issued OAuth 2.0 token.

      For example, ["openid","profile","email","address","phone"]

    3. In redirectUri and signOutUri, enter the redirect URI you configured in the OAuth 2.0 client.

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

    4. In discoveryEndpoint, enter the .well-known URI of the realm in which you created the OAuth 2.0 client.

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

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

      1. Log in to your PingAM administration console.

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

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

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

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

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

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

      2. The string /oauth2

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

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

        For example, /realms/root/realms/customers

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

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

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

    5. In environment, enter AIC.

    6. In cookieName, enter the name of the cookie your authorization server uses to store session tokens on the client.

      For example, PingAM servers use iPlanetDirectoryPro

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

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

      1. Navigate to Tenant settings > Global Settings

      2. Copy the value of the Cookie property.

    7. In browserSeletorType, enter .authSession.

      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

      .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, including any session tokens.

      When is ephemeralAuthSession suitable:

      • ephemeralAuthSession is not suitable when you require single sign-on (SSO) between your iOS apps, as the browser will not maintain session tokens.

      • ephemeralAuthSession is not suitable when you require a session token to log a user out of the server, for example for logging out of PingOne, as the browser will not maintain session tokens.

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

    The result resembles the following:

    return ConfigurationViewModel(
    clientId: "sdkCustomUI",
    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/realms/alpha/.well-known/openid-configuration",
    environment: "AIC",
    cookieName: "ch15fefc5407912",
    browserSeletorType: .authSession
)

  3. Save your changes.

Try it out

To test that your custom UI app is acting as the centralized login pages, perform the following steps.

  1. In Xcode, select Product > Run.

    Xcode launches the sample app in the iPhone simulator.

    ios custom ui menu
    Figure 6. iOS OIDC login sample home screen
    Third-party cookies in the Safari browser

    Safari blocks third-party cookies by default, so the custom UI app will not be able to authenticate calls to the /authorize endpoint if it is running on a different domain than the server.

    In production, ensure your custom UI app and server share the same domain.

    For this tutorial disable third-party cookie checks in Safari as follows:

    1. In the iPhone simulator, in the toolbar click Home. On the screen, use your mouse to swipe to the right, and then tap Settings.

    2. Tap Safari, scroll to the Privacy & Security section, and disable Prevent Cross-Site Tracking.

      safari allow cross site tracking
      Figure 7. Allow third-party cookies in Safari

    3. To return to the sample app, in the toolbar double-click Home to show the open apps, and then tap the PingOIDC app.

      ios switch to oidc app
      Figure 8. Return to the OIDC sample app by double-clicking the home icon.

  2. In the sample app on the iPhone simulator, tap Edit configuration, and verify or edit the configuration you entered in the previous step.

    ios custom ui config
    Figure 9. Verify the configuration settings

  3. 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 connects to your authorization server, which then redirects to the custom UI app running locally on your computer:

    ios custom ui login
    Figure 10. Browser launched and redirected to local custom UI app.

  4. Sign on as a demo user:

    • Name: demo

    • Password: Ch4ng3it!

    If authentication is successful, the application displays the access token issued by PingAM.

    ios custom ui token
    Figure 11. Access token after successful authentication

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

    ios custom ui userinfo
    Figure 12. User info relating to the access token

  6. 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.7.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.7.0] [FRUser.swift:211 : logout()] [Verbose]
  Invalidating OIDC Session successful