Navigate to a specific journey using centralized login

This is part four of a four-part article, Integrate with Identity Cloud hosted pages. This is part four of a four-part article, Integrate with Identity Cloud hosted pages.

Overview

Who is this article for?

This is part four of a step-by-step guide for anyone who wishes to use ForgeRock SDK with hosted pages. The goal is to give you practical advice about theming and provide some best practices along the way.

Prior knowledge configuring Identity Cloud is helpful but not assumed.

Centralized UI and authentication journeys

In part two and part three of this guide, we used a centralized UI to authenticate our app with Identity Cloud.

When using a centralized UI by default, the user is redirected to the default realm journey. In some cases, you may want to point users to different authentication journeys:

Using elevated authentication in certain platforms (2FA, geofencing, and jailbreak detection).

Using centralized UI for authenticating different types of users (admins, clients).

The ForgeRock SDKs for iOS, Android, and JavaScript let you easily configure the journey (tree) for authentication.

In this part of the tutorial, we use ACR values for authentication.

ACR Claims

In the OpenID Connect specification, the acr claim identifies a set of rules that the user must satisfy when authenticating to the OpenID provider. For example, a chain or journey (tree) configured in AM.

To avoid exposing the name of authentication trees or chains, AM implements a map that consists of a key (the value that is part of the acr claim), and the name of the authentication tree or chain.

The OpenID Connect specification indicates that the acr claim is a list of authentication contexts. AM honors the first value in the list for which it has a valid mapping. For example, if the relying party requests a list of acr values, such as acr-1 acr-2 acr-3, and only acr-2 and acr-3 are mapped, AM always chooses acr-2 to authenticate the end user.

The ForgeRock iOS, Android, and JavaScript SDKs leverage the traditional authorization code flow with PKCE from the OAuth 2.0 spec. When using centralized login, to enable the client app to customize the flow, we use the Authentication Context Class Reference (ACR) property to communicate context to the authorization server (Identity Cloud).

Using this method, the client app chooses the journey it presents to the user. You can pre-configure this in the OAuth2.0 client, or on the fly from the client application.

Configure AM

Verify or change settings in the OAuth 2.0 provider

In part two of this guide, we set the OAuth2.0 provider in AM. One of the steps was to enable the claims_parameter_supported option. Perform the following steps to verify or change this option:

In the AM admin UI, navigate to Services.
Select the OAuth 2.0 provider.
Navigate to the Advanced OpenID Connect tab.
Confirm that Enable "claims_parameter_supported" is set to ON.
In OpenID Connect acr_values, add a new entry: Auth Chain Mapping.
Save the configuration.

Configure a new journey

In the Admin UI, click Journeys.
Click +New journey and name it SimpleLogin.
Use the editor to create a journey.

Configure ACR values and the JavaScript SDK

Configure SPA to use the SimpleLogin journey

Returning to the SPA from part two of the guide, open the project in Visual Studio Code.
Create a new constant:
```
const acr_values = 'simple';
```

If using ForgeRock JavaScript SDK v2.2.0 or earlier, replace the SDK configuration with the following:

Config.set({
 clientId,
 middleware: [
        (req, action, next) => {
                 if (action.type === 'AUTHORIZE') {
                     req.url.searchParams.append('acr_values', acr_values);
                                 }
                 next();

             },
         ],
 realmPath,
 redirectUri,
 scope,
 serverConfig: {
     baseUrl,
     },
 support,
});

req.url.searchParams.append('acr_values', acr_values);' changes the searchParams query string.

If using the latest version of the ForgeRock JavaScript SDK 3 or later, you can dynamically pass the acr_values constant in the TokenManager.getTokens() method. See the example code below:

/**
* The key-value of `login: redirect` is what allows central-login.
* Passing no arguments or a key-value of `login: 'embedded'` means
* the app handles authentication locally.
*/
const acr_values = 'simple';
await forgerock.TokenManager.getTokens({ login: 'redirect', query: { acr_values }});

When testing the application, you expect to use the SimpleLogin journey for authentication.

Configure ACR values and the iOS SDK

Configure iOS to use the SimpleLogin journey

Returning to the iOS application from Part 3 of this guide, open the .xcworkspace file using Xcode.

Locate the Login code in ViewController.swift, and replace it with the following:

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

Notice .setCustomParam(key: "acr_values", value: "simple").

When testing the application, you expect to use the SimpleLogin journey for authentication.

Configure ACR values and the Android SDK

Configure Android to use the SimpleLogin journey

Returning to the Android application created in part three of this guide, open the project using Android Studio.

Locate the Login code in MainActivity.java, and replace it with the following:

FRUser.browser().appAuthConfigurer()
             .authorizationRequest(r -> {
                 Map<String, String> additionalParameters = new HashMap<>();
                 additionalParameters.put("acr_values", "simple");
                 r.setAdditionalParameters(additionalParameters)
             })
             .customTabsIntent(t -> {
                 t.setShowTitle(false);
                 t.setToolbarColor(getResources().getColor(R.color.colorAccent));
             }).done()
             .login(this, new FRListener<FRUser>() {
                 @Override
                 public void onSuccess(FRUser result) {
                     userinfo();
                 }

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

Notice the additionalParameters.put("acr_values", "simple"). When testing the application, you expect to use the SimpleLogin journey for authentication.

Summary

In this part, you learned how to use acr claims in AM and the ForgeRock SDKs for iOS, Android, and JavaScript to authenticate users using a specific authentication journey.

This concludes part four of this how-to guide. Use the lessons of this guide to elevate the user experience of your apps using Identity Cloud and the centralized UI.

Related resources

Identity Cloud documentation

ForgeRock GitHub

ForgeRock Developer Experience