This article was written by George Bafaloukas and Adam Crockett.
Overview
Who is this article for?
Step-by-step instructions follow for anyone who wishes to use hosted pages in their mobile or web app, with the help of the ForgeRock SDKs. The goal is to give you practical advice about themes and provide some best practices along the way.
Prior knowledge configuring ForgeRock Identity Cloud is helpful but not assumed.
This article is the last of four in a series:
- Themes in ForgeRock Identity Cloud (Part 1)
- Integrating a Single-Page App (SPA) with ForgeRock Identity Cloud (Part 2)
- Integrating Native Mobile Apps with ForgeRock Identity Cloud (Part 3)
- Navigating to a Specific Journey Using a Centralized Login with ForgeRock Identity Cloud (Part 4)
Centralized UI and authentication journeys
In Part 2 and Part 3 of this series, we used a centralized UI to authenticate our app with ForgeRock 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 Centralised UI for authenticating different types of users (admins, clients).
The Forgerock SDKs for iOS, Android, and JavaScript (JS) let you easily configure the journey (tree) for authentication.
In this part of the series, we use ACR Values for authentication.
ACR claims
In the OpenID Connect specification, the ACR claim identifies a set of rules the user must satisfy when authenticating to the OpenID Connect provider. For example, a chain or journey (tree) configured in ForgeRock Access Management (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, and acr-3, and only acr-2 and acr-3 are mapped, AM always chooses acr-2 to authenticate the end user.
To learn more about ACR Claims and AM, visit The Authentication Context Class Reference (acr) Claim.
The ForgeRock iOS, Android, and JS SDKs leverage the traditional authorization code flow with PKCE from the OAuth2 spec. When using centralized login to enable the client app to customize the flow, we use the 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 preconfigure this in the OAuth2 client, or on the fly from the client application.
Configuring AM
Verify or change settings in the OAuth2 provider
In part two of this guide, we set the OAuth2 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 Native console, navigate to Services .
- Select the OAuth2.0 provider.
- Navigate to the Advanced OpenID Connect tab.
- Confirm that Enable claims_parameter_supportedâ is set to ON.
- In OpenID Connect acr_values, and add a new entry: Auth Chain Mapping.
- Save the configuration.
Configure a new Journey
- In the Admin UI, click on Journeys .
- Click on +New journeyâ and name it âSimpleLoginâ.
- Use the editor to create a journey like the following:
In the next steps, we will configure the iOS, Android, and JS apps from Part 2 and Part 3 of this series to use the SimpleLogin instead of the default journey.
Configuring ACR values and the Javascript SDK
Configuring SPA to use the SimpleLogin journey
- Returning to the SPA created in Part 2 of the series, open the project in Visual Studio Code.
- Create a new constant:
- If using ForgeRock JavaScript SDK v2.2.0 or older, replace the SDK configuration with the following:const acr_values = âsimpleâ;
If you are using the ForgeRock JavaScript SDK v2.2.0 or older, 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,
});
- Note req.url.searchParams.append(âacr_valuesâ, acr_values); changes the searchParams query string.
- If you are using the latest version of the ForgeRock JS SDK, v 3.0 or newer, you can dynamically pass the 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 should expect to use the SimpleLogin tree for authentication.
Configuring ACR values and the iOS SDK
Configuring iOS to use the SimpleLogin journey
- Return to the iOS application created in Part 3 of this series, and 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 the .setCustomParam (key: âacr_valuesâ, value: âsimpleâ).
- When testing the application, you should expect to use the SimpleLogin journey for authentication.
Configuring ACR values and the Android SDK
Configuring Android to use the SimpleLogin journey
- Return to the Android application created in Part 3 of this series, 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);
System.out.println(e);
});
- Notice the additionalParameters.put(âacr_valuesâ, âsimpleâ).
- When testing the application, you should expect to use the SimpleLogin tree for authentication.
Whatâs next
Summary
In this article, 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.
Where to go from here
This concludes the four-part series. We hope you use the lessons of this guide to elevate the user experience of your apps using Forgerock Identity Cloud and the centralized UI.