Keycloak SPA Integration

This project demonstrates how to integrate Keycloak authentication with a React Single Page Application (SPA) built using Vite, TypeScript, and React.

Overview

This application provides a minimal setup for implementing secure user authentication and authorization in a React application using Keycloak. It demonstrates:

• User authentication with Keycloak
• Retrieving and displaying user information
• Managing authentication state with React Context
• Type-safe integration with TypeScript

Features

• 🔐 Secure authentication using Keycloak
• 🔄 Automatic login redirection
• 👤 User profile information display
• 🚪 Logout functionality
• 📦 Modern React with TypeScript

Prerequisites

• Node.js (v22 or newer)
• A running Keycloak server instance

A sample Keycloak client configuration can be found in the extra/react.json file. You can use this as a reference when setting up your Keycloak client.

Setup and Configuration

1. Clone this repository
2. Install dependencies:

   npm install

3. Create a .env file in the root directory with the following variables:

   VITE_KEYCLOAK_URL=https://your-keycloak-server/auth
   VITE_KEYCLOAK_REALM=your-realm
   VITE_KEYCLOAK_CLIENT_ID=your-client-id
   

Running the Application

Development Mode

npm run dev

This starts the development server with hot module replacement (HMR).

Production Build

npm run build

Preview Production Build

npm run preview

Project Structure

• src/KeycloakProvider.tsx - Context provider that handles Keycloak authentication
• src/App.tsx - Main application component displaying user information
• src/main.tsx - Application entry point

How It Works

1. The application initializes Keycloak in the KeycloakProvider component
2. Users are automatically redirected to the Keycloak login page if not authenticated
3. After successful authentication, user information is extracted from the Keycloak token
4. The application displays user details and provides a logout option

Customization

Changing Authentication Flow

The current implementation uses the login-required mode, which automatically redirects unauthenticated users to the login page. To change this behavior, modify the onLoad parameter in the keycloak.init() method in KeycloakProvider.tsx.

Adding Role-Based Access Control

You can implement role-based access control by checking the user's roles from the Keycloak token. The application already extracts role information from the token.

Troubleshooting

• Initialization Issues: Ensure your Keycloak server is running and accessible
• Authentication Failures: Verify that your realm, client ID, and URLs are correctly configured
• Token Parsing Errors: Check that your client has the correct protocol mappers enabled in Keycloak

Additional Resources

• Keycloak Documentation
• keycloak-js API Documentation
• React Documentation
• Vite Documentation

License

This project is open source and available under the MIT License.