Android Quickstart

Use this guide to add ThunderID authentication to an Android application using the com.github.thunder-id:android-sdks.

What You Will Learn

• Create a new Android Studio project

• Install the com.github.thunder-id:android-sdks 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 26 (Android 8.0) deployment target

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.

3. Click Add Application.

4. From the Choose a type page, select Android.

5. Enter a name (e.g. My Android App).

6. Select how you want to sign in users (e.g., email/password, social login, etc.).

7. Select Theme settings.

8. Leave Sign-In Approach set to Bring Your Own UI (the default for Android applications).

9. Click Create.

warning

Copy the Application ID from the General tab, under Quick Copy. You'll need it when configuring the SDK.

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 JitPack repository to your settings.gradle.kts:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

Then add the dependency to your app's build.gradle.kts, using the latest release tag of the android-sdks repository:

build.gradle.kts

dependencies {
    implementation("com.github.thunder-id:android-sdks:<latest-release-tag>")
}

note

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

dependencies {
    implementation 'com.github.thunder-id:android-sdks:<latest-release-tag>'
}

5

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://10.0.2.2:8090",
                        scopes = listOf("openid", "profile", "email"),
                        applicationId = "<your-application-id>"
                    )
                ) {
                    ContentView()
                }
            }
        }
    }
}

Configuration

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

On the Android Emulator, localhost refers to the emulator itself, not your host machine, so baseUrl uses the special alias 10.0.2.2 to reach the host's localhost:8090 instead. If you're running on a physical device, use your host machine's LAN IP address (e.g. https://192.168.1.100:8090) rather than 10.0.2.2.

Configuration Parameters

Parameter	Description
baseUrl	Your ThunderID instance URL. Must use HTTPS.
scopes	OAuth 2.0 scopes to request. Include "openid" at minimum.
applicationId	The Application ID used for the app-native sign-in and sign-up flows

6

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),
        )
    }
}

7

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))
    }
}

8

Run the App

In Android Studio, select an API 26+ 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 flowAdd MFA, passkeys, or social login to your flow, no app code changes required.Flow Designer →

Android SDK ReferenceExplore the full API reference for the Android SDK.API Reference →