Lokksmith

https://github.com/svenjacobs/lokksmith
Admin
A modern Kotlin Multiplatform library for implementing OpenID Connect Authorization Code Flow (with...
Tokens:4,427
Snippets:76
Trust Score:9.2
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install MkDocs Material and Plugins

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/README.md

Installs mkdocs-material with recommended extensions and the mkdocs-macros-plugin, including dependencies. This command is suitable for global installation or within a managed environment.

```bash
pipx install mkdocs-material[recommended] mkdocs-macros-plugin --include-deps
```

--------------------------------

### Install Project Dependencies and Git Hooks

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/contributing.md

Run this command in the project root to install Node.js dependencies and set up Git commit hooks for code style and commit message verification.

```bash
npm install
```

--------------------------------

### Get or Create Authentication Client

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/usage.md

Retrieve an existing client by its key using getOrCreate(), or create a new one if it doesn't exist. This function is suspending and requires a Coroutine scope.

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

--------------------------------

### Format Source Code with Spotless

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/contributing.md

Execute this Gradle task to automatically format the source code according to the project's defined rules.

```bash
./gradlew spotlessApply
```

--------------------------------

### Set Up Singleton Lokksmith Provider

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/usage.md

Ensure a singleton Lokksmith instance is available application-wide by setting it with SingletonLokksmithProvider. This is crucial for platform-specific response handling.

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

--------------------------------

### Launch Auth Flow in Compose Multiplatform

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/usage.md

Use AuthFlowLauncher within a Composable to initiate the authentication flow. Observe authFlowLauncher.result for process state updates.

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

LaunchedEffect(uiState.initiation) {
    uiState.initiation?.let {
        authFlowLauncher.launch(it)
    }
}
```

--------------------------------

### Add Lokksmith to Version Catalog

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/installation.md

Define Lokksmith versions and libraries in your `gradle/libs.versions.toml` file for streamlined dependency management.

```toml
[versions]
lokksmith = "{{ lokksmith_version }}"

[libraries]
lokksmith-core = { module = "dev.lokksmith:lokksmith-core", version.ref = "lokksmith" }
```

--------------------------------

### Prepare Authorization Code Flow

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/usage.md

Initiate the Authorization Code Flow by preparing the request. The redirectUri is a required parameter for the request.

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

val initiation = authFlow.prepare()
```

--------------------------------

### Configure Snapshot Repository

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/installation.md

Add Sonatype's snapshot repository to your Gradle configuration if you need to use snapshot versions of Lokksmith. This is typically done in `settings.gradle.kts` or `build.gradle.kts`.

```kotlin
maven {
    setUrl("https://central.sonatype.com/repository/maven-snapshots/")
    content {
        includeGroup("dev.lokksmith")
    }
}
```

--------------------------------

### Handle Authentication Response

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/usage.md

After opening the system browser with the initiation.requestUrl, pass the returned response to the auth flow to complete the process.

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

authFlow.onResponse(response)
```

--------------------------------

### Create Lokksmith Instance

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/usage.md

Obtain a Lokksmith instance using the platform-specific createLokksmith() function. An optional options argument can be used for customization.

```kotlin
val lokksmith = createLokksmith()
```

--------------------------------

### Launch Auth Flow on iOS (Kotlin Multiplatform)

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/usage.md

Launch an authentication flow from the iOS platform code of a Kotlin Multiplatform application using the lokksmith.launchAuthFlow() function.

```kotlin
lokksmith.launchAuthFlow(initiation)
```

--------------------------------

### Migrate Tokens from AppAuth

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/migration.md

This snippet demonstrates migrating tokens from AppAuth, using the access token's expiration for the refresh token's expiration and immediately performing a token refresh.

```kotlin
lokksmith.migration.setTokens(
    client = client,
    accessToken = appAuthState.accessToken!!,
    accessTokenExpiresAt = appAuthState.accessTokenExpirationTime,
    refreshToken = appAuthState.refreshToken,
    refreshTokenExpiresAt = appAuthState.accessTokenExpirationTime, // access token refresh
    idToken = appAuthState.idToken!!,
)

client.refresh() // perform token refresh
```

--------------------------------

### Set Tokens for Migration

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/migration.md

Use this snippet to set tokens for migration from another OIDC library. Replace placeholder values with actual tokens and expiration timestamps.

```kotlin
val lokksmith = createLokksmith()
val client = lokksmith.get("client-key")

// Replace values with actual tokens and expiration timestamps
// from other library.

lokksmith.migration.setTokens(
    client = client,
    accessToken = "ACCESS TOKEN",
    accessTokenExpiresAt = 1749471081,
    refreshToken = "REFRESH TOKEN",
    refreshTokenExpiresAt = 1752063081,
    idToken = "ID TOKEN",
)
```

--------------------------------

### Configure AndroidManifest.xml for App Links

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/installation.md

Manually update your `AndroidManifest.xml` to use App Links for secure OIDC redirects. Ensure the `android:scheme`, `android:host`, and `android:path` attributes match your redirect URI.

```xml
<activity
        android:name="dev.lokksmith.android.LokksmithRedirectActivity"
        android:exported="true">
    <intent-filter tools:node="removeAll" /> <!-- (1)! -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        
        <data 
            android:scheme="https"
            android:host="example.com"
            android:path="/redirect" /> <!-- (2)! -->
    </intent-filter>
</activity>
```

--------------------------------

### Specify Lokksmith Redirect Scheme for Android

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/installation.md

Configure your Android application's `build.gradle.kts` to specify the redirect scheme for Lokksmith's OAuth responses. Replace `my-app` with your custom scheme.

```kotlin
android {
    defaultConfig {
        addManifestPlaceholders(
            mapOf("lokksmithRedirectScheme" to "my-app") // (1)!
        )
    }
}
```

--------------------------------

### Add Lokksmith Compose Dependency

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/installation.md

Add the `lokksmith-compose` dependency to your source set in `build.gradle.kts` to integrate Lokksmith with Compose.

```kotlin
commonMain.dependencies {
    implementation(libs.lokksmith.compose)
}
```

--------------------------------

### Add Lokksmith Core Dependency

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/installation.md

Include the Lokksmith core library in your project's common main dependencies within your `build.gradle.kts` file.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.lokksmith.core)
        }
    }
}
```

--------------------------------

### Add Lokksmith Compose Artifact to Version Catalog

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/getting-started/installation.md

Define the `lokksmith-compose` artifact in your `gradle/libs.versions.toml` file when using Lokksmith with Jetpack Compose.

```toml
[libraries]
lokksmith-compose = { module = "dev.lokksmith:lokksmith-compose", version.ref = "lokksmith" }
```

--------------------------------

### Detect Motorola Devices

Source: https://github.com/svenjacobs/lokksmith/blob/main/site/docs/faq.md

Use this Kotlin code to identify if the current device is a Motorola device, which may have issues with Auth Tab authentication.

```kotlin
val isMotorolaDevice = Build.MANUFACTURER.lowercase() == "motorola"
```
Tokens:
Raw