KMPAuth Documentation

KMPAuth 3.0 introduces a new pattern replacing the 2.x *UiContainer composables with rememberXxxAuthState (for session management) and rememberXxxSignInState (for credential retrieval).

Key Benefits

• Backend Agnostic: rememberXxxAuthState works with any registered backend (Firebase, Supabase, etc.) without changing your UI code.
• Common Code Support: These states live in commonMain and are compatible with all targets, including Wasm.
• Detailed Errors: Results are returned as Result<KMPAuthUser>, where a failure contains the specific reason instead of a null user.

Mapping 2.x to 3.0

Implementation Example

// 3.0 pattern
val googleSignIn = rememberGoogleAuthState(onResult = { result: Result<KMPAuthUser> ->
    result.onSuccess {
        val name = it.displayName
        // Access raw FirebaseUser if needed via escape hatch:
        val nativeUser = it.raw as? dev.gitlive.firebase.auth.FirebaseUser
    }
})

GoogleSignInButton { googleSignIn.launch() }

// 3.0
val googleSignIn = rememberGoogleAuthState(onResult = { result: Result<KMPAuthUser> ->
    val name = result.getOrNull()?.displayName // uid, email, displayName, photoUrl, providerId
    val nativeUser = result.getOrNull()?.raw as? dev.gitlive.firebase.auth.FirebaseUser // escape hatch
})
GoogleSignInButton { googleSignIn.launch() }

The behavior of OAuth flows depends on your chosen backend (Firebase or Supabase) and the target platform.

Firebase Backend

Prerequisite: Enable the provider in the Firebase console.

• Android / iOS: Uses the Firebase SDK's native web-flow UI.
• Desktop (JVM): Opens the system browser to a local page running Firebase's official JS SDK against your project's hosted auth handler. Supports all console-configured providers (including Apple).
• Web (JS/wasm): Not yet implemented; will return a failed Result.

Supabase Backend

Prerequisite: Enable the provider in the Supabase dashboard. The provider parameter accepts GoTrue names like github, azure, gitlab, or discord.

• Desktop (JVM): Works out of the box; supabase-kt handles the redirect via its own localhost callback server.
• Android / iOS: Uses supabase-kt's standard deep-link setup.
• Web (JS/wasm): Uses a full-page redirect; the session is restored after the page reloads.

The *UiContainer pattern (e.g., GoogleButtonUiContainerFirebase) is deprecated in 3.0. The recommended approach is to use rememberXxxAuthState or rememberXxxSignInState composables. This gives you full control over the UI button while managing the authentication lifecycle.

Key benefits:

• SignInState.isInProgress can be used to drive loading spinners or disable buttons.
• launch() is safe to call multiple times (subsequent calls are ignored if a flow is active).
• Parameters are read at launch time, allowing for dynamic configuration (like toggling linkAccount) without recreating the state.

Note on Callbacks: Session callbacks now return Result<KMPAuthUser> instead of Result<FirebaseUser?>.

// 3.0 Recommended Pattern:
val googleSignIn = rememberGoogleAuthState(
    linkAccount = false,
    onResult = onFirebaseResult,
)

// You can now use any custom button or UI component
GoogleSignInButton(onClick = { googleSignIn.launch() })

KMPAuth provides two distinct layers of composable states for handling authentication in Compose, depending on whether you need a full session or just raw credentials.

1. Credential only layer: Uses rememberXxxSignInState (e.g., rememberGoogleSignInState). This returns a Result<T> containing the raw provider user (e.g., GoogleUser). Use this when you do not have a backend and intend to handle the token/credential yourself.
2. Session layer: Uses rememberXxxAuthState (e.g., rememberGoogleAuthState). This returns a Result<KMPAuthUser>. Use this when you have a registered backend (like Firebase or Supabase) that exchanges the credential for a managed session.

Both layers return a SignInState which provides:

• launch(): To start the authentication flow.
• isInProgress: An observable boolean to drive loading UI and prevent double-taps.

Key behaviors:

• Parameters (like linkAccount) are read at launch time.
• Results are non-null; failures (cancellation, misconfiguration, etc.) are returned as a failed Result with a specific reason.

val googleSignIn = rememberGoogleAuthState(onResult = { result -> /* ... */ })
Button(
    onClick = { googleSignIn.launch() }, 
    enabled = !googleSignIn.isInProgress
) {
    Text("Sign in with Google")
}

KMPAuth uses a registry to manage multiple authentication backends. Each backend is identified by a unique AuthProviderBackend.backendId (e.g., "firebase", "supabase", or a custom ID).

Key behaviors:

• Default Backend: The first backend registered during KMPAuth.initialize becomes the default backend. This default backend is used for non-keyed KMPAuth.* operations and for standard auth state hooks.
• Multiple Backends: You can register multiple backends. Registering additional backends adds them to the registry without changing the existing default.
• Switching Defaults: You can change which backend is considered the default at runtime using setDefaultBackendProvider(id).

KMPAuth.initialize {
    firebase(apiKey = ..., projectId = ..., applicationId = ...) // self-registers, becomes default
    supabase(url = ..., apiKey = ...)                            // registered under "supabase"
    // defaultBackendProvider("supabase")  // optional: make Supabase the default
}

KMPAuth.getBackendProvider()             // returns the default backend
KMPAuth.requireBackendProvider("supabase") // retrieves a specific backend by ID
KMPAuth.setDefaultBackendProvider("supabase") // switches the default backend later

1. Install SDK and Configure Info.plist

Add the Facebook SDK Swift package to your project, then add these keys to your Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fbFACEBOOK_APP_ID</string> <!-- Your Facebook App ID with 'fb' prefix -->
    </array>
  </dict>
</array>

<key>FacebookAppID</key>
<string>FACEBOOK_APP_ID</string>

<key>FacebookClientToken</key>
<string>YOUR_FACEBOOK_CLIENT_TOKEN</string>

<key>FacebookDisplayName</key>
<string>YourAppDisplayName</string>

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>fbapi</string>
  <string>fb-messenger-api</string>
  <string>fbauth2</string>
  <string>fbshareextension</string>
</array>

2. Initialize SDK in AppDelegate

In your Swift code, initialize the Facebook SDK within the application lifecycle methods:

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
    FirebaseApp.configure()
    FBSDKCoreKit.ApplicationDelegate.shared.application(
        application,
        didFinishLaunchingWithOptions: launchOptions
    )
    return true
}

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey : Any] = [:]
) -> Bool {
    return FBSDKCoreKit.ApplicationDelegate.shared.application(
        app,
        open: url,
        options: options
    )
}

Browser-based OAuth flows behave differently depending on the target platform:

• Desktop (JVM): Works out of the box. supabase-kt opens the system browser and uses a local callback server. You must allow-list http://localhost:<port> in your Supabase dashboard. The port can be configured via supabase-kt's httpCallbackConfig.
• Android / iOS: Requires standard supabase-kt deep-link setup. You must set scheme/host on the Supabase client, register the scheme in AndroidManifest.xml or Info.plist, forward the link using handleDeeplinks, and allow-list the redirect URL in the Supabase dashboard.
• Web (JS/wasm): The page redirects to the provider, causing the app to unload. No Result callback will fire. The session is restored by supabase-kt automatically when the page reloads after the redirect.

// Example Browser OAuth call
KMPAuth.signIn(AuthCredential.OAuthWebFlow("github.com"))