Sign in mobile users with a self-hosted page

Add authentication to your mobile app using a self-hosted sign-in page with the

Okta Client SDK for Kotlin

.

---

Learning outcomes

• Configure your Okta org for password-based direct authentication.
• Set up a mobile project with the necessary Okta SDKs.
• Build a credential manager to handle authentication state.
• Create an interface for username/password sign-in flows.
• Implement token refresh and session management.

What you need

• Okta Integrator Free Plan org (opens new window)
• Familiarity with mobile app development concepts

---

Overview

Building a streamlined authentication experience is essential for modern mobile apps. While multifactor authentication provides enhanced security, many apps start with a simpler approach, such as username and password authentication. With the

Okta Client SDK for Kotlin

, you can implement a fully native, password-based sign-in flow like direct authentication. This keeps users within your app while still using the Okta identity platform.

Understand Okta direct authentication for password authentication

Direct authentication enables your mobile app to authenticate users directly through the Okta APIs without browser-based flows. This means that your app maintains complete control over the UI and user experience while Okta handles the security and token management behind the scenes.

For password-only authentication, the flow is straightforward:

1. The user enters credentials in your mobile UI.
2. Your app sends credentials to Okta using direct authentication.
3. Okta validates the credentials and returns OAuth 2.0 tokens.
4. Your app securely stores these tokens for API access.

This approach works well for internal apps, rapid prototyping, or scenarios where you want to add MFA capabilities later without restructuring your codebase.

Security considerations

While this implementation provides a functional authentication system, keep these security points in mind:

• Use only HTTPS: Ensure that all API calls use secure connections. Okta enforces this by default.

• Consider adding MFA: Password-only authentication is less secure than password + MFA. Consider adding support for more authenticators as your app matures.

• Handle token expiration: Always implement token refresh logic to maintain sessions without requiring the user to repeatedly sign in.

• Secure storage: Never store passwords locally. The

  Okta Client SDK for Kotlin

  handles secure token storage automatically.

• Error handling: Provide clear error messages without exposing sensitive security details.

How the components work together

In this guide, you create the user interface using several components. The following displays the flow of data through the components:

1. The user enters credentials in the LoginScreen text fields.
2. The field values are held as state in the LoginViewModel.
3. The user taps Sign In.
4. LoginScreen calls viewModel.login().
5. LoginViewModel calls authService.authenticate().
6. AuthService updates its authenticationState flow.
7. LoginViewModel collects the state change.
8. LoginScreen recomposes based on the new state.
9. When authenticated, the user can open ProfileScreen or TokenDetailsScreen.

This architecture keeps concerns separated: the composable handles presentation, the view model handles UI logic, and the service handles authentication business logic.

Configure your Okta org

Before diving into code, set up your Okta org to support direct authentication with password authentication.

Set up a mobile app

1. Go to Applications > Applications in your Admin Console.
2. Click Create App Integration and select OIDC - OpenID Connect as the sign-in method.
3. Choose Native Application as the app type, and then click Next.
4. Give your app a name, and then configure the other app settings:
   • Grant type: Ensure that Authorization Code is selected.
   • Sign-in redirect URIs: com.okta.{yourOktaDomain}:/callback
   • Sign-out redirect URIs: com.okta.{yourOktaDomain}:/

   Note: Replace {yourOktaDomain} with your actual Okta domain, such as, dev-123456.asqula.com.

5. In the Assignments > Controlled access section, choose your preferred access control method.
6. Click Save and note the client ID. You need this later.

Configure your authorization server

To enable password-based authentication, follow these steps:

1. Go to Security > API.
2. Select the authorization server that you want to use.
3. Click the Access Policies tab.
4. Create an access policy:
   • Click Add Policy.
   • Name the policy and give it a description.
   • Assign the policy to All clients.
   • Click Create Policy.
5. Add a rule to your policy:
   • Click Add rule.
   • Name the policy rule.
   • In the IF Grant type is section, click Advanced and select Resource Owner Password.
   • Leave the Any user assigned the app default for AND User is.
   • Leave the Any scopes default for AND Scopes requested.
   • Click Create rule.
6. Go to Applications > Applications and select the app that you created.
7. Select the Sign On tab (or Authentication, depending on your org configuration) and scroll down to the User authentication section.
8. For this example, select Password only.

Caution: You need to enable the Resource Owner Password grant type for use with the direct authentication password flows.

Set up your project

Now that you've configured your Okta org, create the mobile app.

Create a project

Now that you've configured your Okta org, create the Android app.

1. In Android Studio, select File > New > New Project.
2. Choose Empty Activity (the Jetpack Compose template), and then click Next.
3. Configure your project:
   • Name: OktaPasswordAuth
   • Package name: com.okta.android.passwordauth
   • Language: Kotlin
   • Minimum SDK: API 23: Android 6.0 (Marshmallow)
4. Click Finish.

The Okta SDK uses Java 8 APIs, so enable core library desugaring. Add the following to your app/build.gradle.kts:

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
}

Add Okta SDK dependencies

Add the Okta Client SDK for Kotlin (opens new window) libraries to the dependencies block of your app/build.gradle.kts:

dependencies {
    // Ensure that the core libraries are compatible using the Bill of Materials (BOM).
    implementation(platform("com.okta.kotlin:bom:2.0.3"))
    implementation("com.okta.kotlin:auth-foundation")

    // OktaDirectAuth is published separately and isn't part of the BOM, so pin its version.
    implementation("com.okta.kotlin:okta-direct-auth:0.0.1")

    // Used by the Compose UI to host a ViewModel.
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7")
}

Note: okta-direct-auth is a pre-release library (0.0.1). It isn't included in the com.okta.kotlin:bom, so set its version explicitly. Check the SDK releases (opens new window) for the latest version.

The code snippets read your configuration from BuildConfig. Enable that feature in the android block of app/build.gradle.kts:

android {
    buildFeatures {
        buildConfig = true
    }
}

Create the configuration file

Rather than hardcoding configuration values, keep them in a properties file:

1. Create a file named okta.properties in your project's root directory:

   issuer=https://{yourOktaDomain}
   clientId={yourClientID}
   authorizationServerId={yourCustomAuthServer}
   

   Replace {yourOktaDomain} and {yourClientID} with the values from the app that you create. Use the org base URL for issuer (such as https://dev-123456.asqula.com). The default custom authorization server is selected in code.

2. Surface those values through BuildConfig. Add the following to the bottom of your app/build.gradle.kts:

   val oktaProperties = java.util.Properties()
   rootProject.file("okta.properties").inputStream().use { oktaProperties.load(it) }
   
   android.defaultConfig {
       buildConfigField("String", "ISSUER", "\"${oktaProperties.getProperty("issuer")}\"")
       buildConfigField("String", "CLIENT_ID", "\"${oktaProperties.getProperty("clientId")}\"")
       buildConfigField("String", "SCOPES", "\"${oktaProperties.getProperty("scopes")}\"")
   }
   

3. Initialize the SDK once at app startup. Create an Application subclass that initializes AuthFoundation and sets the default OIDC configuration used for token storage and the credential lifecycle:

   package com.okta.android.passwordauth
   
   import android.app.Application
   import com.okta.authfoundation.AuthFoundation
   import com.okta.authfoundation.client.OidcConfiguration
   
   class OktaPasswordAuthApplication : Application() {
       override fun onCreate() {
           super.onCreate()
   
           AuthFoundation.initializeAndroidContext(this)
           OidcConfiguration.default = OidcConfiguration(
               clientId = BuildConfig.CLIENT_ID,
               defaultScope = BuildConfig.SCOPES,
               // The default custom authorization server issues the tokens.
               issuer = "${BuildConfig.ISSUER}/oauth2/default"
           )
       }
   }
   

   This configures the AuthFoundation OIDC SDK, which backs token storage and the credential lifecycle (token refresh and user info). The direct authentication flow is configured separately in AuthService. Both target the default custom authorization server.

4. Register the Application class in your AndroidManifest.xml with the android:name attribute:

   <application
       android:name=".OktaPasswordAuthApplication"
       ... >
   

Build the authentication service

With setup complete, implement the core authentication logic and create a service layer that handles all interactions with the Okta direct authentication APIs.

Understand the AuthService architecture

The AuthService is the heart of the Okta authentication system. It serves as a centralized layer that manages the entire authentication lifecycle, from the initial sign-in flow to session maintenance. By encapsulating all authentication logic in a single service, you achieve several important goals:

Separation of concerns: The service isolates authentication logic from UI code, making it easier to both test and maintain. Your composables don't need to know how direct authentication works, they simply call methods like authenticate() or logout().

State management: The service exposes the current authentication state (not authenticated, authenticating, authenticated, or error) as a StateFlow (opens new window), allowing your UI to react appropriately. This state-driven approach makes it easy to show loading indicators, error messages, or authenticated content.

Security best practices: All token handling and storage is managed through the service, ensuring that credentials are stored securely by AuthFoundation (opens new window). Your UI never directly touches sensitive data.

Testability: By defining an interface (AuthServicing), you can easily create fake implementations for unit testing your view models without making actual network calls to Okta.

The service handles five key responsibilities:

• Authentication: Validate user credentials with Okta.
• Token storage: Persist tokens securely with Credential.
• Session management: Track whether a user is authenticated.
• Token refresh: Obtain new access tokens without re-authentication.
• User profile retrieval: Fetch user information from Okta.

Build this step by step, starting with the interface that defines the service contract.

Create the service interface

Create a package named auth in your project, then add a file called AuthService.kt. Start with the authentication state and the service contract:

package com.okta.android.passwordauth.auth

import com.okta.authfoundation.client.dto.OidcUserInfo
import kotlinx.coroutines.flow.StateFlow

sealed interface AuthState {
    data object NotAuthenticated : AuthState
    data object Authenticating : AuthState
    data object Authenticated : AuthState
    data class Error(val message: String) : AuthState
}

interface AuthServicing {
    val authenticationState: StateFlow<AuthState>

    suspend fun restoreSession()
    suspend fun authenticate(username: String, password: String)
    suspend fun logout()
    suspend fun refreshAccessToken()
    suspend fun getCurrentUser(): OidcUserInfo?
    suspend fun currentAccessToken(): String?
}

The AuthState values represent every state of the authentication flow. Your UI observes this state and updates accordingly:

• NotAuthenticated: The user is signed out, show the sign-in form.
• Authenticating: A sign-in attempt is in progress, show a loading indicator.
• Authenticated: The user is signed in, show authenticated content.
• Error: Authentication failed, show the error message.

The AuthServicing interface defines the contract for the Okta authentication service, making it easy to test and fake later.

Implement the AuthService

Below the interface, add the implementation. Start with the basic structure:

import com.okta.android.passwordauth.BuildConfig
import com.okta.authfoundation.credential.Credential
import com.okta.directauth.DirectAuthenticationFlowBuilder
import com.okta.directauth.api.DirectAuthenticationFlow
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow

class AuthService : AuthServicing {

    private val _authenticationState = MutableStateFlow<AuthState>(AuthState.NotAuthenticated)
    override val authenticationState: StateFlow<AuthState> = _authenticationState.asStateFlow()

    // Build the direct authentication flow from your Okta configuration.
    private val directAuth: DirectAuthenticationFlow =
        DirectAuthenticationFlowBuilder.create(
            issuerUrl = BuildConfig.ISSUER,
            clientId = BuildConfig.CLIENT_ID,
            scope = BuildConfig.SCOPES.split(" ")
        ) {
            // Select the default custom authorization server.
            authorizationServerId = "default"
        }.getOrThrow()

    // Restore an existing session if a credential is already stored.
    override suspend fun restoreSession() {
        if (Credential.getDefaultAsync() != null) {
            _authenticationState.value = AuthState.Authenticated
        }
    }
}

This sets up the basic structure of the AuthService. The following code breaks down what each part does:

Authentication state

The _authenticationState is a private MutableStateFlow that only the AuthService can update. It's exposed publicly as a read-only StateFlow through authenticationState, which your UI collects.

The direct authentication flow

The directAuth property holds the DirectAuthenticationFlow instance that communicates with the Okta APIs. DirectAuthenticationFlowBuilder.create(...) returns a Result, so call getOrThrow() to unwrap it. The flow reads its issuerUrl, clientId, and scope from BuildConfig, and authorizationServerId = "default" targets the default custom authorization server.

Restoring a session

restoreSession() checks whether a valid credential already exists. Credential.getDefaultAsync() returns null when no credential is stored, so a non-null result means the user is still signed in. Call this when your app starts so users don't have to re-enter their credentials.

Understand session persistence

One of the key features of this implementation is automatic session restoration. When users close and reopen the app, they remain signed in because restoreSession() checks for an existing credential:

override suspend fun restoreSession() {
    if (Credential.getDefaultAsync() != null) {
        _authenticationState.value = AuthState.Authenticated
    }
}

AuthFoundation stores tokens securely on the device, and they persist across app launches. This creates a seamless experience while maintaining security.

Understand the authentication flow

The authenticate method orchestrates the entire sign-in process. Add it to the AuthService class:

import com.okta.directauth.model.DirectAuthenticationError
import com.okta.directauth.model.DirectAuthenticationState
import com.okta.directauth.model.PrimaryFactor

override suspend fun authenticate(username: String, password: String) {
    // 1. Update state to show authentication is in progress.
    _authenticationState.value = AuthState.Authenticating

    // 2. Send the credentials to Okta using direct authentication.
    when (val state = directAuth.start(username, PrimaryFactor.Password(password))) {
        // 3. On success, store the token and make it the default credential.
        is DirectAuthenticationState.Authenticated -> {
            val credential = Credential.store(state.token)
            Credential.setDefaultAsync(credential)
            _authenticationState.value = AuthState.Authenticated
        }

        // 4. This sample supports password-only sign-in.
        is DirectAuthenticationState.MfaRequired ->
            _authenticationState.value =
                AuthState.Error("Additional verification is required for this account.")

        // 5. Surface a server error message when one is available.
        is DirectAuthenticationError.HttpError.Oauth2Error ->
            _authenticationState.value =
                AuthState.Error(state.errorDescription ?: "Authentication failed.")

        // 6. Handle any other error or unexpected state.
        else ->
            _authenticationState.value = AuthState.Error("Authentication failed.")
    }
}

The following breaks down what each step does:

1. Show progress. Setting the state to Authenticating immediately updates the UI to show a loading indicator, giving the user instant feedback.

2. Send the credentials. directAuth.start(username, PrimaryFactor.Password(password)) is a suspend function that sends the username and password to the Okta direct authentication endpoint and returns a DirectAuthenticationState. The SDK also emits this state on the directAuth.authenticationState flow.

3. Store the token. When the state is Authenticated, Okta has returned a token that contains the access, ID, and refresh tokens. Credential.store(state.token) persists it securely, and Credential.setDefaultAsync(credential) makes it the active credential for the session.

4. Handle MFA. If the org policy requires another factor, the flow returns MfaRequired. This password-only sample treats that as an error. You can extend the flow to handle additional factors later.

5. Handle server errors. An Oauth2Error (such as invalid credentials) carries an errorDescription that you can show the user.

6. Handle everything else. Any other error or unexpected state becomes a generic error message.

Understand the log-out process

The logout method ensures a complete and secure log-out flow. Add it to the AuthService class:

override suspend fun logout() {
    val credential = Credential.getDefaultAsync()
    if (credential != null) {
        // 1. Revoke the tokens on the Okta server.
        credential.revokeAllTokens()
        // 2. Remove the stored tokens from the device.
        credential.delete()
    }
    // 3. Reset the authentication state.
    _authenticationState.value = AuthState.NotAuthenticated
}

1. revokeAllTokens() tells Okta to invalidate the access and refresh tokens, so they can't be used even if someone obtains a copy.
2. delete() removes the stored credential from the device, ensuring that no sensitive data remains locally.
3. Resetting the state to NotAuthenticated returns the UI to the sign-in screen.

Understand token refresh

Access tokens have a limited lifetime (typically one hour) for security. Rather than forcing users to sign in again, use the refresh token. Add this method to the AuthService class:

override suspend fun refreshAccessToken() {
    val credential = Credential.getDefaultAsync() ?: return
    credential.refreshToken()
}

refreshToken() sends the refresh token to Okta, receives a new access token (and potentially a new refresh token), and updates the stored credential, all without requiring the user to re-enter their password. Requesting the offline_access scope is what makes a refresh token available.

Understand user profile retrieval

The getCurrentUser method fetches user profile information from Okta. Add it, along with a helper to read the current access token:

import com.okta.authfoundation.client.OAuth2ClientResult
import com.okta.authfoundation.client.dto.OidcUserInfo

override suspend fun getCurrentUser(): OidcUserInfo? {
    val credential = Credential.getDefaultAsync() ?: return null
    return when (val result = credential.getUserInfo()) {
        is OAuth2ClientResult.Success -> result.result
        is OAuth2ClientResult.Error -> null
    }
}

override suspend fun currentAccessToken(): String? {
    return Credential.getDefaultAsync()?.getAccessTokenIfValid()
}

getUserInfo() calls the Okta /userinfo endpoint using the current access token and returns an OidcUserInfo. It internally refreshes the access token if it's expired. The result exposes standard OpenID Connect claims (name, email, preferredUsername, and subject) through the com.okta.authfoundation.claims extension properties.

getAccessTokenIfValid() returns the current access token when it hasn't expired, or null otherwise.

The full authentication service code

With the AuthService complete, you now have a robust authentication layer that handles the sign-in and sign-out flows, token management, and user profile retrieval. This service forms the foundation of your app's security, and because it's interface-based, it's easy to test and maintain.

Here's the complete AuthService.kt implementation with all methods together for reference:

package com.okta.android.passwordauth.auth

import com.okta.android.passwordauth.BuildConfig
import com.okta.authfoundation.client.OAuth2ClientResult
import com.okta.authfoundation.client.dto.OidcUserInfo
import com.okta.authfoundation.credential.Credential
import com.okta.directauth.DirectAuthenticationFlowBuilder
import com.okta.directauth.api.DirectAuthenticationFlow
import com.okta.directauth.model.DirectAuthenticationError
import com.okta.directauth.model.DirectAuthenticationState
import com.okta.directauth.model.PrimaryFactor
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow

sealed interface AuthState {
    data object NotAuthenticated : AuthState
    data object Authenticating : AuthState
    data object Authenticated : AuthState
    data class Error(val message: String) : AuthState
}

interface AuthServicing {
    val authenticationState: StateFlow<AuthState>

    suspend fun restoreSession()
    suspend fun authenticate(username: String, password: String)
    suspend fun logout()
    suspend fun refreshAccessToken()
    suspend fun getCurrentUser(): OidcUserInfo?
    suspend fun currentAccessToken(): String?
}

class AuthService : AuthServicing {

    private val _authenticationState = MutableStateFlow<AuthState>(AuthState.NotAuthenticated)
    override val authenticationState: StateFlow<AuthState> = _authenticationState.asStateFlow()

    private val directAuth: DirectAuthenticationFlow =
        DirectAuthenticationFlowBuilder.create(
            issuerUrl = BuildConfig.ISSUER,
            clientId = BuildConfig.CLIENT_ID,
            scope = BuildConfig.SCOPES.split(" ")
        ) {
            authorizationServerId = "default"
        }.getOrThrow()

    override suspend fun restoreSession() {
        if (Credential.getDefaultAsync() != null) {
            _authenticationState.value = AuthState.Authenticated
        }
    }

    override suspend fun authenticate(username: String, password: String) {
        _authenticationState.value = AuthState.Authenticating

        when (val state = directAuth.start(username, PrimaryFactor.Password(password))) {
            is DirectAuthenticationState.Authenticated -> {
                val credential = Credential.store(state.token)
                Credential.setDefaultAsync(credential)
                _authenticationState.value = AuthState.Authenticated
            }

            is DirectAuthenticationState.MfaRequired ->
                _authenticationState.value =
                    AuthState.Error("Additional verification is required for this account.")

            is DirectAuthenticationError.HttpError.Oauth2Error ->
                _authenticationState.value =
                    AuthState.Error(state.errorDescription ?: "Authentication failed.")

            else ->
                _authenticationState.value = AuthState.Error("Authentication failed.")
        }
    }

    override suspend fun logout() {
        val credential = Credential.getDefaultAsync()
        if (credential != null) {
            credential.revokeAllTokens()
            credential.delete()
        }
        _authenticationState.value = AuthState.NotAuthenticated
    }

    override suspend fun refreshAccessToken() {
        val credential = Credential.getDefaultAsync() ?: return
        credential.refreshToken()
    }

    override suspend fun getCurrentUser(): OidcUserInfo? {
        val credential = Credential.getDefaultAsync() ?: return null
        return when (val result = credential.getUserInfo()) {
            is OAuth2ClientResult.Success -> result.result
            is OAuth2ClientResult.Error -> null
        }
    }

    override suspend fun currentAccessToken(): String? {
        return Credential.getDefaultAsync()?.getAccessTokenIfValid()
    }
}

Build the user interface

With the service layer complete, create the user interface.

Use a ViewModel with Jetpack Compose to keep your UI clean and testable.

Understand the UI architecture

Before diving into code, understand the components that you build and how they work together:

LoginViewModel: The bridge between UI and business logic

The LoginViewModel acts as an intermediary layer between your composables and the AuthService. This separation provides several benefits:

• UI state management: The view model holds UI-specific state (like the username, password, and error message) and exposes it as StateFlows that your composables collect.
• Action coordination: It translates user actions (button taps) into service calls inside viewModelScope, handling coroutine lifecycle for you.
• Testability: You can test view logic independently by injecting a fake AuthServicing.

LoginScreen: The main authentication interface

The LoginScreen is your app's primary authentication screen. It recomposes based on the authentication state that's collected from the view model:

• Login form (NotAuthenticated or Error): Username and password fields with a sign-in button.
• Loading state (Authenticating): A progress indicator while credentials are verified.
• Authenticated view (Authenticated): Token preview, action buttons, and navigation to other screens.

Create the view model

Create a package named ui and add LoginViewModel.kt:

package com.okta.android.passwordauth.ui

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.okta.android.passwordauth.auth.AuthService
import com.okta.android.passwordauth.auth.AuthServicing
import com.okta.android.passwordauth.auth.AuthState
import com.okta.authfoundation.client.dto.OidcUserInfo
import com.okta.authfoundation.credential.Credential
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch

class LoginViewModel(
    private val authService: AuthServicing = AuthService(),
) : ViewModel() {

    val authState: StateFlow<AuthState> = authService.authenticationState

    private val _username = MutableStateFlow("")
    val username: StateFlow<String> = _username.asStateFlow()

    private val _password = MutableStateFlow("")
    val password: StateFlow<String> = _password.asStateFlow()

    private val _errorMessage = MutableStateFlow<String?>(null)
    val errorMessage: StateFlow<String?> = _errorMessage.asStateFlow()

    init {
        // Restore an existing session when the app starts.
        viewModelScope.launch { authService.restoreSession() }
    }

    fun onUsernameChange(value: String) { _username.value = value }
    fun onPasswordChange(value: String) { _password.value = value }

    fun login() {
        viewModelScope.launch {
            _errorMessage.value = null
            authService.authenticate(_username.value, _password.value)
            val state = authService.authenticationState.value
            if (state is AuthState.Error) _errorMessage.value = state.message
            if (state is AuthState.Authenticated) _password.value = ""
        }
    }

    fun logout() {
        viewModelScope.launch {
            authService.logout()
            _username.value = ""
            _password.value = ""
            _errorMessage.value = null
        }
    }

    fun refreshToken() {
        viewModelScope.launch { authService.refreshAccessToken() }
    }

    suspend fun fetchUserProfile(): OidcUserInfo? = authService.getCurrentUser()

    suspend fun currentAccessToken(): String =
        authService.currentAccessToken() ?: "No token"

    suspend fun tokenDetails(): Map<String, String> {
        val token = Credential.getDefaultAsync()?.token ?: return emptyMap()
        return buildMap {
            put("Token type", token.tokenType)
            put("Access token", token.accessToken)
            token.scope?.let { put("Scopes", it) }
            token.idToken?.let { put("ID token", it) }
            token.refreshToken?.let { put("Refresh token", it) }
            put("Expires in", "${token.expiresIn} seconds")
        }
    }
}

Create the login screen

Replace the contents of your MainActivity's composable (or create LoginScreen.kt in the ui package) with the following code:

package com.okta.android.passwordauth.ui

import androidx.compose.foundation.layout.*
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import com.okta.android.passwordauth.auth.AuthState

@Composable
fun LoginScreen(viewModel: LoginViewModel = viewModel()) {
    val authState by viewModel.authState.collectAsState()

    when (authState) {
        is AuthState.Authenticated -> AuthenticatedView(viewModel)
        AuthState.Authenticating -> LoadingView()
        else -> LoginForm(viewModel)
    }
}

@Composable
private fun LoginForm(viewModel: LoginViewModel) {
    val username by viewModel.username.collectAsState()
    val password by viewModel.password.collectAsState()
    val errorMessage by viewModel.errorMessage.collectAsState()
    val canSubmit = username.isNotEmpty() && password.isNotEmpty()

    Column(
        modifier = Modifier.fillMaxSize().padding(24.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        Text("Welcome back", style = MaterialTheme.typography.headlineMedium)
        Text("Sign in with your Okta credentials", style = MaterialTheme.typography.bodyMedium)

        OutlinedTextField(
            value = username,
            onValueChange = viewModel::onUsernameChange,
            label = { Text("Email or username") },
            singleLine = true,
            keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
            modifier = Modifier.fillMaxWidth()
        )

        OutlinedTextField(
            value = password,
            onValueChange = viewModel::onPasswordChange,
            label = { Text("Password") },
            singleLine = true,
            visualTransformation = PasswordVisualTransformation(),
            keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
            modifier = Modifier.fillMaxWidth()
        )

        Button(
            onClick = viewModel::login,
            enabled = canSubmit,
            modifier = Modifier.fillMaxWidth()
        ) {
            Text("Sign In")
        }

        errorMessage?.let {
            Text(it, color = MaterialTheme.colorScheme.error)
        }
    }
}

@Composable
private fun LoadingView() {
    Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
        Column(horizontalAlignment = Alignment.CenterHorizontally) {
            CircularProgressIndicator()
            Spacer(Modifier.height(16.dp))
            Text("Signing in...")
        }
    }
}

@Composable
private fun AuthenticatedView(viewModel: LoginViewModel) {
    var showProfile by remember { mutableStateOf(false) }
    var showTokens by remember { mutableStateOf(false) }
    var token by remember { mutableStateOf("") }

    LaunchedEffect(Unit) { token = viewModel.currentAccessToken() }

    Column(
        modifier = Modifier.fillMaxSize().padding(24.dp),
        verticalArrangement = Arrangement.spacedBy(12.dp)
    ) {
        Text("Successfully authenticated", style = MaterialTheme.typography.headlineSmall)
        Text("Access token", style = MaterialTheme.typography.labelMedium)
        Text(token, style = MaterialTheme.typography.bodySmall, maxLines = 4)

        Button(onClick = { showProfile = true }, modifier = Modifier.fillMaxWidth()) {
            Text("View Profile")
        }
        Button(onClick = { showTokens = true }, modifier = Modifier.fillMaxWidth()) {
            Text("Token Details")
        }
        Button(onClick = viewModel::refreshToken, modifier = Modifier.fillMaxWidth()) {
            Text("Refresh Token")
        }
        Button(onClick = viewModel::logout, modifier = Modifier.fillMaxWidth()) {
            Text("Sign Out")
        }
    }

    if (showProfile) ProfileDialog(viewModel) { showProfile = false }
    if (showTokens) TokenDetailsDialog(viewModel) { showTokens = false }
}

Create the supporting screens

ProfileDialog displays the signed-in user's profile, and TokenDetailsDialog inspects the issued tokens. Add both to LoginScreen.kt:

import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import com.okta.authfoundation.claims.email
import com.okta.authfoundation.claims.name
import com.okta.authfoundation.claims.preferredUsername
import com.okta.authfoundation.claims.subject

@Composable
private fun ProfileDialog(viewModel: LoginViewModel, onDismiss: () -> Unit) {
    var profile by remember { mutableStateOf<Map<String, String>?>(null) }

    LaunchedEffect(Unit) {
        val userInfo = viewModel.fetchUserProfile()
        profile = if (userInfo == null) {
            emptyMap()
        } else {
            mapOf(
                "Name" to (userInfo.name ?: "Not provided"),
                "Email" to (userInfo.email ?: "Not provided"),
                "Username" to (userInfo.preferredUsername ?: "Not provided"),
                "User ID" to (userInfo.subject ?: "Unknown")
            )
        }
    }

    AlertDialog(
        onDismissRequest = onDismiss,
        confirmButton = { TextButton(onClick = onDismiss) { Text("Done") } },
        title = { Text("Profile") },
        text = {
            when (val current = profile) {
                null -> CircularProgressIndicator()
                else -> Column {
                    current.forEach { (label, value) ->
                        Text(label, style = MaterialTheme.typography.labelSmall)
                        Text(value, style = MaterialTheme.typography.bodyMedium)
                        Spacer(Modifier.height(8.dp))
                    }
                }
            }
        }
    )
}

@Composable
private fun TokenDetailsDialog(viewModel: LoginViewModel, onDismiss: () -> Unit) {
    var details by remember { mutableStateOf<Map<String, String>>(emptyMap()) }

    LaunchedEffect(Unit) { details = viewModel.tokenDetails() }

    AlertDialog(
        onDismissRequest = onDismiss,
        confirmButton = { TextButton(onClick = onDismiss) { Text("Done") } },
        title = { Text("Token Details") },
        text = {
            Column(modifier = Modifier.verticalScroll(rememberScrollState())) {
                details.forEach { (label, value) ->
                    Text(label, style = MaterialTheme.typography.labelMedium)
                    Text(value, style = MaterialTheme.typography.bodySmall)
                    Spacer(Modifier.height(8.dp))
                }
            }
        }
    )
}

Finally, show the LoginScreen from your MainActivity:

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import com.okta.android.passwordauth.ui.LoginScreen

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                LoginScreen()
            }
        }
    }
}

Test your implementation

You're now ready to test the complete authentication flow:

1. Build and run: Select an emulator or connected device, then click Run (or press Shift+F10).
2. Enter credentials: Use valid Okta user credentials from your org.
3. Sign in: Tap Sign In.
4. View token: After successful authentication, your access token appears.
5. Explore features:
   • Tap View Profile to see user information.
   • Tap Token Details to inspect all tokens.
   • Tap Refresh Token to get a new access token.
   • Tap Sign Out to clear the session.

Handle common issues

Invalid credentials
If you see an authentication error, verify the following:

• The username and password are correct.
• The user is assigned to your app in Okta.
• The Resource Owner Password grant type is enabled in your authorization server.

Configuration errors
If the app crashes on launch, verify the following:

• Double-check your okta.properties values.
• Ensure that your client ID and issuer URL are correct.
• Confirm that you registered OktaPasswordAuthApplication in AndroidManifest.xml with android:name.
• Confirm that buildConfig = true is set so the BuildConfig values are generated.

Token expiration
Access tokens typically expire after one hour. Use the Refresh Token button to get a new one without reauthenticating. A refresh token is only issued when you request the offline_access scope.

Pre-release SDK
okta-direct-auth is a pre-release library (0.0.1). Its API may change before a stable release, so check the SDK releases (opens new window) and changelog when you upgrade.

Beyond username and password

You've built a complete, mobile authentication system using Okta direct authentication with username and password. Your app now handles credential validation, secure token storage, session management, and token refresh all without leaving your mobile UI.

This foundation makes it easy to add more sophisticated authentication features later like biometric verification or passwordless, while maintaining the same clean architecture.

The

Okta Client SDK for Kotlin

provides a secure and user-friendly authentication experience that can scale with your app's needs.