Blog / Tutorials

Getting Started with Keycloak in 2026: The Modern Guide

Guilliano Molaire May 16, 2026 Updated May 18, 2026 9 min read

Last updated: March 2026

Keycloak is the most widely deployed open-source identity and access management solution. It handles authentication, authorization, and user management so you do not have to build these from scratch. This guide takes you from zero to a working Keycloak setup with a connected React application in about 30 minutes.

We will cover installation, the admin console, creating your first realm and client, user management, connecting a React single-page application, adding Google social login, and basic theme customization. By the end, you will have a working authentication system that you can extend for production use.

What You Need

Docker installed on your machine (get Docker)
Node.js 18+ and npm (get Node.js)
A code editor
A web browser

No Java or Keycloak experience required. For the full reference, see the official Keycloak documentation.

Step 1: Start Keycloak with Docker

The fastest way to run Keycloak is with a single Docker command:

docker run -d 
  --name keycloak 
  -p 8080:8080 
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin 
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin 
  quay.io/keycloak/keycloak:26.0 
  start-dev

This starts Keycloak in development mode with:

Admin username: admin
Admin password: admin
Admin Console available at: http://localhost:8080/admin

Wait about 30 seconds for Keycloak to start, then open http://localhost:8080/admin in your browser and log in with the admin credentials.

For a more complete Docker setup with PostgreSQL and persistent storage, use our Docker Compose Generator or see our Docker Compose guide.

Step 2: Tour the Admin Console

After logging in, you will see the Keycloak Admin Console. Here are the key areas:

Realm Selector (Top Left)

The dropdown in the top-left corner shows the current realm. You start in the master realm, which is for Keycloak administration only. You will create a new realm for your application.

Main Navigation

Realm settings: Configure realm-level settings (login, email, tokens, security)
Clients: Applications that use Keycloak for authentication
Client scopes: Groups of protocol mappers (claims) that clients can request
Realm roles: Roles that apply across all clients
Users: User management (create, edit, delete, view sessions)
Groups: Organize users into groups
Sessions: View and manage active user sessions
Events: Authentication events and admin activity logs
Identity providers: External authentication sources (Google, GitHub, SAML IdPs)
User federation: Connect external user directories (LDAP, Active Directory)

Step 3: Create Your First Realm

The master realm is for Keycloak administration. Always create a separate realm for your application.

Click the realm name dropdown (top-left, shows “master”)
Click Create realm
Set Realm name to my-app
Leave Enabled toggled on
Click Create

You are now in the my-app realm. All subsequent configuration happens here.

Configure Realm Settings

Go to Realm settings and review these tabs:

Login tab:

User registration: Enable if you want a self-service registration form
Forgot password: Enable so users can reset their passwords
Email as username: Enable for a simpler login experience
Login with email: Enable (allows login with email instead of username)
Verify email: Enable for production

Email tab (optional for development):
For development, you can skip email configuration. For production, configure an SMTP server so Keycloak can send verification and password reset emails.

Tokens tab:

Access Token Lifespan: 5 minutes (default, good for most apps)
SSO Session Idle: 30 minutes
SSO Session Max: 10 hours

These defaults are reasonable for getting started. See our guide on 8 default configurations to adjust for production tuning.

Step 4: Create Your First Client

A “client” in Keycloak represents an application that uses Keycloak for authentication.

Go to Clients > Create client
Client type: OpenID Connect
Client ID: react-app
Click Next
Client authentication: Off (this is a public client, since SPAs cannot store secrets)
Standard flow: Enabled
Direct access grants: Off
Click Next
Root URL: http://localhost:5173 (Vite’s default dev server port)
Valid redirect URIs: http://localhost:5173/*
Valid post logout redirect URIs: http://localhost:5173/*
Web origins: http://localhost:5173
Click Save

You can also generate client configurations using the Keycloak Config Generator.

Step 5: Create Your First User

Go to Users > Add user
Username: testuser
Email: [email protected]
Email verified: Toggle on
First name: Test
Last name: User
Click Create

Now set a password:

Go to the Credentials tab
Click Set password
Enter a password (e.g., test1234)
Temporary: Toggle off (so the user is not forced to change it on first login)
Click Save and confirm

Step 6: Connect a React Application

Now let us build a React application that uses Keycloak for authentication.

Create the React App

npm create vite@latest keycloak-demo -- --template react
cd keycloak-demo
npm install
npm install keycloak-js

Configure Keycloak Client

Create a Keycloak configuration file:

// src/keycloak.js
import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
  url: 'http://localhost:8080',
  realm: 'my-app',
  clientId: 'react-app'
});

export default keycloak;

Update the App Component

Replace the default App.jsx:

// src/App.jsx
import { useEffect, useState } from 'react';
import keycloak from './keycloak';

function App() {
  const [authenticated, setAuthenticated] = useState(false);
  const [initialized, setInitialized] = useState(false);
  const [userInfo, setUserInfo] = useState(null);

  useEffect(() => {
    keycloak
      .init({
        onLoad: 'check-sso',
        pkceMethod: 'S256',
        checkLoginIframe: false
      })
      .then((auth) => {
        setAuthenticated(auth);
        setInitialized(true);

        if (auth) {
          setUserInfo({
            name: keycloak.tokenParsed?.name,
            email: keycloak.tokenParsed?.email,
            username: keycloak.tokenParsed?.preferred_username,
            roles: keycloak.tokenParsed?.realm_access?.roles || []
          });

          // Auto-refresh token
          setInterval(() => {
            keycloak.updateToken(30).catch(() => {
              console.log('Failed to refresh token, logging out');
              keycloak.logout();
            });
          }, 10000);
        }
      })
      .catch((err) => {
        console.error('Keycloak init failed:', err);
        setInitialized(true);
      });
  }, []);

  if (!initialized) {
    return <div style={{ padding: '2rem' }}>Initializing authentication...</div>;
  }

  if (!authenticated) {
    return (
      <div style={{ padding: '2rem', fontFamily: 'system-ui' }}>
        <h1>Keycloak Demo</h1>
        <p>You are not logged in.</p>
        <button
          onClick={() => keycloak.login()}
          style={{
            padding: '0.75rem 1.5rem',
            fontSize: '1rem',
            cursor: 'pointer',
            background: '#3b82f6',
            color: 'white',
            border: 'none',
            borderRadius: '6px'
          }}
        >
          Sign In
        </button>
        <button
          onClick={() => keycloak.register()}
          style={{
            padding: '0.75rem 1.5rem',
            fontSize: '1rem',
            cursor: 'pointer',
            background: 'transparent',
            color: '#3b82f6',
            border: '1px solid #3b82f6',
            borderRadius: '6px',
            marginLeft: '1rem'
          }}
        >
          Register
        </button>
      </div>
    );
  }

  return (
    <div style={{ padding: '2rem', fontFamily: 'system-ui' }}>
      <h1>Welcome, {userInfo?.name || userInfo?.username}!</h1>

      <div style={{
        background: '#f8fafc',
        padding: '1.5rem',
        borderRadius: '8px',
        marginBottom: '1.5rem'
      }}>
        <h2>User Info</h2>
        <p><strong>Username:</strong> {userInfo?.username}</p>
        <p><strong>Email:</strong> {userInfo?.email}</p>
        <p><strong>Roles:</strong> {userInfo?.roles?.join(', ')}</p>
      </div>

      <div style={{
        background: '#f8fafc',
        padding: '1.5rem',
        borderRadius: '8px',
        marginBottom: '1.5rem'
      }}>
        <h2>Access Token (decoded)</h2>
        <pre style={{
          background: '#1e293b',
          color: '#e2e8f0',
          padding: '1rem',
          borderRadius: '6px',
          overflow: 'auto',
          fontSize: '0.85rem'
        }}>
          {JSON.stringify(keycloak.tokenParsed, null, 2)}
        </pre>
      </div>

      <div>
        <button
          onClick={() => keycloak.accountManagement()}
          style={{
            padding: '0.75rem 1.5rem',
            cursor: 'pointer',
            background: '#6b7280',
            color: 'white',
            border: 'none',
            borderRadius: '6px'
          }}
        >
          Manage Account
        </button>
        <button
          onClick={() => keycloak.logout({ redirectUri: 'http://localhost:5173/' })}
          style={{
            padding: '0.75rem 1.5rem',
            cursor: 'pointer',
            background: '#ef4444',
            color: 'white',
            border: 'none',
            borderRadius: '6px',
            marginLeft: '1rem'
          }}
        >
          Sign Out
        </button>
      </div>
    </div>
  );
}

export default App;

Run the Application

npm run dev

Open http://localhost:5173 in your browser. Click Sign In, and you will be redirected to Keycloak’s login page. Enter the credentials for the test user you created (testuser / test1234). After logging in, you will be redirected back to the React app with your user information displayed.

You can inspect the access token structure using the JWT Token Analyzer by copying the raw token from Keycloak.

Step 7: Add Roles and Permissions

Roles allow you to control what authenticated users can do in your application.

Create Realm Roles

Go to Realm roles > Create role
Create roles: user, editor, admin
Click Save for each

Assign Roles to Users

Go to Users > select testuser
Go to Role mapping > Assign role
Select user and editor
Click Assign

Use Roles in Your Application

After assigning roles, they appear in the access token under realm_access.roles. Update your React app to check roles:

function ProtectedContent({ keycloak }) {
  const roles = keycloak.tokenParsed?.realm_access?.roles || [];
  const isAdmin = roles.includes('admin');
  const isEditor = roles.includes('editor');

  return (
    <div>
      {isEditor && (
        <div>
          <h3>Editor Panel</h3>
          <p>You have editor access.</p>
        </div>
      )}
      {isAdmin && (
        <div>
          <h3>Admin Panel</h3>
          <p>You have admin access.</p>
        </div>
      )}
      {!isEditor && !isAdmin && (
        <p>You have basic user access.</p>
      )}
    </div>
  );
}

For more advanced role-based access control patterns, see our RBAC feature page and our guide on understanding RBAC.

Step 8: Add Google Social Login

Social login lets users authenticate with their existing accounts instead of creating new credentials.

Create Google OAuth Credentials

Go to Google Cloud Console
Create a new project or select an existing one
Go to APIs & Services > Credentials > Create Credentials > OAuth Client ID
Application type: Web application
Authorized redirect URIs: http://localhost:8080/realms/my-app/broker/google/endpoint
Copy the Client ID and Client Secret

Configure Google IdP in Keycloak

In the Keycloak Admin Console (realm my-app), go to Identity providers
Select Google from the provider list
Enter the Client ID and Client Secret from Google
Default scopes: openid email profile
Click Save

Now when users click “Sign In,” they will see a “Google” button on the Keycloak login page.

First Login Flow

When a user logs in with Google for the first time, Keycloak runs a “First Login Flow” that determines whether to:

Create a new account
Link to an existing account (based on email match)
Prompt the user to choose

The default behavior links to an existing account if the email matches, or creates a new account otherwise.

For configuring additional identity providers like GitHub, Microsoft, Apple, and SAML-based enterprise IdPs, see our guides on integrating GitHub social login and setting up Entra ID SAML.

Step 9: Basic Theme Customization

Keycloak’s default login page works, but you will want to brand it for your application. Keycloak themes control the look and feel of login, registration, account management, and email templates.

Quick Customization via Admin Console

For simple changes (logo, colors), you can customize within the Admin Console:

Go to Realm settings > Themes
Select themes for Login, Account, Admin, and Email

Custom Theme with CSS

For deeper customization, create a theme directory:

# Create theme structure
mkdir -p themes/my-theme/login/resources/css

Create a custom stylesheet:

/* themes/my-theme/login/resources/css/custom.css */
:root {
  --pf-global--primary-color--100: #3b82f6;
  --pf-global--primary-color--200: #1e40af;
}

.login-pf body {
  background: linear-gradient(135deg, #0f172a 0%, #1e293b 100%);
}

.card-pf {
  border-radius: 12px;
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3);
}

#kc-header-wrapper {
  font-size: 1.5rem;
  color: #ffffff;
}

Create a theme.properties file:

# themes/my-theme/login/theme.properties
parent=keycloak.v2
import=common/keycloak

styles=css/custom.css

Mount the theme directory when running Keycloak:

docker run -d 
  --name keycloak 
  -p 8080:8080 
  -v $(pwd)/themes/my-theme:/opt/keycloak/themes/my-theme 
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin 
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin 
  quay.io/keycloak/keycloak:26.0 
  start-dev

Then select your theme in Realm settings > Themes > Login theme: my-theme.

For a complete guide on Keycloak theming and branding, see our branding feature page.

Step 10: Add Multi-Factor Authentication

Adding MFA significantly improves security. Keycloak supports TOTP (Google Authenticator, Authy), WebAuthn (passkeys, security keys), and recovery codes.

Enable TOTP

Go to Authentication > Required Actions
Find Configure OTP and toggle Default Action to on (this requires all new users to set up TOTP)

Or make it optional and let users enable it themselves:

Leave Default Action off
Users can enable TOTP from their Account Console at http://localhost:8080/realms/my-app/account

Conditional MFA

For more sophisticated MFA policies (e.g., require MFA only for admin users, or only from unknown devices), configure conditional authentication flows. See our MFA feature page and our guide on passwordless authentication with passkeys.

What to Learn Next

You now have a working Keycloak setup with a connected React app, social login, roles, and the foundation for MFA. Here are the next steps depending on your use case:

For Backend Integration

For Production Deployment

For Advanced Features

For Understanding the Concepts

For a comprehensive reference, the Keycloak documentation covers every feature in detail.

Skip the Infrastructure Work

If you want to use Keycloak without managing servers, databases, TLS certificates, backups, and upgrades, Skycloak provides fully managed Keycloak hosting. You get a production-ready Keycloak instance in minutes with built-in monitoring, automatic updates, and 99.9% uptime SLA. Check our pricing to find the right plan for your team.

Written by Guilliano Molaire Founder

Guilliano is the founder of Skycloak and a cloud infrastructure specialist with deep expertise in product development and scaling SaaS products. He discovered Keycloak while consulting on enterprise IAM and built Skycloak to make managed Keycloak accessible to teams of every size.

View all posts

Ready to simplify your authentication?

Deploy production-ready Keycloak in minutes. Unlimited users, flat pricing, no SSO tax.

Start Free Trial Talk to Sales