Skip to main content
Version: v1

Integrate With Beyond Identity

This guide describes how to use Beyond Identity for authentication during an OAuth2 authorization flow.

Prerequisites

Before calling EmbeddedSdk.authenticate(), we must authorize using Beyond Identity.

Authorize With Beyond Identity

Using the Web

The library follows the best practices set out in RFC 8252 - OAuth 2.0 for Native Apps, including using Custom Tabs for authorization requests. For this reason, WebView is explicitly not supported due to usability and security reasons.

  • Step 1: Configuring the Authenticator Config

Make sure the Authenticator Config in the Beyond Identity Console is set to type Embedded and that the Invoke URL points to your application with either an App Scheme or a Universal Link.

  • Step 2: Beyond Identity Authorize URL

To start the authorization flow, build a CustomTabsIntent, and launch the OAuth2 Authorization Request URL you built in the pre-requisite step.

val builder = CustomTabsIntent.Builder()
...
builder.build().launchUrl(context, BI_AUTH_URL)
  • Step 3: Invoke URL

A URL with the Invoke URL scheme should be triggered by the web page. The Android OS will look for an appropraite Activity to handle the Intent. In your Activity, which handles your Beyond Identity scheme, override onCreate &/ onNewIntent, and call EmbeddedSdk.authenticate(). You can confirm the validity of the URL with EmbeddedSdk.isAuthenticateUrl().

intent?.data?.let { uri ->
when {
EmbeddedSdk.isAuthenticateUrl(uri.toString()) -> {
EmbeddedSdk.authenticate(
url = uri.toString(),
credentialId = selectedCredentialId,
) {
...
}
}
...
}
}
  • Step 4: Redirect URL

To complete the authorization flow, build another CustomTabsIntent, and launch the redirectUrl returned from a successful AuthenticateResponse. The authorization code and state parameter are attached to this URL.

intent?.data?.let { uri ->
when {
EmbeddedSdk.isAuthenticateUrl(uri.toString()) -> {
EmbeddedSdk.authenticate(
url = uri.toString(),
credentialId = selectedCredentialId,
) { result ->
result.onSuccess { authenticateResponse ->
authenticateResponse.redirectUrl?.let { redirectUrl ->
CustomTabsIntent.Builder().build().launchUrl(context, Uri.parse(redirectUrl))
}
}
}
}
uri.scheme == CALLBACK_URL_SCHEME -> {
// This URL contains authorization code and state parameters
// Exchange the authorization code for an id_token using Beyond Identity's token endpoint.
}
...
}
}

Full Example

private fun launchBI(context: Context, url: Uri = BI_AUTH_URL) {
CustomTabsIntent.Builder().build().launchUrl(context, url)
}

private fun handleIntent(context: Context, intent: Intent?) {
selectCredentialId { selectedCredentialId ->
intent?.data?.let { uri ->
when {
EmbeddedSdk.isAuthenticateUrl(uri.toString()) -> {
EmbeddedSdk.authenticate(
url = uri.toString(),
credentialId = selectedCredentialId,
) { result ->
result.onSuccess { authenticateResponse ->
authenticateResponse.redirectUrl?.let { redirectUrl ->
CustomTabsIntent.Builder().build().launchUrl(context, Uri.parse(redirectUrl))
}
}
}
}
uri.scheme == CALLBACK_URL_SCHEME -> {
// This URL contains authorization code and state parameters
// Exchange the authorization code for an id_token using Beyond Identity's token endpoint.
}
}
}
}
}

private fun selectCredentialId(callback: (String) -> Unit) {
// Where you can perform some logic here to select a credential, or
// present UI to a user to enable them to select a credential.
}