OpenID Connect Authentication

Authentication follows the Authorization Code Flow with PKCE — the recommended flow for mobile apps, as defined in RFC 6749 and RFC 7636. For a detailed protocol reference, see the OpenID Connect Core 1.0 spec.

At a high level, the flow has three steps:

1. Authorization Request The app opens a secure system browser and redirects the user to the Identity Provider (e.g. Keycloak). A PKCE code_challenge is included so the token exchange can later be verified.

2. Callback After the user authenticates, the Identity Provider redirects back to the app via a custom URI scheme or App/Universal Link, carrying a short-lived authorization_code.

3. Token Request The app exchanges the authorization_code — together with the PKCE code_verifier — for an access_token, id_token, and optionally a refresh_token.

Since mobile apps are public clients (no client_secret), PKCE is mandatory.

---

Implementation

The recommended library for both platforms is AppAuth, a certified OpenID Connect implementation maintained by the OpenID Foundation:

Platform	Library	Minimum OS
iOS / macOS	openid/AppAuth-iOS	iOS 12+
Android	openid/AppAuth-Android	API 16+

AppAuth handles PKCE, endpoint discovery, and the secure browser session automatically:

• iOS uses ASWebAuthenticationSession under the hood

• Android uses Chrome Custom Tabs

---

iOS (AppAuth-iOS)

Installation

Swift Package Manager:

https://github.com/openid/AppAuth-iOS

CocoaPods:

pod 'AppAuth'

Redirect URI — Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.example.app</string>
    </array>
  </dict>
</array>

Login

import AppAuth

class AuthManager {

    // Retain the session to keep ASWebAuthenticationSession alive
    var currentAuthFlow: OIDExternalUserAgentSession?

    func login(presenting viewController: UIViewController) {
        // Get the Authentication URL from the SDK
        guard let openIDBaseUrl = URL(string:kapeSDK?.manager.getConfiguration().domains().getOpenidApiDomain() ?? "") else { return }

        // 1. Discover AS endpoints
        OIDAuthorizationService.discoverConfiguration(forIssuer: openIDBaseUrl) { configuration, error in
            guard let configuration else {
                print("Discovery failed: \(error!)")
                return
            }

            // 2. Build authorization request — PKCE is handled automatically
            let request = OIDAuthorizationRequest(
                configuration: configuration,
                clientId: "my-mobile-app",
                // use offline_access to request long-living Refresh. Tokens
                scopes: [OIDScopeOpenID, OIDScopeProfile, OIDScopeEmail, "offline_access"],
                redirectURL: URL(string: "com.example.app:/callback")!,
                responseType: OIDResponseTypeCode,
                additionalParameters: nil
            )

            // 3. Open ASWebAuthenticationSession and exchange code for tokens
            self.currentAuthFlow = OIDAuthState.authState(
                byPresenting: request,
                presenting: viewController
            ) { authState, error in
                guard let authState else {
                    print("Auth failed: \(error!)")
                    return
                }
                print("Access token: \(authState.lastTokenResponse?.accessToken ?? "-")")
                print("ID token:     \(authState.lastTokenResponse?.idToken ?? "-")")
                // Authenticate SDK
                let credentials = AuthCredentials(accessToken: authState.lastTokenResponse?.accessToken ?? "", refreshToken:authState.lastTokenResponse?.refreshToken ?? "", idToken: authState.lastTokenResponse?.idToken ?? "")
                try kapeSDK!.manager.identity().openidAuthenticateWithAuthCredentials(authCredentials: credentials)
            }
        }
    }
}

Hold a strong reference to currentAuthFlow for the duration of the session. Releasing it cancels the ASWebAuthenticationSession.

---

Android (AppAuth-Android)

Installation

build.gradle:

dependencies {
    implementation "net.openid:appauth:0.11.1"
}

Redirect URI — AndroidManifest.xml

<activity android:name="net.openid.appauth.RedirectUriReceiverActivity"
          android:exported="true">
    <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.example.app" />
    </intent-filter>
</activity>

Login

import net.openid.appauth.*

class LoginActivity : AppCompatActivity() {

    private lateinit var authService: AuthorizationService
    private val RC_AUTH = 100

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        authService = AuthorizationService(this)

        val issuer = Uri.parse(kapeSDK?.manager?.getConfiguration()?.domains()?.getOpenidApiDomain() ?: return)

        // 1. Discover AS endpoints
        AuthorizationServiceConfiguration.fetchFromIssuer(issuer) { configuration, error ->
            if (configuration == null) {
                Log.e("OIDC", "Discovery failed: $error")
                return@fetchFromIssuer
            }

            // 2. Build authorization request — PKCE is handled automatically
            val request = AuthorizationRequest.Builder(
                configuration,
                "my-mobile-app",
                ResponseTypeValues.CODE,
                Uri.parse("com.example.app:/callback")
            )
                .setScopes("openid", "profile", "email", "offline_access")
                .build()

            // 3. Open Chrome Custom Tab
            val intent = authService.getAuthorizationRequestIntent(request)
            startActivityForResult(intent, RC_AUTH)
        }
    }

    // 4. Receive the authorization code callback
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        if (requestCode != RC_AUTH || data == null) return

        val response = AuthorizationResponse.fromIntent(data)
        val error = AuthorizationException.fromIntent(data)

        if (response == null) {
            Log.e("OIDC", "Authorization failed: $error")
            return
        }

        // 5. Exchange code for tokens
        authService.performTokenRequest(response.createTokenExchangeRequest()) { tokenResponse, ex ->
            if (tokenResponse != null) {
                Log.d("OIDC", "Access token: ${tokenResponse.accessToken}")
                Log.d("OIDC", "ID token:     ${tokenResponse.idToken}")
                val credentials = AuthCredentials(
                    accessToken = tokenResponse.accessToken ?: "",
                    refreshToken = tokenResponse.refreshToken ?: "",
                    idToken = tokenResponse.idToken ?: ""
                )
                kapeSDK?.manager?.identity()?.openidAuthenticateWithAuthCredentials(authCredentials = credentials)
            } else {
                Log.e("OIDC", "Token exchange failed: $ex")
            }
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        authService.dispose()
    }
}

Terminating an OpenID SSO Session

The authentication request will usually initiate an SSO Session, which will ensure, that other apps using the same authorization URL can use the session to automatically login the user. If you want to terminate such a session, preventing other apps from getting automatically logged in, you need to create an EndSessionRequest instead of AuthorizationRequest providing the ID Token which you can fetch from the SDK with fetchTokenTypeType .

Legacy XV Token Exchange

Apps can convert their Legacy XV Tokens into OpenID credentials by generating a "magic link." This link functions like a standard authentication link. However, you must create custom AuthorizationRequest for AppAuth, to use this custom URL and to skip the nonce validation.

Swift

public func authorize_openid_with_legacy_xv_access_token(token: String, completion: @escaping () -> Void) {
    guard let issuerURL = URL(string: kapeSDK?.manager.getConfiguration().domains().getOpenidApiDomain() ?? "") else {
        completion()
        return
    }

    execute_sdk_operation {
        let magicLinkString = try kapeSDK!.manager.identity().openidGenerateMagicLoginLinkFromXvAuth(xvAccessToken: token)
        guard let magicLink = URL(string: magicLinkString) else {
            completion()
            return
        }

        OIDAuthorizationService.discoverConfiguration(forIssuer: issuerURL) { config, error in
            guard let config else {
                print("Magic link flow — discovery error: \(error?.localizedDescription ?? "unknown")")
                completion()
                return
            }

            // Build a synthetic OIDAuthorizationRequest. state is set to an empty string so
            // AppAuth skips state validation in the callback — the magic link flow does not
            // produce a state. nonce is omitted entirely; OIDAuthorizationService.present only
            // returns the authorization code and does not validate the ID token nonce. The token
            // exchange via OIDAuthorizationService.perform(tokenRequest:) also skips nonce
            // validation, which avoids a mismatch since the magic link ID token has no nonce.
            // The MagicLinkUserAgent opens the pre-built magic link URL directly, so AppAuth's
            // constructed URL is never used.
            let request = OIDAuthorizationRequest(
                configuration: config,
                clientId: CLIENT_ID,
                clientSecret: nil,
                scope: "\(OIDScopeOpenID) \(OIDScopeProfile) \(OIDScopeEmail) offline_access",
                redirectURL: URL(string: CALLBACK_SCHEME + CALLBACK_PATH_AUTH)!,
                responseType: OIDResponseTypeCode,
                state: "",           // empty → AppAuth skips state validation in callback
                nonce: nil,          // nil → no nonce generated, no nonce validated
                codeVerifier: nil,
                codeChallenge: nil,
                codeChallengeMethod: nil,
                additionalParameters: nil
            )

            // OIDAuthorizationService.present handles URL presentation + callback interception.
            // It does NOT perform a token exchange, so no ID token nonce validation happens here.
            currentAuthorizationFlow = OIDAuthorizationService.present(
                request,
                externalUserAgent: MagicLinkUserAgent(magicLink: magicLink)
            ) { authorizationResponse, error in
                guard let authorizationResponse, let code = authorizationResponse.authorizationCode else {
                    print("Magic link flow error: \(error?.localizedDescription ?? "unknown")")
                    completion()
                    return
                }

                // Exchange the authorization code for tokens. OIDAuthorizationService.perform
                // without an authorizationResponse argument skips ID token nonce validation.
                let tokenRequest = OIDTokenRequest(
                    configuration: config,
                    grantType: OIDGrantTypeAuthorizationCode,
                    authorizationCode: code,
                    redirectURL: URL(string: CALLBACK_SCHEME + CALLBACK_PATH_AUTH)!,
                    clientID: CLIENT_ID,
                    clientSecret: nil,
                    scopes: nil,
                    refreshToken: nil,
                    codeVerifier: nil,
                    additionalParameters: nil
                )

                OIDAuthorizationService.perform(tokenRequest) { tokenResponse, error in
                    guard let tokenResponse, let accessToken = tokenResponse.accessToken else {
                        print("Magic link token exchange error: \(error?.localizedDescription ?? "unknown")")
                        completion()
                        return
                    }

                    execute_sdk_operation {
                        let credentials = AuthCredentials(
                            accessToken: accessToken,
                            refreshToken: tokenResponse.refreshToken ?? "",
                            idToken: tokenResponse.idToken ?? ""
                        )
                        try kapeSDK!.manager.identity().openidAuthenticateWithAuthCredentials(authCredentials: credentials)

                        let acrLevel = try kapeSDK!.manager.identity().getOpenidAcrValue() ?? 0
                        print("Token acr level: \(acrLevel)")
                        
                        //In this example we require Level 2, so we might need to perform another authorization to step up
                        if acrLevel < 2 {
                            print("acr=\(acrLevel), step-up required — opening standard OIDC flow")
                            authorize_openid(completion: completion)
                        } else {
                            completion()
                        }
                    }
                }
            }
        }
    }
}