This comprehensive guide covers implementing PKCE (Proof Key for Code Exchange) for Single Page Applications (SPAs) and native mobile applications using Oten IDP.
PKCE (Proof Key for Code Exchange) is a security extension to OAuth 2.0 that prevents authorization code interception attacks. It's required for public clients that cannot securely store client secrets.
What is PKCE?
PKCE works by generating a cryptographically random string called a "code verifier" and its derived "code challenge". The code challenge is sent with the authorization request, and the code verifier is sent with the token request to prove that the same client that initiated the flow is completing it.
// OtenAuth.kt
import android.content.Context
import android.content.Intent
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent
import androidx.lifecycle.LiveData
import androidx.lifecycle.MutableLiveData
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey
import kotlinx.coroutines.*
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
import java.io.IOException
import java.security.MessageDigest
import java.security.SecureRandom
import java.util.*
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException
import kotlin.coroutines.suspendCoroutine
@Serializable
data class UserInfo(
val sub: String,
val email: String,
val name: String,
val picture: String? = null,
val exp: Long
)
@Serializable
data class AuthTokens(
val access_token: String,
val refresh_token: String,
val id_token: String
)
class OtenAuth(
private val context: Context,
private val clientId: String,
private val redirectUri: String
) {
private val baseUrl = "https://account.oten.com"
private val httpClient = OkHttpClient()
private val json = Json { ignoreUnknownKeys = true }
private val _isAuthenticated = MutableLiveData<Boolean>()
val isAuthenticated: LiveData<Boolean> = _isAuthenticated
private val _user = MutableLiveData<UserInfo?>()
val user: LiveData<UserInfo?> = _user
private val _isLoading = MutableLiveData<Boolean>()
val isLoading: LiveData<Boolean> = _isLoading
private val _error = MutableLiveData<String?>()
val error: LiveData<String?> = _error
private val encryptedPrefs by lazy {
val masterKey = MasterKey.Builder(context)
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
.build()
EncryptedSharedPreferences.create(
context,
"oten_auth",
masterKey,
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)
}
init {
checkAuthenticationStatus()
}
// MARK: - PKCE Generation
private fun generateCodeVerifier(): String {
val charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
val random = SecureRandom()
return (1..128)
.map { charset[random.nextInt(charset.length)] }
.joinToString("")
}
private fun generateCodeChallenge(verifier: String): String {
val bytes = verifier.toByteArray(Charsets.UTF_8)
val digest = MessageDigest.getInstance("SHA-256").digest(bytes)
return Base64.getUrlEncoder().withoutPadding().encodeToString(digest)
}
private fun generateState(): String {
return UUID.randomUUID().toString().replace("-", "")
}
// MARK: - Authentication Flow
fun login(
scope: String = "openid profile email",
prompt: String? = null,
uiLocales: String? = null
) {
CoroutineScope(Dispatchers.Main).launch {
try {
_isLoading.value = true
_error.value = null
// Generate PKCE parameters
val codeVerifier = generateCodeVerifier()
val codeChallenge = generateCodeChallenge(codeVerifier)
val state = generateState()
// Store parameters securely
encryptedPrefs.edit()
.putString("code_verifier", codeVerifier)
.putString("oauth_state", state)
.apply()
// Create authorization URL directly (no JAR for public clients)
val authUri = Uri.parse("$baseUrl/v1/oauth/authorize")
.buildUpon()
.appendQueryParameter("client_id", clientId)
.appendQueryParameter("response_type", "code")
.appendQueryParameter("redirect_uri", redirectUri)
.appendQueryParameter("scope", scope)
.appendQueryParameter("state", state)
.appendQueryParameter("code_challenge", codeChallenge)
.appendQueryParameter("code_challenge_method", "S256")
// Add optional parameters
prompt?.let { authUri.appendQueryParameter("prompt", it) }
uiLocales?.let { authUri.appendQueryParameter("ui_locales", it) }
presentAuthenticationSession(authUri.build())
} catch (e: Exception) {
_error.value = e.message
_isLoading.value = false
}
}
}
private fun presentAuthenticationSession(authUri: Uri) {
val customTabsIntent = CustomTabsIntent.Builder()
.setShowTitle(true)
.build()
customTabsIntent.launchUrl(context, authUri)
_isLoading.value = false
}
fun handleCallback(intent: Intent) {
CoroutineScope(Dispatchers.Main).launch {
try {
_isLoading.value = true
_error.value = null
val uri = intent.data ?: throw Exception("No callback URI found")
val code = uri.getQueryParameter("code")
val state = uri.getQueryParameter("state")
val error = uri.getQueryParameter("error")
if (error != null) {
val errorDescription = uri.getQueryParameter("error_description") ?: error
throw Exception("OAuth error: $errorDescription")
}
if (code == null || state == null) {
throw Exception("Missing authorization code or state parameter")
}
// Validate state
val storedState = encryptedPrefs.getString("oauth_state", null)
if (storedState == null || state != storedState) {
throw Exception("Invalid state parameter - possible CSRF attack")
}
// Get code verifier
val codeVerifier = encryptedPrefs.getString("code_verifier", null)
?: throw Exception("Code verifier not found")
// Clean up stored values
encryptedPrefs.edit()
.remove("oauth_state")
.remove("code_verifier")
.apply()
// Exchange code for tokens
val tokens = exchangeCodeForTokens(code, codeVerifier)
storeTokens(tokens)
parseUserInfo(tokens.id_token)
} catch (e: Exception) {
_error.value = e.message
_isLoading.value = false
}
}
}
private suspend fun exchangeCodeForTokens(code: String, codeVerifier: String): AuthTokens =
suspendCoroutine { continuation ->
val formBody = FormBody.Builder()
.add("grant_type", "authorization_code")
.add("code", code)
.add("redirect_uri", redirectUri)
.add("client_id", clientId)
.add("code_verifier", codeVerifier)
.build()
val request = Request.Builder()
.url("$baseUrl/v1/oauth/token")
.post(formBody)
.build()
httpClient.newCall(request).enqueue(object : Callback {
override fun onFailure(call: Call, e: IOException) {
continuation.resumeWithException(e)
}
override fun onResponse(call: Call, response: Response) {
try {
val responseBody = response.body?.string()
if (response.isSuccessful && responseBody != null) {
val tokens = json.decodeFromString<AuthTokens>(responseBody)
continuation.resume(tokens)
} else {
continuation.resumeWithException(Exception("Token exchange failed: ${response.code}"))
}
} catch (e: Exception) {
continuation.resumeWithException(e)
}
}
})
}
// MARK: - Token Management
private fun storeTokens(tokens: AuthTokens) {
encryptedPrefs.edit()
.putString("access_token", tokens.access_token)
.putString("refresh_token", tokens.refresh_token)
.putString("id_token", tokens.id_token)
.apply()
}
private fun parseUserInfo(idToken: String) {
try {
val parts = idToken.split(".")
if (parts.size != 3) {
throw Exception("Invalid ID token format")
}
val payload = parts[1]
val decodedBytes = Base64.getUrlDecoder().decode(payload)
val userInfo = json.decodeFromString<UserInfo>(String(decodedBytes))
// Check token expiration
if (userInfo.exp < System.currentTimeMillis() / 1000) {
logout()
return
}
_user.value = userInfo
_isAuthenticated.value = true
_isLoading.value = false
} catch (e: Exception) {
_error.value = "Failed to parse user info: ${e.message}"
_isLoading.value = false
}
}
fun checkAuthenticationStatus() {
val idToken = encryptedPrefs.getString("id_token", null)
if (idToken != null) {
parseUserInfo(idToken)
} else {
_isAuthenticated.value = false
_user.value = null
}
}
fun logout() {
encryptedPrefs.edit()
.remove("access_token")
.remove("refresh_token")
.remove("id_token")
.remove("oauth_state")
.remove("code_verifier")
.apply()
_isAuthenticated.value = false
_user.value = null
_error.value = null
}
}
// MainActivity.kt
import android.content.Intent
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.runtime.livedata.observeAsState
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
class MainActivity : ComponentActivity() {
private lateinit var auth: OtenAuth
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
auth = OtenAuth(
context = this,
clientId = "your-client-id",
redirectUri = "myapp://callback"
)
setContent {
OtenAuthTheme {
AuthScreen(auth = auth)
}
}
// Handle callback if this activity was launched by redirect
handleCallbackIfNeeded(intent)
}
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
handleCallbackIfNeeded(intent)
}
private fun handleCallbackIfNeeded(intent: Intent?) {
if (intent?.data?.scheme == "myapp") {
auth.handleCallback(intent)
}
}
}
@Composable
fun AuthScreen(auth: OtenAuth) {
val isAuthenticated by auth.isAuthenticated.observeAsState(false)
val user by auth.user.observeAsState()
val isLoading by auth.isLoading.observeAsState(false)
val error by auth.error.observeAsState()
Column(
modifier = Modifier
.fillMaxSize()
.padding(16.dp),
horizontalAlignment = Alignment.CenterHorizontally,
verticalArrangement = Arrangement.Center
) {
if (isAuthenticated && user != null) {
// Authenticated view
Card(
modifier = Modifier.fillMaxWidth(),
elevation = CardDefaults.cardElevation(defaultElevation = 4.dp)
) {
Column(
modifier = Modifier.padding(16.dp),
horizontalAlignment = Alignment.CenterHorizontally
) {
Text(
text = user!!.name,
style = MaterialTheme.typography.headlineSmall
)
Spacer(modifier = Modifier.height(8.dp))
Text(
text = user!!.email,
style = MaterialTheme.typography.bodyMedium
)
Spacer(modifier = Modifier.height(16.dp))
Button(
onClick = { auth.logout() },
modifier = Modifier.fillMaxWidth()
) {
Text("Logout")
}
}
}
} else {
// Login view
Column(
horizontalAlignment = Alignment.CenterHorizontally
) {
Text(
text = "Welcome",
style = MaterialTheme.typography.headlineMedium
)
Spacer(modifier = Modifier.height(8.dp))
Text(
text = "Sign in with Oten to continue",
style = MaterialTheme.typography.bodyMedium
)
Spacer(modifier = Modifier.height(24.dp))
Button(
onClick = { auth.login() },
enabled = !isLoading,
modifier = Modifier.fillMaxWidth()
) {
if (isLoading) {
CircularProgressIndicator(
modifier = Modifier.size(16.dp),
strokeWidth = 2.dp
)
Spacer(modifier = Modifier.width(8.dp))
}
Text(if (isLoading) "Signing In..." else "Sign In")
}
}
}
error?.let { errorMessage ->
Spacer(modifier = Modifier.height(16.dp))
Card(
colors = CardDefaults.cardColors(
containerColor = MaterialTheme.colorScheme.errorContainer
)
) {
Text(
text = "Error: $errorMessage",
modifier = Modifier.padding(16.dp),
color = MaterialTheme.colorScheme.onErrorContainer
)
}
}
}
}
// ✅ Correct: Use cryptographically secure random generation
function generateSecureCodeVerifier() {
const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
const randomValues = new Uint8Array(128);
window.crypto.getRandomValues(randomValues);
return Array.from(randomValues, byte => charset[byte % charset.length]).join('');
}
// ❌ Incorrect: Using Math.random() (not cryptographically secure)
function generateInsecureCodeVerifier() {
const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
return Array.from({length: 128}, () => charset[Math.floor(Math.random() * charset.length)]).join('');
}
// ✅ Correct: Use sessionStorage for temporary storage
sessionStorage.setItem('code_verifier', codeVerifier);
sessionStorage.setItem('oauth_state', state);
// ❌ Incorrect: Using localStorage for sensitive data
localStorage.setItem('code_verifier', codeVerifier); // Persists across sessions
// ✅ Correct: Use Keychain (iOS) or Keystore (Android)
storeInKeychain(key: "code_verifier", value: codeVerifier)
// ❌ Incorrect: Using UserDefaults (iOS) or SharedPreferences (Android)
UserDefaults.standard.set(codeVerifier, forKey: "code_verifier")
// ✅ Correct: Always validate state parameter
const storedState = sessionStorage.getItem('oauth_state');
if (!storedState || state !== storedState) {
throw new Error('Invalid state parameter - possible CSRF attack');
}
// ❌ Incorrect: Skipping state validation
// This leaves your app vulnerable to CSRF attacks
// ✅ Correct: Check token expiration
function isTokenValid(idToken) {
try {
const payload = parseJWT(idToken);
return payload.exp > Date.now() / 1000;
} catch (error) {
return false;
}
}
// ❌ Incorrect: Not checking expiration
// This could lead to using expired tokens
// ❌ Incorrect: Not validating redirect URI
window.location.href = callbackURL; // Could be malicious
// ✅ Correct: Validate redirect URI
if (callbackURL.startsWith(expectedRedirectURI)) {
window.location.href = callbackURL;
} else {
throw new Error('Invalid redirect URI');
}
// ❌ Incorrect: Allowing HTTP in production
const redirectURI = "http://myapp.com/callback";
// ✅ Correct: Always use HTTPS in production
const redirectURI = "https://myapp.com/callback";
// ✅ Ensure same verifier is used throughout the flow
const pkce = await generatePKCE();
sessionStorage.setItem('code_verifier', pkce.codeVerifier); // Store immediately
// Later, in callback
const storedVerifier = sessionStorage.getItem('code_verifier');
if (!storedVerifier) {
throw new Error('Code verifier not found - session may have expired');
}
// ✅ Always include PKCE parameters in JAR
const jarPayload = {
// ... other parameters
code_challenge: pkce.codeChallenge,
code_challenge_method: 'S256'
};
// Validate before creating JAR
if (!pkce.codeChallenge || !pkce.codeChallengeMethod) {
throw new Error('PKCE parameters are required');
}
// ✅ Generate unique state for each request
const state = crypto.randomUUID(); // Always unique
// ✅ Clear previous state before new login
sessionStorage.removeItem('oauth_state');
sessionStorage.setItem('oauth_state', state);
// ✅ Validate state immediately in callback
const urlState = urlParams.get('state');
const storedState = sessionStorage.getItem('oauth_state');
if (!storedState) {
throw new Error('No stored state found - session may have expired');
}
if (urlState !== storedState) {
throw new Error('State mismatch - possible CSRF attack');
}
// ✅ Validate JAR payload before sending
function validateJARPayload(payload) {
const required = ['iss', 'aud', 'iat', 'exp', 'client_id', 'redirect_uri'];
for (const field of required) {
if (!payload[field]) {
throw new Error(`Missing required JAR field: ${field}`);
}
}
}
// ✅ Handle JAR creation errors gracefully
try {
const jarResponse = await fetch('/api/create-jar', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(jarPayload)
});
if (!jarResponse.ok) {
const errorText = await jarResponse.text();
throw new Error(`JAR creation failed (${jarResponse.status}): ${errorText}`);
}
const { requestJWT } = await jarResponse.json();
if (!requestJWT) {
throw new Error('JAR not returned from server');
}
} catch (error) {
console.error('JAR creation error:', error);
throw new Error('Failed to create authorization request');
}
// Enable debug mode for troubleshooting
const authClient = new OtenPKCE(clientId, redirectUri, {
debug: true,
logLevel: 'verbose'
});
// This will log all PKCE parameters and requests
authClient.enableDebugMode();
