Android Quickstart

Use this guide to add ThunderID authentication to an Android application using the ThunderID Android SDK for Jetpack Compose.

What You Will Learn

• Create a new Android Studio project

• Install the dev.thunderid:compose Gradle dependency

• Add working sign-in and sign-out using Jetpack Compose components

• Display the signed-in user's name

Prerequisites

• About 15 minutes

• Android Studio, installed and up to date

• API 24 (Android 7.0) deployment target

Example Source Code

Check out the complete Android Quickstart Sample in the ThunderID repository.

1

Run ThunderID

Start a local ThunderID instance. Pick the method that works best for you:

$npx thunderid

Requires Node.js 18+

Full install guide →

Once it's running, the console is available at https://localhost:8090/console.

2

Create an Application

1. Sign in to the Console.

   Test User

   If you used the default setup, sign in to the Console as admin with the password generated during setup and printed to the setup output (unless you supplied your own).

2. Navigate to Applications, and click Add Application.

3. Under Application Type, select Mobile App.

4. Enter a name (e.g. My Android App) and create an application. The rest of the settings can stay at their defaults.

5. Copy the Client ID from the General tab. You'll add the redirect URI in the next step after configuring your URL scheme.

3

Create an Android App

In Android Studio, create a new project using the Empty Activity template with Kotlin as the language and Jetpack Compose enabled.

note

If you already have an existing Android project, skip this step.

4

Install the ThunderID Compose SDK

Add the ThunderID Maven repository to your settings.gradle.kts:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        maven("https://maven.thunderid.dev/releases")
    }
}

Then add the dev.thunderid:compose dependency to your app's build.gradle.kts. This includes the core dev.thunderid:android client as a dependency.

build.gradle.kts

dependencies {
    implementation("dev.thunderid:compose:0.1.0")
}

note

If you use Groovy-based Gradle scripts (build.gradle) instead of the Kotlin DSL, add the dependency as:

implementation 'dev.thunderid:compose:0.1.0'

5

Configure a Callback URL Scheme

ThunderID redirects back to your app after sign-in and sign-out using a custom URL scheme. You need to register this scheme in two places.

1. Register the scheme in your app

Open AndroidManifest.xml and add an intent filter with your scheme to your launcher activity. Use singleTask launch mode so the redirect reuses the existing activity instance instead of creating a new one.

AndroidManifest.xml

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="dev.thunderid.quickstart" />
    </intent-filter>
</activity>

2. Register the redirect URI in the ThunderID console

In the console, open your registered application and add the following as an Allowed Redirect URI:

dev.thunderid.quickstart://callback

Add the same value as an Allowed Post-Logout Redirect URI:

dev.thunderid.quickstart://logout

6

Initialize the SDK

Open your MainActivity and wrap the content you pass to setContent with the ThunderIDProvider composable. This provides ThunderIDState to all child composables through LocalThunderID.

MainActivity.kt

package dev.thunderid.quickstart

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.material3.MaterialTheme
import dev.thunderid.android.ThunderIDConfig
import dev.thunderid.compose.ThunderIDProvider

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            MaterialTheme {
                ThunderIDProvider(
                    config = ThunderIDConfig(
                        baseUrl = "https://localhost:8090",
                        clientId = "<your-client-id>",
                        scopes = listOf("openid", "profile", "email"),
                        afterSignInUrl = "dev.thunderid.quickstart://callback",
                        afterSignOutUrl = "dev.thunderid.quickstart://logout",
                        applicationId = "<your-application-id>"
                    )
                ) {
                    ContentView()
                }
            }
        }
    }
}

Configuration

Replace <your-client-id> with the Client ID and <your-application-id> with the Application ID from your ThunderID application settings.

Configuration Parameters

Parameter	Description
baseUrl	Your ThunderID instance URL. Must use HTTPS.
clientId	The Client ID from your ThunderID application
scopes	OAuth 2.0 scopes to request. Include "openid" at minimum.
afterSignInUrl	The redirect URI to return to after sign-in
afterSignOutUrl	The redirect URI to return to after sign-out
applicationId	The Application ID used for embedded (app-native) sign-in flows

7

Add Sign-In and Sign-Out

The ThunderID Android SDK provides SignedIn and SignedOut guard composables for conditional rendering, a SignIn composable for the embedded sign-in flow, and a SignOutButton for sign-out.

Create ContentView.kt:

ContentView.kt

package dev.thunderid.quickstart

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import dev.thunderid.compose.LocalThunderID
import dev.thunderid.compose.components.guards.SignedIn

@Composable
fun ContentView() {
    val thunder = LocalThunderID.current

    if (!thunder.isInitialized) {
        Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
            CircularProgressIndicator()
        }
    } else {
        SignedIn(fallback = { AuthView() }) {
            HomeView()
        }
    }
}

Create AuthView.kt to display the sign-in form:

AuthView.kt

package dev.thunderid.quickstart

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import dev.thunderid.compose.components.presentation.auth.SignIn

@Composable
fun AuthView() {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(24.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center,
    ) {
        Text(text = "Welcome", style = MaterialTheme.typography.headlineMedium)
        SignIn(
            applicationId = "<your-application-id>",
            modifier = Modifier.padding(top = 24.dp),
        )
    }
}

8

Display User Profile Information

Create HomeView.kt to show the authenticated user's name and a sign-out button:

HomeView.kt

package dev.thunderid.quickstart

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import dev.thunderid.compose.LocalThunderID
import dev.thunderid.compose.components.actions.SignOutButton

@Composable
fun HomeView() {
    val thunder = LocalThunderID.current
    val user = thunder.user

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(24.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center,
    ) {
        Text(
            text = "Welcome, ${user?.displayName ?: user?.email ?: "User"}!",
            style = MaterialTheme.typography.headlineSmall,
        )
        user?.email?.let {
            Text(text = it, style = MaterialTheme.typography.bodyMedium)
        }
        SignOutButton(modifier = Modifier.padding(top = 24.dp))
    }
}

9

Run the App

In Android Studio, select an API 24+ emulator or device and press Run (▶).

Test credentials

You'll need a user to sign in with. If you haven't created one yet, open https://localhost:8090/console, navigate to Users, and add a test user with an email and password.

Success

You should see the sign-in form. Enter your test user credentials and tap Submit. After successful authentication, the home screen displays the user's name and a Sign Out button.

What's Next

Upgrade the sign-in flow

Add MFA, passkeys, or social login to your flow, no app code changes required.

Flow Designer →

Android SDK Reference

Explore the full API reference for the ThunderID Android SDK.

API Reference →