OpenPass SDK for Android quickstart guide

This quickstart guide helps you integrate OpenPass directly with your Android-based mobile application. Follow these steps to install the SDK:

  1. Install the SDK.
  2. Initialize the OpenPass manager.
  3. Add the Sign In with OpenPass button using the web flow for mobile.

TIP: For debugging, enable additional logging.

The following sections detail each step.

Install the SDK

Create a build.gradle file and add the following code snippet, replacing LATEST_VERSION_NUMBER_PLACEHOLDER with the current version number.

dependencies {
    implementation("com.myopenpass.sdk:openpass-android-sdk:<LATEST_VERSION_NUMBER_PLACEHOLDER>")

    // Support for TV is optional.
    implementation("com.myopenpass.sdk:openpass-android-sdk-tv:<LATEST_VERSION_NUMBER_PLACEHOLDER>")
}

Initialize the OpenPass Manager


Initialize the OpenPass manager before using it in your application. You can do this using one of these options:

Provide access to Android context

When initializing your main application instance, provide access to an Android Context. When you initialize the OpenPassManager class using this option, there's no need to provide a custom implementation because it uses its own default network session. See the following code example.

class DevApplication : Application() {
   override fun onCreate() {
      super.onCreate()

      OpenPassManager.init(this)
   }
}

Use a custom network session

Configure the OpenPass manager with a custom network-session implementation to control network access. When you initialize the OpenPassManager class with a custom network session, you can wrap HTTP clients like OkHttp.

class DevApplication : Application() {
   override fun onCreate() {
      super.onCreate()

      OpenPassManager.init(this, OkNetworkSession())
   }
}

After initialization, you can access the OpenPass manager instance through the getInstance method, as shown in the following example:

OpenPassManager.getInstance()

Add sign-in button click handler

The sign-in process for mobile is a web-based flow that uses a custom Chrome tab to perform sign-in before redirecting the user to the application. This flow uses the Android Custom Tabs feature to launch the sign-in experience in a custom tab. After the user completes their sign-in, the web component redirects the user back to the application.

To set up the flow, do the following:

  1. Configure the web sign-in flow client.
  2. Configure the intent and redirect.
  3. Launch the web flow.
  4. Observe the results.
  5. Clean up the web flow.

Configure the web sign-in flow client

To configure the web sign-in flow client, do the following:

  1. Provide your OpenPass client identifier and initialized OpenPass manager. This creates your instance.
  2. As an option, pass in additional theming options using Android custom tabs.

The following is a code example with a custom theme.

client = WebSignInFlowClient(clientId, manager)
client?.let { client ->
   // Configure the web component to match the style of your app.
   client.toolbarColor = PRIMARY_COLOR
   client.secondaryToolbarColor = SECONDARY_COLOR
   client.navigationBarColor = BACKGROUND_COLOR
   client.navigationBarDividerColor = SECONDARY_COLOR
}

For details on theming, see What can I customize in a Custom Tab? in the Chrome for Developers Portal.

Configure the intent and redirect

Before launching the flow, configure the application by using a new intent that includes an OpenPass response to handle its results.

To do this, the following is required:

The redirect is defined in the AndroidManifest.xml file.
An intent filter is defined for an activity.
The associated activity is handling the new intent through onNewIntent.
The activity has access to the same WebSignInFlowClient instance that initiated the flow.

The redirect is defined through the <meta> tag specified in the AndroidManifest.xml file. It is extracted from the given Context and must match the redirect value your OpenPass client is configured to use. Here's an example:

<meta-data android:name="op_web_redirect" android:value="com.myopenpass.auth.b3044f3612f7cfdf237331d9d38d2477://openpass-android-redirect.com"/>

Here is an example of the intent filter:

<intent-filter>
   <data android:scheme="com.myopenpass.auth.b3044f3612f7cfdf237331d9d38d2477" android:host="openpass-android-redirect.com" />
   <action android:name="android.intent.action.VIEW" />
   <category android:name="android.intent.category.BROWSABLE" />
   <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

IMPORTANT: The metadata and intent filter must match. The SDK uses the metadata provided to know the URI (scheme and host) that it should launch to redirect back into the application. The intent filter is the application notifying Android what URIs it can handle. While OpenPass generates the scheme value, the organization configures the host when the client is registered, which will likely not match the host example provided here.

When handling a new intent, pass it into the web sign-in flow client:

override fun onPostCreate(savedInstanceState: Bundle?) {
   super.onPostCreate(savedInstanceState)
   handleIntent(intent)
}

override fun onNewIntent(intent: Intent) {
   super.onNewIntent(intent)
   handleIntent(intent)
}

open fun handleIntent(intent: Intent) {
   // A new intent has been delivered to the activity. Pass it into the OpenPass SDK to confirm whether it is the result of a previous authentication flow.
   client.checkSignIn(intent)
}

If the instance of the WebSignInFlowClient originally used to start the flow is tied to the activity, or the associated view model, you should set the android:launchMode activity to singleTop in the AndroidManifest.xml file. This ensures that only a single instance is created and the invoked onNewIntent method is the same as the one that started the flow.

Here is a code example with the launch mode set to singleTop:

<activity android:name="com.myopenpass.auth.dev.MobileActivity"
   android:launchMode="singleTop"
   android:exported="true">
...
</activity>

Launch the web flow

After configuring your web sign-in flow client, launch the web flow. The OpenPass manager will detect when a user is signed in.

NOTE: The flow will share token and error results, but you should obtain final OpenPass tokens directly from the OpenPass manager.

Both the OpenPass manager and web sign-in flow client provide support for Kotlin flows and listener interfaces. This allows support for both Kotlin and Java. Choose the option that best fits your application.

The following example launches the flow in Kotlin and shares token and error results.

client = WebSignInFlowClient(clientId, manager)
client?.let { client ->
   // ... Configure any theming

   // Launch the sign-in flow.
   client.launchSignIn(action.context)

   // Observe the results of the flow, handling them accordingly.
   client.state.collect { state ->
      when (state) {
          is WebSignInFlowState.Error -> _viewState.emit(ErrorState(state.error))
          is WebSignInFlowState.Complete -> {
             val tokens = manager.currentTokens
             if (tokens != null) {
                 // Tokens Available
                 _viewState.emit(SignedInState(tokens))
             } else {
                 // Tokens Not Available
                 _viewState.emit(SignedOutState)
             }
          }
         is WebSignInFlowState.Launched -> Unit
      }
   }
}

Observe the results

To detect when the user has authenticated and accessed the provided OpenPass tokens, observe the state reported by the OpenPass manager.

Here is a code example for observing the results.

// Observe the state of OpenPassManager and translate it into our own ViewState.
viewModelScope.launch {
    manager.state.collect { state ->
        Log.d(TAG, "State Update: $state")

        when (state) {
            is OpenPassManagerState.SignedOut -> _viewState.emit(SignedOutState)
            is OpenPassManagerState.SignedIn -> _viewState.emit(SignedInState(state.tokens))
            is OpenPassManagerState.Error -> { _viewState.emit(ErrorState(state.error)) }
        }
    }
}

Clean up the web flow

After you're finished with the web sign-in flow client, even if it's been successful, call close() on it to ensure resources are cleaned up.

Additional resources

For more information, see the following pages:

Developer Documentation:

External Resources: