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 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 thesearchParams
query string.If using the latest version of the ForgeRock JavaScript SDK 3 or later, you can dynamically pass the
acr_values
constant in theTokenManager.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 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 theSimpleLogin
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.