🔐 Keycloak — Foundations, Installation, Security Principles, and Integrations

Intro: Keycloak is one of the most important open-source identity platforms in modern engineering estates. For Product Security, it is valuable not just because it adds login pages or token issuance, but because it centralizes identity, session, and trust decisions that teams otherwise implement badly and repeatedly.

What this page includes

what Keycloak is and where it fits;

the security problems it helps solve;

installation and baseline configuration;

GitLab and AWS integration patterns;

risk notes and practical rollout guidance.

What Keycloak is

Keycloak is an open-source Identity and Access Management platform used to add authentication and authorization to applications and services with less custom identity code. In practice, teams use it for SSO, federation, token issuance, client registration, identity brokering, and account management.

The main philosophy

A good Keycloak deployment tries to move identity from “every app implements auth slightly differently” to “identity is a platform service with explicit trust boundaries.”

That means:

applications should not store passwords themselves if they do not need to;
token and session rules should be centrally managed;
federation and identity brokering should happen in one place;
admin interfaces and public login surfaces should be separated;
client configuration, scopes, and mappers should be reviewed like production config.

Security problems Keycloak helps reduce

Keycloak helps close or reduce these classes of risk:

inconsistent authentication logic across applications;
weak local password storage and session handling in every app;
poor MFA rollout discipline;
duplicated user lifecycle logic and ad hoc federation;
fragile app-specific SSO integrations;
long-lived access patterns without central session control.

It does not remove the need for:

careful authorization design inside applications;
secure reverse proxy and TLS configuration;
secure admin-access design;
token scope, mapper, and client review.

Core concepts that matter most

Realm

A realm is roughly a tenant or security boundary in Keycloak. Each realm contains its own clients, users, roles, groups, flows, and settings.

Client

A client is an application or service that delegates auth to Keycloak. Clients can use OIDC or SAML depending on the integration.

Client scopes and mappers

These shape what claims and metadata appear in tokens. They are powerful and easy to overuse.

Identity providers and brokering

Keycloak can act as a broker in front of upstream IdPs using OIDC or SAML.

Admin console and admin APIs

These are high-value control-plane surfaces and should be separated from public login endpoints.

Fast local installation with Docker

Minimal dev start

docker run -p 127.0.0.1:8080:8080   -e KC_BOOTSTRAP_ADMIN_USERNAME=admin   -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin   quay.io/keycloak/keycloak:26.5.6 start-dev

What this does

binds Keycloak only to loopback on port 8080;
creates the initial bootstrap admin;
starts in development mode.

This is good for learning, local PoCs, and configuration experiments. It is not a production pattern.

First-run admin steps

1. Log in to the admin console

Use the bootstrap admin and immediately plan to rotate the password.

2. Create a dedicated realm

Use the master realm only to manage Keycloak itself, not to host application identities.

3. Create a first non-admin test user

This validates login and token issuance in the right realm.

4. Create a first client

For most modern app integrations, create an OpenID Connect client first.

5. Review client scopes and mappers

Keep tokens small and intentional.

Production baseline configuration

1. Use production mode

bin/kc.sh start

Production mode is intentionally stricter and expects hostname and TLS configuration.

2. Set an explicit hostname

bin/kc.sh start --hostname https://sso.example.com

Do not rely on dynamic hostname resolution in production unless you have a very deliberate proxy design.

3. Put Keycloak behind a reverse proxy

Typical reasons:

stable TLS termination;
clean public URLs;
separation between public and admin surfaces;
better rate limiting and access control.

4. Separate admin and public endpoints

A strong baseline is to expose admin APIs and the admin console on a different hostname or path and block them from the public internet where possible.

5. Use a production-grade database

Do not treat the embedded or local dev posture as acceptable for long-lived production environments.

6. Cluster for availability where needed

Two or more instances are normal for production-grade SSO.

Important UI paths

Realm creation

Current realm -> Create Realm

Client creation

Clients -> Create client

Signature algorithm

Realm Settings -> Tokens -> Default Signature Algorithm

Identity brokering

Identity Providers -> Add provider

Users and credentials

Users -> <user> -> Credentials

Events

Events and Event Config

Practical baseline checklist

Area	Recommended baseline
Public transport	HTTPS only
Hostname	explicit hostname set
Reverse proxy	yes, with header handling reviewed
Admin surface	separate hostname/path and network restriction
Realm design	avoid using `master` for application identities
Client defaults	least scope, minimal mappers
Token signing	public-key algorithms such as RSA
Eventing	admin and auth events reviewed and exported
MFA	enforced for admins and privileged users via the IdP flow
Backups	database and configuration recovery tested

Integration with GitLab

For GitLab Self-Managed, the cleanest modern pattern is usually OpenID Connect with Keycloak as the IdP.

Why teams do this

SSO into GitLab;
central auth and IdP-side MFA;
fewer locally managed identities in GitLab;
easier lifecycle management.

GitLab-side example

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Keycloak",
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer: "https://keycloak.example.com/realms/myrealm",
      client_auth_method: "query",
      discovery: true,
      uid_field: "preferred_username"
    }
  }
]

Keycloak-side notes

create an OIDC client for GitLab;
set valid redirect URIs carefully;
prefer standard code flow;
keep scopes minimal;
review claim mapping for username/email/group handling.

Important compatibility note

GitLab expects HTTPS to the OIDC provider. Also configure Keycloak to use public-key token signing rather than symmetric signing for this style of integration.

Integration with AWS

There are two common AWS patterns, and teams often mix them up.

Pattern A — workforce SSO into AWS

Use this when people log into AWS accounts and apps.

Typical design:

Keycloak acts as the external IdP;
AWS IAM Identity Center consumes federation via SAML 2.0 and provisioning via SCIM where applicable;
users access the AWS access portal with their corporate identities.

Pattern B — federation for web apps or specific AWS trust relationships

Use this when your application or trust model needs an OIDC-compatible IdP relationship.