Veslo Auth Android SDK

VESLO Logo

A production-grade Android SDK for OIDC/OAuth 2.0 authentication using Veslo Identity provider.

Features

🔐 Secure Authentication - PKCE-based OAuth 2.0 flow via AppAuth
🔄 Token Management - Automatic token refresh with encrypted storage
📡 Observable State - Reactive authentication state via StateFlow
🛡️ Thread Safety - Synchronized singleton with volatile fields
📝 Debug Logging - Optional logging for development
💾 UserInfo Caching - 5-minute TTL cache for user profile

Requirements

Android API 24+ (Android 7.0)
Kotlin 1.9+
AndroidX

Installation

Gradle (Kotlin DSL)

Add the JitPack repository (in settings.gradle.kts) and the dependency:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://jitpack.io")
            credentials {
                username = providers.gradleProperty("authToken").getOrElse("")
                password = ""
            }
        }
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.github.veslo-io:veslo-auth-sdk-android:1.0.1")
}

Private repo: Add your JitPack token to ~/.gradle/gradle.properties (do not commit):

authToken=jp_your_jitpack_token

Or add authToken=jp_your_token to the project’s gradle.properties and keep that file out of version control.

Quick Start

1. Configure the SDK

val config = AuthConfig.builder()
    .clientId("your-client-id")
    .redirectUri("com.yourapp:/oauth2callback")
    .discoveryUri("https://auth.example.com/.well-known/openid-configuration")
    .scopes(listOf("openid", "profile", "email"))
    .enableLogging(BuildConfig.DEBUG)
    .build()
 
VesloAuth.initialize(this, config)

Note: The SDK uses AppAuth’s authorization code flow with PKCE. Include offline_access in scopes if you need refresh tokens for long-lived sessions.

2. Set up AndroidManifest

Add the redirect activity:

<activity
    android:name="net.openid.appauth.RedirectUriReceiverActivity"
    android:exported="true">
    <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="${appAuthRedirectScheme}" />
    </intent-filter>
</activity>

Add the redirect scheme to build.gradle.kts:

android {
    defaultConfig {
        manifestPlaceholders["appAuthRedirectScheme"] = "com.yourapp"
    }
}

Pass a CoroutineScope (e.g. lifecycleScope) so sign-in is cancelled when the scope is cancelled:

VesloAuth.signIn(this, lifecycleScope)

4. Handle Auth Response

In your Activity:

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    if (intent != null && VesloAuth.isAuthCallback(intent)) {
        lifecycleScope.launch { VesloAuth.handleAuthResponse(intent) }
    }
}

5. Observe Authentication State

lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        VesloAuth.state.collect { state ->
            when (state) {
                is VesloAuthState.Idle -> showLoginButton()
                is VesloAuthState.Loading -> showProgress()
                is VesloAuthState.Authenticated -> navigateToHome()
                is VesloAuthState.Error -> showError(state.exception)
            }
        }
    }
}

6. Get Access Token

VesloAuth.getAccessToken()
    .onSuccess { token -> /* Use token */ }
    .onFailure { error -> /* Handle error */ }

7. Get User Info

VesloAuth.getUserInfo()
    .onSuccess { userInfo ->
        Log.d("User", "Name: ${userInfo.name}")
        Log.d("User", "Email: ${userInfo.email}")
    }
    .onFailure { error -> /* Handle error */ }

8. Sign Out

lifecycleScope.launch {
    VesloAuth.signOut()
}

Configuration Options

Option	Type	Default	Description
`clientId`	`String`	Required	OAuth client ID
`redirectUri`	`String`	Required	Redirect URI for auth callback
`discoveryUri`	`String`	Required	OIDC discovery endpoint
`scopes`	`List<String>`	`openid, profile, email, offline_access`	OAuth scopes
`toolbarColor`	`Int?`	`null`	Custom browser toolbar color
`connectionTimeoutMs`	`Int`	`15000`	Network connection timeout
`readTimeoutMs`	`Int`	`15000`	Network read timeout
`enableLogging`	`Boolean`	`false`	Enable debug logging

Error Handling

The SDK uses a typed exception hierarchy:

sealed class VesloAuthException : Exception() {
    class NotInitialized : VesloAuthException()
    class Configuration(message: String) : VesloAuthException()
    class Discovery(cause: Throwable?) : VesloAuthException()
    class Authorization(message: String) : VesloAuthException()
    class TokenExchange(cause: Throwable?) : VesloAuthException()
    class TokenRefresh(cause: Throwable?) : VesloAuthException()
    class Network(message: String) : VesloAuthException()
    class UserInfo(cause: Throwable?) : VesloAuthException()
}

ProGuard

The SDK includes consumer ProGuard rules. No additional configuration needed.

Dependencies

AppAuth for Android - OAuth 2.0/OIDC
AndroidX Security Crypto - Encrypted storage
Kotlin Coroutines - Async operations
Gson - JSON parsing

License

See LICENSE for details.