2FA Implementation with Keycloak and React

This project demonstrates a secure authentication flow using Keycloak for user authentication and built-in OTP (One-Time Password) for two-factor authentication (2FA).

---

Authentication Flow

1. User visits the Web App (React Frontend)

• Access: http://localhost:3000
• App detects the user is not authenticated
• Displays "Login" button

2. User initiates login

• Clicks "Login" button
• Frontend redirects to Keycloak at http://localhost:8080

3. First Factor: Username/Password

• Keycloak prompts for credentials
• User enters username and password
• Keycloak validates the credentials

4. Second Factor: OTP Authentication

• First-time users:
  • Keycloak shows a QR code
  • User scans it using Google Authenticator, Authy, or similar
  • User enters the initial OTP to complete setup
• Returning users:
  • Keycloak prompts for a 6-digit OTP code
  • User enters code from their authenticator app

5. Authentication Complete

• Keycloak validates OTP
• If valid:
  • Issues JWT access and refresh tokens
  • Redirects user back to the frontend (http://localhost:3000)
  • Frontend stores tokens and updates the UI

---

Protected Resource Access

• Authenticated users can access protected routes (e.g. /secure)
• Frontend sends JWT in API request headers
• Protected content is fetched and displayed

---

Logout Flow

• User clicks "Logout"
• Frontend triggers logout via Keycloak
• Keycloak clears session and redirects to home

---

Technical Components

Frontend (React)

• React + react-router-dom for routing
• @react-keycloak/web for Keycloak integration
• Public and protected routes
• Token handling managed by Keycloak adapter

Authentication Server (Keycloak)

• Manages users, logins, and OTP
• Issues JWT tokens
• Stores user data in PostgreSQL
• Configured with custom realm and client

Database (PostgreSQL)

• Stores Keycloak configuration
• Persists user accounts and OTP metadata

---

Setup Requirements

• Docker and Docker Compose
  • Used for local development and testing
• Authenticator App:
  • Google Authenticator
  • Authy
  • Any TOTP-compatible app

---

Configuration

Keycloak Setup

• Realm: test-realm
• Client: frontend-app
• Authentication Flow: browser with 2fa
• Valid Redirect URIs: http://localhost:3000/*
• Web Origins: http://localhost:3000

Frontend Configuration

• Keycloak settings in keycloak.js
• Configure protected routes and token handling

---

Running the Application

1. Update Keycloak config in the frontend.
2. Use Docker Compose to run:

   docker-compose up --build
   
   
   

---

Keycloak settings

Access Keycloak Admin Console

1. Open your browser and go to:
   http://localhost:8080/admin

2. Login with:

   • Username: admin
   • Password: admin

---

Create a New Realm

1. Hover over the "Master" dropdown in the top-left corner.
2. Click "Create Realm".
3. Set:
   • Name: test-realm
4. Click "Create".

---

Create a Client

1. In the left sidebar, click "Clients".
2. Click "Create client".

Step 1: General Settings

• Client ID: frontend-app
• Client Type: OpenID Connect
• Click Next.

Step 2: Capability Config

• Client Authentication: OFF (turn the switch off)
• Authorization: OFF
• Click Next.

Step 3: Login Settings

• Valid Redirect URIs: http://localhost:3000/*
• Web Origins: http://localhost:3000
• Click Save.

---

Configure Post-Logout Redirect

1. Stay in the client settings for frontend-app.
2. Find the section "Valid post logout redirect URIs".
3. Add: /
4. Click Save.

---

Create a Test User

1. Click "Users" in the left sidebar.
2. Click "Add user".
3. Fill in:
   • Username: testuser
   • Email: [email protected] (optional)
   • First Name: Test (optional)
   • Last Name: User (optional)
4. Click Create.

Set User Credentials

1. Go to the "Credentials" tab.
2. Click "Set password".
3. Enter:
   • Password: testpass
   • Temporary: YES
4. Click Save.
5. Confirm by clicking "Save password".

---

These Settings Enable:

• Frontend app to authenticate via Keycloak
• Proper redirects after login/logout

---

Configure 2FA in Keycloak

Access Keycloak Admin Console

1. Go to: http://localhost:8080/admin
2. Login using admin credentials.
3. Select the realm: test-realm.

---

Create a New Authentication Flow

1. In the left sidebar, go to Authentication.
2. Click on the Flows tab.
3. Click Create flow.
4. Set:
   • Name: browser with 2fa
5. Click Create.

---

Configure Flow Steps

1. With your new flow selected, click Add step.

2. Select Cookie.

3. Set Requirement to ALTERNATIVE.

4. Click Add sub-flow.

   • Name: Forms
   • Flow Type: generic
   • Requirement: ALTERNATIVE

5. Click the + icon next to the newly created Forms sub-flow to expand it.

6. Click Add step:

   • Select: Username Password Form
   • Requirement: REQUIRED

7. Click Add step again:

   • Select: OTP Form
   • Requirement: REQUIRED

---

Set as Default Flow

1. On the same Flows page, click the Actions dropdown.
2. Select Bind flow.
3. Choose Browser flow.
4. Save/Bind the flow.

---

Final Flow Structure Example

Your browser with 2fa flow should look like:

browser with 2fa
├── Cookie (ALTERNATIVE)
└── Forms (ALTERNATIVE)
    ├── Username Password Form (REQUIRED)
    └── OTP Form (REQUIRED)

---

Test the 2FA Setup

First-time Login

1. Go to: http://localhost:3000
2. Click Login.
3. Enter username/password.
4. A QR code will be displayed.
5. Scan the code using Google Authenticator or Authy.
6. Enter the TOTP code shown in your app.
7. You will be logged in.

Subsequent Logins

1. Go to: http://localhost:3000
2. Click Login.
3. Enter username/password.
4. Enter the code from your authenticator app.
5. You will be logged in.

---

Supported Authenticator Apps

• Google Authenticator
• Authy
• Any TOTP-compatible authenticator app

---