Integrate With Okta

This guide describes how to configure Okta to delegate to Beyond Identity for authentication during an OAuth2 authorization flow.

Prerequisites

• Integrate With Okta
• Kotlin SDK

Before calling EmbeddedSdk.authenticate(), we must Authorize With Okta.

Authorize With Okta

• Step 1: Configuring the Authenticator Config

Make sure the Authentication 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: Okta Authorize URL

To start the authorization flow, launch a WebView, and load the Oauth2 Authorization Request URL provided by Okta.

val webView = WebView(activity)
...
webView.loadUrl(OKTA_URL)

• Step 3: Invoke URL

Create a WebViewClient and override shouldOverrideUrlLoading. A URL with the Invoke URL scheme should be returned from Okta. When the webpage loads the URL, call EmbeddedSdk.authenticate(). You can confirm the validity of the URL with EmbeddedSdk.isAuthenticateUrl().

webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView?,
        request: WebResourceRequest?,
    ): Boolean {
        request?.url?.let { invokeUrl ->
            if (EmbeddedSdk.isAuthenticateUrl(invokeUrl.toString())) {
                EmbeddedSdk.authenticate(
                    invokeUrl.toString(),
                    ...
                ) {
                    ...
                }
                return true
            }
        }
        return super.shouldOverrideUrlLoading(view, request)
    }
}

• Step 4: Redirect URL

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

EmbeddedSdk.authenticate(
    invokeUrl.toString(),
    object : ((List<Credential>, (String?) -> Unit) -> Unit) {
        override fun invoke(p1: List<Credential>, p2: (String?) -> Unit) {}
    }
) { result ->
    result.onSuccess { authenticateResponse ->
        authenticateResponse.redirectUrl?.let { redirectUrl ->
            val webView = WebView(activity)

            webView.webViewClient = object : WebViewClient() {
                override fun shouldOverrideUrlLoading(
                    view: WebView?,
                    request: WebResourceRequest?,
                ): Boolean {
                    request?.url?.scheme?.let { scheme ->
                        if (scheme == CALLBACK_URL_SCHEME) {
                            // This URL contains authorization code and state parameters
                            // Exchange the authorization code for an id_token using Okta's token endpoint.
                            return true
                        }
                    }
                    return super.shouldOverrideUrlLoading(view, request)
                }
            }

            webView.loadUrl(redirectUrl)
        }
    }
}

Full Example

val webView = WebView(activity)

webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView?,
        request: WebResourceRequest?,
    ): Boolean {
        request?.url?.let { invokeUrl ->
            if (EmbeddedSdk.isAuthenticateUrl(invokeUrl.toString())) {
                EmbeddedSdk.authenticate(
                    invokeUrl.toString(),
                    object : ((List<Credential>, (String?) -> Unit) -> Unit) {
                        override fun invoke(p1: List<Credential>, p2: (String?) -> Unit) {}
                    }
                ) { result ->
                    result.onSuccess { authenticateResponse ->
                        authenticateResponse.redirectUrl?.let { redirectUrl ->
                            val newWebView = WebView(activity)
                
                            newWebView.webViewClient = object : WebViewClient() {
                                override fun shouldOverrideUrlLoading(
                                    view: WebView?,
                                    request: WebResourceRequest?,
                                ): Boolean {
                                    request?.url?.scheme?.let { scheme ->
                                        if (scheme == CALLBACK_URL_SCHEME) {
                                            // This URL contains authorization code and state parameters
                                            // Exchange the authorization code for an id_token using Okta's token endpoint.
                                            return true
                                        }
                                    }
                                    return super.shouldOverrideUrlLoading(view, request)
                                }
                            }
                
                            newWebView.loadUrl(redirectUrl)
                        }
                    }
                }
                return true
            }
        }
        return super.shouldOverrideUrlLoading(view, request)
    }
}

webView.loadUrl(OKTA_URL)