Expo Keycloak Integration Demo 🚀

This project demonstrates how to integrate Keycloak authentication with a React Native mobile application built using Expo.

📋 Overview

This demo showcases a complete Keycloak integration including:

• OAuth 2.0 authentication flow using OpenID Connect
• Token management and secure storage
• User session management
• Cross-platform support (iOS, Android, Web)

🔧 Technology Stack

• Expo SDK 54.0.10 with React 19.1.0 and React Native 0.81.4
• TypeScript 5.9.2 with path aliases (@/*)
• Expo Router 6.0.8 for file-based routing
• Expo Auth Session for OAuth authentication
• Expo Secure Store for secure token storage
• Keycloak for identity and access management

🚀 Getting Started

Prerequisites

1. Keycloak Server: Running Keycloak instance with a configured realm and client
2. Client Configuration: Mobile client configured with redirect URI ukata.mobile://redirect
3. Node.js & npm: For running the development server

Installation

1. Clone the repository

2. Install dependencies:

   npm install

3. Configure your Keycloak settings in services/keycloak.ts:

   export const keycloakConfig: KeycloakConfig = {
     url: 'https://your-keycloak-server.com',
     realm: 'your-realm',
     clientId: 'your-client-id',
     redirectUri: 'ukata.mobile://redirect'
   };

4. Start the development server:

   npx expo start

📱 Running the App

You can run the app on different platforms:

• Development build: For full functionality
• Android emulator: npm run android
• iOS simulator: npm run ios
• Web: npm run web
• Expo Go: Limited functionality for testing

🔐 Key Features

Authentication Flow

• Uses OpenID Connect protocol for secure authentication
• Implements OAuth 2.0 Authorization Code flow
• Automatic token refresh and session management
• Secure token storage using Expo Secure Store

Keycloak Integration

• Discovery Document: Automatically fetches Keycloak configuration
• Token Management: Handles access tokens, refresh tokens, and ID tokens
• User Information: Extracts user details from JWT tokens
• Logout: Implements proper logout with token revocation

Security Features

• Secure token storage with fallback mechanisms
• JWT token validation and parsing
• Session state management
• Proper error handling and logging

📂 Project Structure

├── app/
│   ├── login.tsx              # Login screen with Keycloak integration
│   ├── (tabs)/
│   │   └── dashboard.tsx      # Protected dashboard screen
│   └── _layout.tsx            # Root navigation layout
├── services/
│   ├── keycloak.ts           # Keycloak service implementation
│   ├── auth-storage.ts       # Secure token storage
│   └── jwt-utils.ts          # JWT utility functions
├── components/
│   ├── themed/               # Themed UI components
│   └── ui/                   # Reusable UI components
└── constants/                # App constants and themes

🔧 Keycloak Configuration

Required Client Settings

1. Access Type: confidential
2. Valid Redirect URIs: ukata.mobile://redirect
3. Web Origins: * (for development)
4. Standard Flow Enabled: ON

User Attributes

The app expects the following user attributes:

• name or given_name + family_name
• email
• preferred_username (optional)

🛠 Development Commands

npm start          # Start Expo development server
npm run android    # Start Android development build
npm run ios        # Start iOS development build
npm run web        # Start web development build
npm run lint       # Run ESLint for code quality checks

📝 Implementation Details

Keycloak Service (services/keycloak.ts)

• Singleton pattern for service instance management
• Handles authentication, token exchange, and user session management
• Implements proper error handling and comprehensive logging

Auth Storage (services/auth-storage.ts)

• Secure token storage using Expo Secure Store
• Fallback to AsyncStorage for development environments
• Handles multiple token types (access, refresh, ID tokens)

Login Screen (app/login.tsx)

• Clean UI with loading states and error handling
• Automatic authentication status checking
• Redirects to dashboard after successful login

🧪 Testing the Integration

1. Connection Test: The app automatically tests Keycloak connectivity on startup
2. Authentication Flow: Test the complete OAuth 2.0 flow
3. Token Management: Verify token storage and retrieval
4. User Session: Test login, logout, and session persistence

🔍 Debugging

The app includes comprehensive logging for debugging:

• Authentication flow steps
• Token exchange process
• User information extraction
• Storage operations
• Error details

Check the console logs for detailed information about the authentication process.

📚 Learn More

• Expo Documentation
• Keycloak Documentation
• OAuth 2.0 and OpenID Connect
• Expo Auth Session
• Expo Secure Store

🤝 Contributing

This project serves as a demonstration of Keycloak integration with Expo. Feel free to use it as a reference for your own implementations or suggest improvements.