Use centralized login

Applies to:

ForgeRock SDK for Android
ForgeRock SDK for iOS
ForgeRock SDK for JavaScript

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 OAuth 2.0 security with PKCE.

Set up centralized login in Android 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.11.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> for AppAuth.RedirectUriReceiverActivity to your AndroidManifest.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
         }
     });

Set up centralized login in iOS apps

This section describes how to configure your ForgeRock iOS SDK application to use centralized login:

Configure a custom URL type, for example frauth, so that users can be redirected to your application:

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 the validateBrowserLogin() 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
  }
}

Set up centralized login in JavaScript 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

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.

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 and state 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
  },
});

ForgeRock Developer Experience

Use centralized login

Set up centralized login in Android apps

Set up centralized login in iOS apps

Set up centralized login in JavaScript apps