sdk/android

SDK Kotlin pour Android utilisant Chrome Custom Tabs, le flux de coded'autorisation PKCE S256 et le stockage des jetons viaEncryptedSharedPreferences reposant sur Keystore.

Statut

L’état du package est Implémenté et vérifié localement. La suite de tests unitaires JVM réussit et couvre PKCE, la gestion de l’état et du nonce, la capacité invité et les contrats de stockage. EncryptedSharedPreferences, Chrome Custom Tabs, App Links et un aller-retour réel avec un IdP nécessitent encore un appareil ou un émulateur. Cette page documente le comportement implémenté; elle ne constitue pas une déclaration d’aptitude à la production.

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

Prérequis

Android API 26+ (Android 8.0)
Kotlin 1.9+ et AndroidX

Installation

Ajoutez la dépendance au fichier build.gradle.kts de votre moduled’application :

// settings.gradle.kts
includeBuild("../xid/sdk/android")

// app/build.gradle.kts
dependencies {
    implementation("dev.xid:xid-android:0.1.0-alpha.0")
}

Configuration du manifeste

Enregistrez une Activity de callback avec un intent-filter. Les App Links(schéma HTTPS avec autoVerify) sont recommandés par rapport aux schémaspersonnalisés :

<!-- AndroidManifest.xml -->
<activity android:name=".AuthCallbackActivity" 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" />
        <data android:scheme="https"
              android:host="yourapp.example.com"
              android:pathPrefix="/auth/callback" />
    </intent-filter>
</activity>

Démarrage rapide

import dev.xid.sdk.Xid
import dev.xid.sdk.model.XidConfig

// 1. Initialize in Application.onCreate. offline_access is rejected until DPoP is implemented.
Xid.configure(
    context = this,
    config = XidConfig(
        issuer = "https://xid.dev",
        clientId = "your_client_id",
        redirectUri = "https://yourapp.example.com/auth/callback",
        scopes = listOf("openid", "profile", "email"),
    )
)

// 2. Sign in (opens Chrome Custom Tabs)
lifecycleScope.launch { Xid.signIn(requireContext()) }

// 3. Handle redirect in AuthCallbackActivity
val session = Xid.handleRedirect(intent.data.toString())

// 4. Read the current unexpired session. Expiry requires reauthorization.
val session = Xid.getSession()

// 5. Get the current unexpired access token.
val token = Xid.getAccessToken()

// 6. Clear local state and optionally open end_session.
Xid.signOut(context = this, openEndSession = true)

API principale

Méthode	Signature
`configure`	`fun configure(context: Context, config: XidConfig)`
`signIn`	`suspend fun signIn(context: Context, options: SignInOptions? = null)`
`handleRedirect`	`suspend fun handleRedirect(url: String): XidSession`
`getSession`	`suspend fun getSession(): XidSession?`
`getAccessToken`	`suspend fun getAccessToken(options: GetAccessTokenOptions? = null): String`
`signOut`	`suspend fun signOut(context: Context? = null, openEndSession: Boolean = false)`
`setTokenStorage`	`fun setTokenStorage(adapter: TokenStorageAdapter)`

Types d’erreur

Toutes les erreurs SDK sont des sous-types de la classe scelléeXidException :

Sous-classe	Déclencheur
`NotConfigured`	configure() n’a pas été appelé
`UserCancelled`	L’utilisateur a fermé les Custom Tabs sans terminer
`StateMismatch`	Incohérence d’état OAuth — possible CSRF
`TokenExchangeFailed`	Le point de terminaison de jeton a renvoyé une erreur
`TokenValidationFailed`	La validation de la signature ou des claims du jeton d’identité a échoué
`NoSession`	Méthode de session appelée hors connexion

Sécurité

Client public — aucun secret client stocké ni transmis.
PKCE S256 uniquement. Le serveur rejette la méthode plain challenge.
EncryptedSharedPreferences reposant sur Android Keystore (AES-256-GCM)protège le stockage des jetons au repos.
État OAuth aléatoire généré par requête ; validé lors de la redirectionpour prévenir le CSRF.

Limites connues

La verification du jeton ID par JWKS est implementee et testee localement. Les validations appareil ou emulateur Android et IdP reel restent requises avant L4.
Aucun mécanisme pour détecter quand l’utilisateur ferme Custom Tabs sansterminer l’autorisation.
Compte unique uniquement — la couche de stockage utilise des clés fixes.