Keycloak

Deploy and Host Keycloak on Sealos

Keycloak is an open-source identity and access management platform for securing applications and services. This template deploys Keycloak 26.7.0 with a persistent KubeBlocks PostgreSQL 16.4 database on Sealos.

About Hosting Keycloak

Keycloak provides centralized sign-in, single sign-on, user federation, identity brokering, multi-factor authentication, and standards-based OpenID Connect, OAuth 2.0, and SAML integration. A realm isolates users, clients, roles, groups, authentication policies, and sessions for one organization or environment.

This template creates a public HTTPS endpoint for the Keycloak Admin Console and authentication APIs. Realm configuration and identity data are stored in PostgreSQL so they survive application restarts.

Common Use Cases

• Single sign-on: Use one identity provider across internal and customer-facing applications.
• Application authentication: Add OpenID Connect, OAuth 2.0, or SAML to web and mobile applications.
• Identity federation: Connect LDAP, Active Directory, social providers, and external OpenID Connect or SAML providers.
• Centralized access control: Manage users, groups, roles, sessions, and authentication policies from one console.
• Multi-tenant identity: Separate organizations or environments with independent realms.

Dependencies for Keycloak Hosting

The Sealos template provisions:

• Keycloak 26.7.0
• KubeBlocks PostgreSQL 16.4 with persistent storage
• A database initialization Job
• Public HTTPS ingress and a Sealos Canvas application entry

Deployment Dependencies

• Keycloak documentation - Server and administration guides
• Keycloak GitHub repository - Source code and release information
• Sealos App Store - One-click application deployment

Implementation Details

Architecture Components

• Keycloak StatefulSet: Runs the identity server, Admin Console, authentication endpoints, and account console.
• PostgreSQL Cluster: Stores realms, users, clients, roles, credentials, sessions, and configuration.
• Database initialization Job: Waits for PostgreSQL and idempotently creates the keycloak database.
• Ingress and App resources: Publish Keycloak through HTTPS and add it to the Sealos Canvas.

Keycloak connects to PostgreSQL through the credentials generated by KubeBlocks. Health checks use Keycloak's management port and the official /health/started, /health/ready, and /health/live endpoints.

Resource Profile

The template was live-tested with this minimum resource profile:

A 100m Keycloak CPU limit produced recurring blocked-thread warnings during cold start. The 200m / 1024Mi profile completed database migration, administrator login, realm creation, user creation, a random 404 request, and a stable log window with zero restarts. Larger realms and higher authentication traffic should receive additional CPU and PostgreSQL capacity.

License Information

Keycloak is licensed under the Apache License 2.0. This Sealos template packages deployment configuration and keeps the upstream license unchanged.

Why Deploy Keycloak on Sealos?

• One-click deployment: Create Keycloak and PostgreSQL together from the App Store.
• Managed database: KubeBlocks provisions PostgreSQL credentials, storage, and lifecycle resources.
• Persistent identity data: Realm and user data remain in PostgreSQL across Keycloak restarts.
• Public HTTPS access: Sealos provisions ingress and TLS for the Admin Console and authentication endpoints.
• Health-aware startup: Database gates and official health endpoints keep traffic away until Keycloak is ready.
• Simple operations: Inspect logs, adjust resources, and manage the deployment from the Sealos Canvas.

Deployment Guide

1. Open the Keycloak template and click Deploy Now.
2. Enter an initial administrator username and a strong administrator password. Save both values in a password manager.
3. Click Deploy and wait for PostgreSQL initialization and Keycloak cold start. The first deployment can take several minutes.
4. Open the Keycloak entry from the Sealos Canvas.
5. Select Administration Console, then sign in with the administrator credentials entered during deployment.

Login and User Registration

Initial Administrator Login

The admin_username and admin_password deployment inputs create a temporary bootstrap administrator in the master realm. Open https://<app-host>/admin/ and sign in with these values.

Use the bootstrap account to create a permanent server administrator:

1. Select the master realm.
2. Open Users, select Add user, and create the permanent administrator.
3. Open the new user's Credentials tab and set a permanent password.
4. Open Role mapping, assign the admin realm role, and verify the account in a new browser session.
5. Delete the temporary bootstrap administrator after the permanent account works.

The master realm manages the Keycloak server. Create separate realms for application users and clients.

Application Users

Create users from Users inside the target realm. Realm administrators control self-service registration through Realm settings > Login > User registration. Each application integrates with a client created in its realm and uses that realm's OpenID Connect, OAuth 2.0, or SAML endpoints.

Configuration

The public application URL is generated by Sealos and configured as Keycloak's hostname. PostgreSQL connection values come from the KubeBlocks credential Secret.

Scaling

1. Open the Keycloak deployment in the Sealos Canvas.
2. Increase Keycloak CPU for faster startup and higher login throughput.
3. Increase Keycloak memory for larger caches, more realms, or additional providers.
4. Increase PostgreSQL resources and storage as identity data and session volume grow.

This template uses one Keycloak replica and one PostgreSQL replica. Production environments with strict availability objectives should plan a tested multi-replica Keycloak and highly available PostgreSQL topology.

Troubleshooting

Admin Console is still starting

• Wait for the Keycloak resource card to report Ready; cold start includes server augmentation and database migration.
• Inspect the Keycloak startup logs in the Sealos Canvas.
• Confirm that the PostgreSQL resource card is Running.

Administrator login fails

• Use the exact admin_username and admin_password values entered during deployment.
• Confirm the login page uses the master realm.
• After creating a permanent administrator, verify that the account has the admin realm role.

Application redirect or issuer URL is incorrect

• Configure the client with the public HTTPS Keycloak URL shown in the Sealos Canvas.
• Set the application's redirect URI and web origin in the client configuration.
• Use the realm issuer URL: https://<app-host>/realms/<realm-name>.

Realm users cannot register

• Open the target realm and enable Realm settings > Login > User registration.
• Review email verification, password policy, and required action settings for that realm.

Database-related startup errors

• Confirm that the KubeBlocks PostgreSQL cluster is Running.
• Check the database initialization Job and Keycloak init container logs.
• Verify that the PostgreSQL persistent volume has available capacity.

Additional Resources

• Keycloak website
• Keycloak Server Administration Guide
• Keycloak Server Guide
• Keycloak GitHub
• Sealos documentation

License

This Sealos template follows the templates repository license. Keycloak is licensed under the Apache License 2.0.