Kotlin Multiplatform OIDC

The library uses CodeAuthFlow to implement the Authorization Code Grant Flow. You must obtain an authFlowFactory (platform-specific implementation) via Dependency Injection.

To start the login process (which opens the system browser) and retrieve tokens:

1. Call authFlowFactory.createAuthFlow(client).
2. Call flow.startLogin().
3. Call flow.continueLogin() to get the resulting tokens.

val flow = authFlowFactory.createAuthFlow(client)
flow.startLogin()
val tokens = flow.continueLogin()

To use this library in your iOS project, add the Swift package from the official repository. If you are using a Swift module, add the dependency to your Package.swift file using the exact version required.

dependencies: [
    .package(url: "https://github.com/kalinjul/OpenIdConnectClient.git", exact: "<version>")
],

Use the oidc-ktor dependency to install the OIDC authentication provider into your HttpClient. This automates token attachment and refreshing.

Note: Because of Ktor's internal caching, you must manually call ktorHttpClient.clearTokens() if a token is invalidated outside of Ktor's refresh logic (e.g., during a manual logout).

HttpClient(engine) {
    install(Auth) {
        oidcBearer(
            tokenStore = tokenStore,
            refreshHandler = refreshHandler,
            client = client,
        )
    }
}

// On logout:
ktorHttpClient.clearTokens()

To request access tokens, use the CodeAuthFlowFactory. You can specify whether to use an ephemeralBrowserSession (which uses ASWebAuthenticationSession). Use the factory to create an auth flow and call getAccessToken() to perform the exchange.

let factory = CodeAuthFlowFactory(ephemeralBrowserSession: false)
let flow = factory.createAuthFlow(client: client)
do {
    let tokens = try await flow.getAccessToken()
} catch {
    print(error)
}

On Android, the login process can be interrupted if the Activity or Process is killed. To handle this, you should register your activity and check if a login can be resumed during onCreate().

1. Call authFlowFactory.registerActivity(this) in your Activity.
2. Check flow.canContinueLogin().
3. If true, call flow.continueLogin() to resume the flow.

authFlowFactory.registerActivity(this)
val flow = authFlowFactory.createAuthFlow(client)
if (flow.canContinueLogin()) {
    val tokens = flow.continueLogin()
}

Because the redirect occurs in a new instance of your Wasm application, you must use your application's routing mechanism to detect the redirect path and trigger the authentication flow.

Define a specific subpath (e.g., /redirect) as your redirect URL. When the application detects this path in window.location.pathname, call PlatformCodeAuthFlow.handleRedirect() to complete the authentication process.

fun main() {
    CanvasBasedWindow(canvasElementId = "wasm-js-app") {
        val currentPath = window.location.pathname
        when {
            currentPath.isBlank() || currentPath == "/" -> {
                MainView()
            }
            currentPath.startsWith("/redirect") -> {
                LaunchedEffect(Unit) {
                    PlatformCodeAuthFlow.handleRedirect()
                }
            }
        }
    }
}

Wasm projects do not require declaring a redirect scheme; they must use https with subpaths of your application URL.

To initiate authentication in a wasmJs target, instantiate WasmCodeAuthFlowFactory. You can optionally pass window size parameters to the constructor.

When authentication starts, the app opens a new window for login. The redirect is handled by a new instance of your app opened within that login window. You must ensure that PlatformCodeAuthFlow.handleRedirect() is called only within this specific redirect instance.

val factory = WasmCodeAuthFlowFactory(/* window size parameters */)

Because authentication occurs in a web browser, the Android OS may terminate your application while it is in the background. To resume an interrupted authentication or logout process when the app restarts, use the following patterns:

Resume Login

Check if a login is in progress using authFlow.canContinueLogin() and then call authFlow.continueLogin().

Resume Logout

Check if a logout is in progress using endSessionFlow.canContinueLogout() and then call endSessionFlow.continueLogout().

// Resume Login
if (authFlow.canContinueLogin()) {
    val tokens = authFlow.continueLogin(configureTokenExchange = null)
    // save tokens
}

// Resume Logout
if (endSessionFlow.canContinueLogout()) {
    endSessionFlow.continueLogout()
    // clear tokens
}

Add the core library and optional integration modules to your commonMain sourceSet (for KMP) or Android dependencies.

• oidc-appsupport: Core library.
• oidc-ktor: Optional Ktor integration (experimental).
• oidc-okhttp4: Optional OkHttp integration for Android (experimental).

implementation("io.github.kalinjul.kotlin.multiplatform:oidc-appsupport:<version>")
implementation("io.github.kalinjul.kotlin.multiplatform:oidc-ktor:<version>") // optional ktor support
implementation("io.github.kalinjul.kotlin.multiplatform:oidc-okhttp4:<version>") // optional okhttp support (android only)