Skip to content

Home

Jump to bottom
gennady73 edited this page Dec 4, 2025 · 3 revisions

Keycloak-SSO Demo: Workshop

This repository hosts a legacy, functional workshop guide for deploying and configuring Red Hat Single Sign-On (RH-SSO v7.6.x) / Keycloak (v18.x).

Keycloak / RH-SSO Demonstration Project

Welcome to the Keycloak / Red Hat Single Sign-On (RH-SSO) Demonstration Project.

This repository serves as a comprehensive, hands-on workshop designed to bridge the gap between Identity Management Infrastructure and Secure Application Development.

Unlike simple "Hello World" tutorials, this project demonstrates a complete, end-to-end integration scenario. You will learn how to deploy a High-Availability (HA) Identity Provider cluster and use it to secure a distributed application architecture using standard OpenID Connect (OIDC) flows.

Project Status: Foundational / Legacy

This project utilizes Keycloak 18.x (RH-SSO 7.6.4) and focuses on the monolithic "Standalone-HA" deployment model. It serves as the conceptual predecessor to our modern, cloud-native RHBK Multi-Site SSO Workshop.
While the server version is older, the concepts, terminology, and OIDC workflows detailed here remain the industry standard and are essential.

What You Will Learn

This workshop is divided into three distinct perspectives, allowing you to master the full security lifecycle:

1. The Administrator Perspective (Ops)

Learn the "Server Side" of Identity Management.

  • Core Architecture: deploying Keycloak in a clustered mode with an external PostgreSQL database.
  • Realm Management: structuring organizations, users, and roles.
  • Client Configuration: defining OIDC clients, understanding Access Types (Confidential vs. Public), and managing Redirect URIs.

2. The Developer Perspective (Dev)

Learn how to consume Identity in your code.

  • OIDC Workflows: implementing the Authorization Code Flow for browser-based front-ends.
  • API Security: protecting RESTful back-ends by validating JWT Bearer Tokens.
  • Role-Based Access Control (RBAC): extracting claims from tokens to enforce permissions at the code level.

3. Advanced Topics (Architect)

Explore complex deployment patterns and high availability.

  • High-Availability (HA): Understanding the Standalone-HA architecture and clustering mechanisms.
  • Cross-Site Replication: A brief introduction to multi-site deployments and the challenges of active-active configurations (X-Site).

Workshop Structure

Use the sidebar navigation to explore the detailed chapters.

Chapter Focus Files Covered
I. Configuration Guide (Admin) Installation, Core Server Settings, Database Tuning, and Client Registration. docs/keycloak/RHSSO_Configuration_Guide.md
II. Developer Guide (Dev) Step-by-step instructions for integrating OIDC into Front-end and Back-end applications. docs/dev/RHSSO_Developer_Guide.md kc-front-end/README.md kc-back-end/README.md
III. Advanced Topics Exploration of legacy cross-site (xsite) replication concepts and database strategies. docs/xsite/README.md

🔗 Related Projects

  • Modern Evolution: For Red Hat Build of Keycloak (v26+), Cross-Site Replication, and OpenShift/Kubernetes deployments, please visit the RHBK Multi-Site SSO Workshop.

NOTE: This project uses older Keycloak versions(up to v.18) and serves as the conceptual predecessor to the RHBK Multi-Site SSO Workshop.

I. Configuration Guide (RHSSO Administrator Context)

Terminology

Getting started

The workflows

  • Keycloak client types

  • The Keycloak Realm overview: relations between Roles, Groups, Users, and Cliens.

  • Workflow: Web application (Front-end)

    • Case: The front-end application and the back-end service.
      • Public client definition
    • Case: The frontend and several back-end services

  • Workflow: Machine to machine communication(M2M)

    • Confidential client overview.

    • Bearer-only client overview.

    • The Service account setup.

    • The M2M Interaction Closeup.

    • Case: The front-end and several back-end services.

      • Front-End: public client.
      • Back-end "service A": Bearer-only client.
      • Back-end "service B": Confidential client.

Oauth2 Proxy - The alternative (code-free) workflow.

  • Workflow: Web application with Front-end and/or Backend
  • Browser based flow explanation
  • Keycloak settings example
  • Oauth2 Proxy settings example

II. Developer Guide (Application Developer Context)

Terminology

Getting started

The workflows

  • Workflow: Web application (Front-end)

    • Case: The front-end application and the back-end service.
      • Frontend OIDC Integration, code closeup.
      • Backend API Security, code closeup.

  • Workflow: Machine to machine communication(M2M)

    • Case: application which consists of a front-end and several back-end services

    • Confidential client overview.

    • Bearer-only client overview.

    • The M2M Interaction Closeup.

    • The Service account

    • Keycloak API call delegation, code closeup.

    • Case: The front-end and several back-end services.

      • Front-End: public client.
      • Back-end "service A": Bearer-only client.
      • Back-end "service B": Confidential client.
      • Keycloak API call delegation: The "service account" vs "role overriding" approach, code closeup.

Oauth2 Proxy - The alternative (code-free) workflow.

  • Workflow: Web application with Front-end and/or Backend
  • Keycloak settings summary
  • Oauth2 Proxy settings summary

III. Red Hat Single Sign-On (RHSSO) High-Availability

This chapter explores advanced deployment scenarios for RH-SSO (Keycloak 7.6.x), focusing on clustering, resilience, and the architectural challenges of multi-site deployments.

Note: This content reflects legacy architectures. For modern, cloud-native HA, please refer to the RHBK Multi-Site SSO Workshop.

Introduction

Prerequisites

Configuration Management in Clustered Deployments

Discussing the risks of operating two separate clusters in Active-Active mode without synchronous replication.

Domain Mode

Understanding the requirements for a single, centralized relational database (PostgreSQL) shared by all cluster nodes to maintain data consistency.

High Availability (HA) Mode with External Infinispan and Shared PostgreSQL Database

High-Availability (HA) Mode with External Infinispan and Multi-Master MariaDB/Galera Cluster

An overview of database-level replication options (e.g., Galera) required to support a multi-site RH-SSO deployment.

Load Balancer Configuration

  • Build the HAProxy Image
  • Run the HAProxy Container

Realm Management

  • Export Realm Configuration
  • Import Realm Configuration

Infinispan

  • Prerequisites
  • Relations in deployment
  • Sites configurations
  • Network configuration

The Infinispan cross-site configuration - run

  • Cache configuration
  • Docker compose file
  • Storage
  • Run the cluster containers

Clone this wiki locally