Use centralized login
The following diagram shows a sample OAuth 2.0 flow that the ForgeRock SDK uses for your native app:
Note that the SDKs also support PKCE.
ForgeRock Android SDK apps
This section describes how to configure your ForgeRock Android SDK application to use centralized login
by leveraging the AppAuth
library:
-
Add the build dependency to the
build.gradle
file:implementation 'net.openid:appauth:0.7.1'
-
Configure the app to allow the
AppAuth
library to capture authorization redirects.Add the custom scheme your app will use to your
build.gradle
file:android.defaultConfig.manifestPlaceholders = [ 'appAuthRedirectScheme': 'com.forgerock.android' ]
-
When using a custom scheme, you can configure
AppAuth
to capture all redirects using this custom scheme through a manifest placeholder.-
Configure the redirect URI by adding an
<intent-filter>
forAppAuth.RedirectUriReceiverActivity
to yourAndroidManifest.xml
:<activity android:name="net.openid.appauth.RedirectUriReceiverActivity" tools:node="replace"> <intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:scheme="com.forgerock.android"/> </intent-filter> </activity>
-
Add the following to the
strings.xml
file:<string name="forgerock_oauth_redirect_uri" translatable="false">com.forgerock.android:/oauth2redirect</string>
-
In the Identity Cloud admin UI, update the Application Sign-in-URLs to match the value:
com.forgerock.android
For more information, refer to Capturing the authorization redirect.
-
-
For Android 11 or higher, add the following to the
AndroidManfest.xml
file:<queries> <intent> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="com.forgerock.android" /> </intent> </queries>
For more information, refer to Open URLs in a browser or other app.
-
Configure your application to use browser mode:
// Use FRUser.browser() to enable browser mode: FRUser.browser().login(context, new FRListener<FRUser>()); // Use standard SDK interface to retrieve an AccessToken: FRUser.getCurrentUser().getAccessToken() // Use standard SDK interface to logout a user: FRUser.getCurrentUser().logout()
The SDK uses the OAuth 2.0 parameters you configured in your application.
You can amend the example code above to customize the integration with AppAuth; for example, adding OAuth 2.0 or OpenID Connect parameters, and browser colors:
FRUser.browser().appAuthConfigurer() .authorizationRequest(r -> { // Add a login hint parameter about the user: r.setLoginHint("demo@example.com"); // Request that the user re-authenticates: r.setPrompt("login"); }) .customTabsIntent(t -> { // Customize the browser: t.setShowTitle(true); t.setToolbarColor(getResources().getColor(R.color.colorAccent)); }).done() .login(this, new FRListener<FRUser>() { @Override public void onSuccess(FRUser result) { //success } @Override public void onException(Exception e) { //fail } });
ForgeRock iOS SDK apps
This section describes how to configure your ForgeRock iOS SDK application to use centralized login:
-
If your application targets iOS 10 and earlier, configure a custom URL scheme:
-
In Xcode, in the Project Navigator, double-click your application to open the Project pane.
-
On the Info tab, in the URL Types panel, configure your custom URL scheme:
-
Add the custom URL scheme to the Redirection URIs property of your OAuth 2.0 client:
-
In your
AppDelegate.swift
file, call thevalidateBrowserLogin()
function:@UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { // Method invoked when the app is opened with Custom URL Scheme. // For example, a redirect from SFSafariViewController with an authorization code func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { // Parse and validate URL, extract authorization code, and continue the flow: Browser.validateBrowserLogin(url) } }
-
-
To enable centralized login, add code similar to the following to your app:
// BrowserBuilder let browserBuilder = FRUser.browser() browserBuilder.set(presentingViewController: self) browserBuilder.setCustomParam(key: "custom_key", value: "custom_val") // Browser let browser = browserBuilder.build() // Login browser.login{ (user, error) in if let error = error { // Handle error } else if let user = user { // Handle authenticated status } }
ForgeRock JavaScript SDK apps
This section describes how to configure your ForgeRok JavaScript SDK application with centralized login:
-
To initiate authentication by redirecting to the centralized login UI, add a
login
property that specifies how authentication happens in your app:const tokens = TokenManager.getTokens({ forceRenew: false, // Immediately return stored tokens, if they exist login: 'redirect' // Redirect to AM or the web app that handles authentication });
Supported values are as follows:
Setting Description redirect
Your app uses a redirect to ForgeRock® Access Management (AM), or another web application, to handle authentication.
embedded
Your app handles authentication natively, using SDK functionality.
If you do not specify a value,
embedded
is assumed, for backwards-compatibility. -
When the user is returned to your app, complete the OAuth 2.0 flow by passing in the
code
andstate
values that were returned.Use the
query
property to complete the flow:const tokens = TokenManager.getTokens({ query: { code: 'lFJQYdoQG1u7nUm8 ... ', // Authorization code from redirect URL state: 'MTY2NDkxNTQ2Nde3D ... ', // State from redirect URL }, });