Android (Kotlin)

Prefer a custom scheme for the callback

If the App Link host overlaps with the IdP, an unrelated deep link gets injected into the OAuth parser and produces missingCode. Use a custom scheme of the form <app>://oauth/1pass/callback for the callback. Diagnostics: https://api.1pass.dev/diagnose

Do not use EncryptedSharedPreferences

androidx.security:security-crypto 1.1.0+ is deprecated. Use DataStore + Tink.

Dependencies

// app/build.gradle.kts
dependencies {
    implementation("androidx.browser:browser:1.8.0")
    implementation("androidx.datastore:datastore-preferences:1.1.1")
    implementation("com.google.crypto.tink:tink-android:1.13.0")
    implementation("androidx.biometric:biometric:1.2.0-alpha05")
}

OAuth + PKCE

import android.content.Context
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent
import java.security.MessageDigest
import java.security.SecureRandom
import android.util.Base64
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.FormBody

class LogiOAuth(private val context: Context) {
    private val base = "https://api.1pass.dev"
    private val clientId = "logi_..."
    private val redirectUri = "com.example.myapp://callback"
    private val client = OkHttpClient()

    private fun base64UrlEncode(data: ByteArray): String =
        Base64.encodeToString(data, Base64.URL_SAFE or Base64.NO_PADDING or Base64.NO_WRAP)

    fun startSignIn(): Pair<String, String> {
        val verifier = ByteArray(32).also { SecureRandom().nextBytes(it) }
            .let { base64UrlEncode(it) }
        val challenge = base64UrlEncode(
            MessageDigest.getInstance("SHA-256").digest(verifier.toByteArray())
        )
        val state = base64UrlEncode(
            ByteArray(16).also { SecureRandom().nextBytes(it) }
        )

        val url = Uri.parse("$base/oauth/authorize").buildUpon()
            .appendQueryParameter("client_id", clientId)
            .appendQueryParameter("redirect_uri", redirectUri)
            .appendQueryParameter("response_type", "code")
            .appendQueryParameter("scope", "openid profile:basic email")
            .appendQueryParameter("state", state)
            .appendQueryParameter("code_challenge", challenge)
            .appendQueryParameter("code_challenge_method", "S256")
            .build()

        CustomTabsIntent.Builder().build().launchUrl(context, url)
        return verifier to state
    }

    suspend fun exchangeCode(code: String, verifier: String): TokenResponse {
        val body = FormBody.Builder()
            .add("grant_type", "authorization_code")
            .add("code", code)
            .add("redirect_uri", redirectUri)
            .add("code_verifier", verifier)
            .add("client_id", clientId)
            .build()

        val req = Request.Builder().url("$base/oauth/token").post(body).build()
        client.newCall(req).execute().use { resp ->
            return parseToken(resp.body!!.string())
        }
    }
}

data class TokenResponse(val accessToken: String, val refreshToken: String)

In onNewIntent, receive the redirect URI, verify state, then call exchangeCode.

App-to-app first-try (Intent setPackage)

If the logi app is installed, try it first; otherwise fall back to Custom Tabs:

fun launchAuthorize(context: Context, url: Uri) {
    val appIntent = android.content.Intent(android.content.Intent.ACTION_VIEW, url).apply {
        setPackage("dev.onepass.app")
        addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK)
    }
    try {
        context.startActivity(appIntent)
    } catch (_: android.content.ActivityNotFoundException) {
        CustomTabsIntent.Builder().build().launchUrl(context, url)
    }
}

Manifest configuration

<!-- AndroidManifest.xml -->
<activity android:name=".OAuthCallbackActivity" android:exported="true">
  <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" />
    <!-- Custom scheme callback -->
    <data android:scheme="com.example.myapp" android:host="callback" />
  </intent-filter>
</activity>

<application
    android:fullBackupContent="@xml/backup_rules"
    android:dataExtractionRules="@xml/data_extraction_rules">

App Links + assetlinks.json

If you also want to receive App Links, register the host with https:// and publish .well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.myapp",
    "sha256_cert_fingerprints": ["AA:BB:CC:..."]
  }
}]

Signing certificate SHA256:

keytool -list -v -keystore release.keystore -alias myalias | grep SHA256

Storing the Refresh Token (DataStore + Tink)

import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import com.google.crypto.tink.Aead
import com.google.crypto.tink.KeyTemplates
import com.google.crypto.tink.aead.AeadConfig
import com.google.crypto.tink.integration.android.AndroidKeysetManager
import android.util.Base64

private val Context.tokenStore by preferencesDataStore(name = "logi_tokens")

class LogiTokenStorage(private val context: Context) {
    private val refreshKey = stringPreferencesKey("refresh_token_encrypted")

    init { AeadConfig.register() }

    private val aead: Aead by lazy {
        AndroidKeysetManager.Builder()
            .withSharedPref(context, "logi_master_keyset", "logi_prefs")
            .withKeyTemplate(KeyTemplates.get("AES256_GCM"))
            .withMasterKeyUri("android-keystore://logi_master_key")
            .build()
            .keysetHandle
            .getPrimitive(Aead::class.java)
    }

    suspend fun saveRefreshToken(token: String) {
        val ciphertext = aead.encrypt(token.toByteArray(), null)
        val encoded = Base64.encodeToString(ciphertext, Base64.NO_WRAP)
        context.tokenStore.edit { it[refreshKey] = encoded }
    }

    suspend fun loadRefreshToken(): String? {
        val encoded = context.tokenStore.data
            .map { it[refreshKey] }
            .firstOrNull() ?: return null
        val ciphertext = Base64.decode(encoded, Base64.NO_WRAP)
        return String(aead.decrypt(ciphertext, null))
    }
}

Excluding from backup (required)

<!-- app/src/main/res/xml/backup_rules.xml -->
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
  <exclude domain="sharedpref" path="logi_master_keyset.xml" />
  <exclude domain="file" path="datastore/logi_tokens.preferences_pb" />
</full-backup-content>

Biometric protection (optional)

import android.security.keystore.KeyGenParameterSpec
import android.security.keystore.KeyProperties
import javax.crypto.KeyGenerator

fun generateBiometricProtectedKey(alias: String) {
    val spec = KeyGenParameterSpec.Builder(
        alias,
        KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
    )
        .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
        .setUserAuthenticationRequired(true)
        .setUserAuthenticationParameters(0, KeyProperties.AUTH_BIOMETRIC_STRONG)
        .setInvalidatedByBiometricEnrollment(true)
        .apply {
            try { setIsStrongBoxBacked(true) } catch (_: Exception) {}
        }
        .build()

    KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore")
        .apply { init(spec) }
        .generateKey()
}

Authenticate with BiometricPrompt, then use the cipher. For StrongBox, catch StrongBoxUnavailableException and fall back. When a new fingerprint is enrolled the key is invalidated → you need a re-login flow.

Device Bootstrap (device_secret)

1. On the first call, POST /api/v1/devices with {device_uuid, platform}, and the response includes device_secret once, along with a PAK.
2. On later calls, send {device_uuid, platform, device_secret} to the same endpoint to receive a new PAK. A missing or mismatched secret returns 401.

data class BootstrapResponse(
    val accessToken: String,
    val deviceSecret: String?
)

suspend fun handleBootstrap(resp: BootstrapResponse) {
    resp.deviceSecret?.let { storage.saveDeviceSecret(it) }
}

val secret = storage.loadDeviceSecret()  // if null, re-login via OAuth
val body = mapOf(
    "device_uuid" to uuid,
    "platform" to "android",
    "device_secret" to secret
)

Store it encrypted under a separate key:

private val deviceSecretKey = stringPreferencesKey("device_secret_encrypted")

suspend fun saveDeviceSecret(secret: String) {
    val ciphertext = aead.encrypt(secret.toByteArray(), null)
    context.tokenStore.edit {
        it[deviceSecretKey] = Base64.encodeToString(ciphertext, Base64.NO_WRAP)
    }
}

❌ Do not store it as plaintext in SharedPreferences.

Troubleshooting

• missingCode: App Link host conflict → switch to a custom scheme
• 401 on refresh: device_secret missing/mismatched → prompt an OAuth re-login
• Tokens invalid after a backup restore: backup_rules.xml missing
• StrongBox failure: catch StrongBoxUnavailableException → fall back to the regular Keystore
• App Link not working: check the assetlinks.json SHA256 fingerprint (release/debug are separate)

Checklist

• [ ] EncryptedSharedPreferences not used
• [ ] DataStore + Tink encrypted storage
• [ ] backup_rules.xml excludes tokens
• [ ] PKCE S256 (no plain)
• [ ] state generated and verified
• [ ] device_secret stored under a separate key
• [ ] Intent setPackage first-try → Custom Tabs fallback
• [ ] StrongBox fallback handled