Usage¶

The main entry point is the Lokksmith class, which manages and persists authentication clients and their state across your application. To obtain an instance, use the platform-specific createLokksmith() function. The function has an optional options argument for tweaking the behaviour of Lokksmith. Please read the source code documentation for details.

val lokksmith = createLokksmith()

Use getOrCreate() to retrieve an existing client by its unique key, or create a new one if it does not exist. This key is independent of the OAuth client ID, but you may use the same value if it suits your use case. Defining distinct keys allows you to manage multiple authentication clients within your application.

val client = lokksmith.getOrCreate("my-key") {
    id = "my-client-id"
    discoveryUrl = "https://example.com/.well-known/openid-configuration"
}

Once you have a client instance, it is time to call the Authorization Code Flow to obtain the tokens.

val authFlow = client.authorizationCodeFlow(
    AuthorizationCodeFlow.Request( // (1)!
        redirectUri = "my-app://openid-response"
    )
)

val initiation = authFlow.prepare()

1. See code documentation of AuthorizationCodeFlow.Request for more details.

The next step is to call the request URL from the Initiation object and pass the returned response to the auth flow.

// Open system browser with initiation.requestUrl, pass response to auth flow

authFlow.onResponse(response)

In a best case scenario the client is now authenticated and received the tokens.

You can now access the tokens through client.tokens, which is a Coroutine Flow, or client.runWithTokens().

Singleton¶

A singleton Lokksmith instance must be provided during application startup as soon as possible via SingletonLokksmithProvider. This provider ensures that platform-specific response handling, which is decoupled from the initiation of an auth flow and is launched by the system implicitly, is able to retrieve the Lokksmith instance. On Android this should be executed in the Application class, for example.

SingletonLokksmithProvider.set(
    lokksmith = createLokksmith(),
    coroutineScope = MainScope(),
)

Provider-specific token request parameters¶

Some providers require a vendor-specific parameter on requests to the token endpoint. Set additionalTokenRequestParameters on the client options to have it sent with both the authorization code exchange and every token refresh:

val client = lokksmith.getOrCreate(
    key = "my-key",
    options = Client.Options(
        additionalTokenRequestParameters = mapOf("httpStatusCodes" to "true"),
    ),
) {
    id = "my-client-id"
    discoveryUrl = "https://example.com/.well-known/openid-configuration"
}

From Swift, the same options are set on LokksmithClientOptions and passed where the client is obtained:

let options = LokksmithClientOptions()
options.additionalTokenRequestParameters = ["httpStatusCodes": "true"]

let client = try await lokksmith.getOrCreateClient(
    key: "main",
    configuration: .companion.discovery(
        clientId: "my-client-id",
        discoveryUrl: "https://example.com/.well-known/openid-configuration"
    ),
    options: options
)

Options are not persisted with the client, so pass the same options every time it is read back with client(key:options:).

The example above is SAP Customer Data Cloud, which answers token endpoint errors with HTTP 200 and an error body unless httpStatusCodes=true is sent. Without it, Lokksmith cannot tell an OAuth error such as invalid_grant apart from a malformed response — which is the difference between "the session is dead" and "retry later".

These parameters are constant for the lifetime of the client. Values that need to vary per request are not covered by this option.

Platform-specific configuration¶

Some request values legitimately differ per platform. The most common is the redirect URI: a multiplatform app often registers a different URI per platform — for example a verified App Link / Universal Link such as https://app.example.com/redirect on Android and iOS, but a same-origin URL like https://example.com/redirect on Web. On Desktop the redirect URI is ignored and replaced by the loopback URL, so its value does not matter there.

Keep your shared flow code identical by delegating the platform-dependent value to an expect/actual declaration:

expect val redirectUri: String

actual val redirectUri = "https://app.example.com/redirect"

actual val redirectUri = "https://example.com/redirect"

actual val redirectUri = "http://localhost/callback" // ignored; replaced by the loopback URL

Then build the request from shared code as usual:

val authFlow = client.authorizationCodeFlow(
    AuthorizationCodeFlow.Request(redirectUri = redirectUri)
)

Platform implementations¶

Calling the system browser and handling the authentication response on mobile platforms involves multiple steps, including managing process death and app recreation. To ensure a seamless user experience, it is essential to persist and restore authentication state as needed. Lokksmith provides platform-specific implementations that abstract these complexities, making it easier to integrate secure authentication flows in your application.

Compose Multiplatform¶

The AuthFlowLauncher shown here works on Android, iOS, Desktop and Web.

Once you receive the Initiation object, use AuthFlowLauncher to start the authentication flow from your Composable. For example:

val uiState by viewModel.uiState.collectAsStateWithLifecycle() // (1)!
val authFlowLauncher = rememberAuthFlowLauncher()

LaunchedEffect(uiState.initiation) {
    uiState.initiation?.let { initiation ->
        authFlowLauncher.launch(initiation)    
    }
}

1. data class UiState(val initiation: Initiation? = null)

You can either use authFlowLauncher.result to observe the current state of the process and update the user interface accordingly or use Client.authFlowResult(1) from your business logic (e.g. ViewModel) to pass the same result state to your UI state.

1. See AuthFlowResultProvider

iOS¶

To launch an authentication flow from the iOS platform code of a Kotlin Multiplatform application, use launchAuthFlow():

lokksmith.launchAuthFlow(initiation)

Native iOS apps¶

Native iOS apps written in Swift use the Lokksmith Swift package described in Installation. It exposes a Swift-facing API rather than the Kotlin one: suspending functions become async, and the browser flow, code exchange and token persistence happen in a single call.

Create one LokksmithManager for the lifetime of the app and share it:

import Lokksmith

let lokksmith = LokksmithManager()

let client = try await lokksmith.getOrCreateClient(
    key: "main",
    configuration: .companion.discovery(
        clientId: "my-client-id",
        discoveryUrl: "https://example.com/.well-known/openid-configuration"
    )
)

authorize presents an ASWebAuthenticationSession, exchanges the authorization code, validates the tokens and persists them. It returns nil when the user dismisses the browser:

let request = LokksmithAuthorizationRequest(redirectUri: "my-app://openid-response")
request.scopes = ["profile", "email"]
request.prompts = [.login] // optional, forces re-authentication

if let tokens = try await client.authorize(request: request) {
    print(tokens.accessToken.token)
}

Reading the current tokens does not suspend and never triggers a network request, which makes it suitable for answering "is the user signed in?" synchronously:

if client.isAuthenticated { … }
let subject = client.tokens?.idToken.subject

On the request path, use freshTokens(). It refreshes only when the access token or the ID token is expired or about to expire:

let accessToken = try await client.freshTokens().accessToken.token

To react to token changes, for example to mirror the access token somewhere, observe them and cancel the returned handle when you are done:

let observation = client.observeTokens { tokens in
    // Called on the main thread, starting with the current value.
}
// later
observation.cancel()

do {
    let tokens = try await client.freshTokens()
} catch let error as NSError {
    let failure = error.userInfo["KotlinException"] as? LokksmithFailure
    switch failure?.kind {
    case .oAuthRejection: try await client.resetTokens()
    case .transport:      break // keep the session, retry later
    default:              break
    }
}

Local sign-out is resetTokens(), which discards the persisted tokens but keeps the client and its provider configuration. endSession(request:) additionally runs the provider's RP-initiated logout flow, when one is advertised.

Desktop¶

On Desktop, Lokksmith implements the loopback redirect described in RFC 8252 ("OAuth 2.0 for Native Apps"). When you prepare an auth flow, Lokksmith starts a temporary HTTP server bound to 127.0.0.1 on an ephemeral port and uses http://127.0.0.1:<port>/callback as the redirect URI. The redirectUri you pass to AuthorizationCodeFlow.Request (or EndSessionFlow.Request) is therefore ignored and replaced by this loopback URL.

Use the Compose rememberAuthFlowLauncher() exactly as described under Compose Multiplatform. It opens the system browser, waits for the redirect on the loopback server, and completes the flow.

The Desktop behaviour can be customized via DesktopOptions when creating the instance:

val lokksmith = createLokksmith(
    dataDirectory = DataDirectory.Default("my-app"),
    desktop = DesktopOptions(
        redirectPath = "/callback",  // (1)!
        redirectTimeout = 5.minutes, // (2)!
        // browserLauncher, authorizationResponseHtml, endSessionResponseHtml, ...
    ),
)

1. Path of the loopback redirect URI.
2. How long to wait for the redirect before the flow times out.

Web¶

On the Web (Kotlin/Wasm in the browser) an auth flow is completed via a full-page redirect: the browser navigates to the OpenID provider and is redirected back to a same-origin URL, which reloads and restarts the whole application. The redirectUri you pass to AuthorizationCodeFlow.Request (or EndSessionFlow.Request) must therefore be a URL on your app's own origin, for example https://myapp.example/. Custom URI schemes do not work in the browser.

Because the redirect restarts the app, there is no in-memory state to resume from. Lokksmith reads the response from the current URL on startup for you: by default createLokksmith() completes a pending flow automatically (controlled by the handleRedirectOnStartup argument). The result is then observed through common code via Client.authFlowResult or client.tokens, exactly as on the other platforms.

Use the Compose rememberAuthFlowLauncher() exactly as described under Compose Multiplatform to start the flow. From non-Compose code you can launch it directly, which navigates the current document to the request URL:

lokksmith.launchAuthFlow(initiation)