Lightweight implementation of OpenID Connect/OAuth 2.0 supporting Authorization Code Grant Flow, discovery, PKCE, and simple JWT parsing. Includes Android, iOS, desktop support, and OkHttp/Ktor integration.
Kotlin Multiplatform Library for OpenId Connect / OAuth 2.0.
The library is designed for kotlin multiplatform, Android-only and iOS only Apps. For iOS only, use the OpenIdConnectClient Swift Package.
This is a lightweight implementation that does not provide any client-side validation of signatures.
Supported platforms:
Features:
You can find the full Api documentation here.
Library dependency versions:
Note that while the library may work with other kotlin/ktor versions, proceed at your own risk.
Add the dependency to your commonMain sourceSet (KMP) / Android dependencies (android only):
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)
Or, for your libs.versions.toml:
[versions]
oidc = "<version>"
[libraries]
oidc-appsupport = { module = "io.github.kalinjul.kotlin.multiplatform:oidc-appsupport", version.ref = "oidc" }
oidc-okhttp4 = { module = "io.github.kalinjul.kotlin.multiplatform:oidc-okhttp4", version.ref = "oidc" }
oidc-ktor = { module = "io.github.kalinjul.kotlin.multiplatform:oidc-ktor", version.ref = "oidc" }
If you want try a snapshot version, just add maven("https://central.sonatype.com/repository/maven-snapshots/") to your repositories.
There is currently no way to view available snapshots on sonatype central.
You will need some basic project setup to handle redirect urls and create an instance of the AuthFlowFactory:
Create an OpenIdConnectClient:
val client = OpenIdConnectClient(discoveryUri = "<discovery url>") {
endpoints {
tokenEndpoint = "<tokenEndpoint>"
authorizationEndpoint = "<authorizationEndpoint>"
userInfoEndpoint = null
endSessionEndpoint = "<endSessionEndpoint>"
}
clientId = "<clientId>"
clientSecret = "<clientSecret>"
scope = "openid profile"
codeChallengeMethod = CodeChallengeMethod.S256
redirectUri = "<redirectUri>"
postLogoutRedirectUri = "<postLogoutRedirectUri>"
}
If you provide a Discovery URI, you may skip the endpoint configuration and call discover() on the client to retrieve the endpoint configuration.
The Authorization Code Flow is implemented by CodeAuthFlow. You'll need platform specific variants (see Setup). Preferably, those instances should be provided using Dependency Injection. For more information, have a look at the KMP sample app.
Request tokens using code auth flow (this will open the browser for login):
val flow = authFlowFactory.createAuthFlow(client)
flow.startLogin()
val tokens = flow.continueLogin()
The login flow is split into startLogin and continueLogin.
The main reason is that on Android, the activity and/or process can easily get killed during login.
In order to mitigate this, call continueLogin() during your activity's onCreate():
authFlowFactory.registerActivity(this)
val flow = authFlowFactory.createAuthFlow(client)
if (flow.canContinueLogin()) {
val tokens = flow.continueLogin()
}
Perform refresh or endSession:
tokens.refresh_token?.let { client.refreshToken(refreshToken = it) }
tokens.id_token?.let { client.endSession(idToken = it) }
Since persisting tokens is a common task in OpenID Connect Authentication, we provide a TokenStore that uses a Multiplatform Settings Library to persist tokens in Keystore (iOS) / Encrypted Preferences (Android). If you use the TokenStore, you may also make use of TokenRefreshHandler for synchronized token refreshes.
tokenstore.saveTokens(tokens)
val accessToken = tokenstore.getAccessToken()
val refreshHandler = TokenRefreshHandler(tokenStore = tokenstore)
refreshHandler.refreshAndSaveToken(client, oldAccessToken = token) // thread-safe refresh and save new tokens to store
Android implementation is AndroidEncryptedPreferencesSettingsStore, for iOS use IosKeychainTokenStore.
You can use "oidc-ktor" dependency, which provides easy integration for ktor projects:
HttpClient(engine) {
install(Auth) {
oidcBearer(
tokenStore = tokenStore,
refreshHandler = refreshHandler,
client = client,
)
}
}
Because of the way ktor works, you need to tell the client if the token is invalidated outside of ktor's refresh logic, e.g. on logout:
ktorHttpClient.clearTokens()
For most calls (getAccessToken(), refreshToken(), endSession()), you may provide
additional configuration for the http call, like headers or parameters using the configure closure parameter:
client.endSession(idToken = idToken) {
headers.append("X-CUSTOM-HEADER", "value")
url.parameters.append("custom_parameter", "value")
}
val tokens = flow.getAccessToken(configureAuthUrl = {
// customize url that is passed to browser for authorization requests
parameters.append("prompt", "login")
}, configureTokenExchange = {
// customize token exchange http request
header("additionalHeaderField", "value")
})
If you have configured a postLogoutRedirectUri and want to perform a Logout using a Web Flow,
you can use the endSession flow:
val flow = authFlowFactory.createEndSessionFlow(client)
tokens.id_token?.let { flow.endSession(it) }
That way, browser cookies should be cleared so the next time a client wants to login, it get's prompted for username and password again.
We provide simple JWT parsing (without any validation):
val jwt = tokens.id_token?.let { Jwt.parse(it) }
println(jwt?.payload?.aud) // print audience
println(jwt?.payload?.iss) // print issuer
println(jwt?.payload?.additionalClaims?.get("email")) // get claim
val authenticator = OpenIdConnectAuthenticator {
getAccessToken { tokenStore.getAccessToken() }
refreshTokens { oldAccessToken -> refreshHandler.refreshAndSaveToken(client, oldAccessToken) }
onRefreshFailed {
// provided by app: user has to authenticate again
}
buildRequest {
header("AdditionalHeader", "value") // add custom header to all requests
}
}
val okHttpClient = OkHttpClient.Builder()
.authenticator(authenticator)
.build()
| State | Implementation |
|---|
| Android | Stable | Chrome Custom Tabs |
| iOS | Stable | ASWebAuthenticationSession |
| Desktop | Experimental | Embedded Webserver + Browser |
| WasmJS | Experimental | Popup Window communicating via postMessage() |
Jwt.parse()| kmp-oidc version | kotlin version | ktor version |
|---|
| <=0.11.1 | 1.9.23 | 2.3.7 |
| 0.11.2 | 2.0.20 | 2.3.7 |
| 0.12.+ | 2.0.20 | 3.0.+ |
| 0.13.+ | 2.1.20 | 3.1.+ |
| 0.14.0 - 0.15.+ | 2.1.21 | 3.2.+ |
| 0.16.+ | 2.2.20 | 3.3.+ |
Surfaced from shared tags and platforms — no rankings paid for.