# Keycloak — Foundations, Installation, 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

```bash
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

```bash
bin/kc.sh start
```

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

### 2. Set an explicit hostname

```bash
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

```ruby
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.

Typical design:

* create an AWS IAM OIDC provider;
* define IAM roles that trust the external issuer;
* scope trust with `aud`, `iss`, and claim conditions.

### Example IAM trust policy for an external OIDC provider

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/sso.example.com/realms/engineering"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "sso.example.com/realms/engineering:aud": "aws-client"
        },
        "StringLike": {
          "sso.example.com/realms/engineering:sub": "team:*"
        }
      }
    }
  ]
}
```

### Which AWS integration is usually better?

* for **human workforce access**, start with **IAM Identity Center + SAML/SCIM**;
* for **application federation**, evaluate **IAM OIDC provider** patterns.

## Common mistakes

* using the `master` realm for everything;
* exposing the admin console on the same public surface as login flows;
* overloading tokens with too many claims and mappers;
* using weak or inconsistent redirect-URI policy;
* letting every app team create arbitrary scopes and mappers without review;
* assuming Keycloak solves authorization design inside the application;
* running long-lived production on dev-style startup defaults.

## Suggested rollout order

1. decide whether Keycloak is for workforce SSO, app auth, or both;
2. design realm boundaries before onboarding many apps;
3. harden hostname, TLS, reverse proxy, and admin exposure;
4. onboard one low-risk OIDC client first;
5. standardize client scopes and mapper patterns;
6. add GitLab or another high-value platform integration;
7. only then scale to broader federation.

## Related pages

* [🤖 Workload Federation and Non-Human Identities](/architecture-api-crypto-and-identity/index-2/workload-federation-and-non-human-identities.md)
* [🔐 GitHub, GitLab, and Cloud Trust Patterns](/architecture-api-crypto-and-identity/index-2/github-gitlab-oidc-and-cloud-trust-patterns.md)
* [⏱️ JIT, PAM, Break-Glass, and Admin Access](/architecture-api-crypto-and-identity/index-2/jit-pam-break-glass-and-admin-access.md)
* [🔗 Service-to-Service Auth, Webhooks, and Event-Driven Security](/architecture-api-crypto-and-identity/index-1/service-to-service-auth-webhooks-and-event-driven-security.md)

\---*Author attribution: Ivan Piskunov, 2026 - Educational and defensive-engineering use.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.product-security.expert/architecture-api-crypto-and-identity/index-2/keycloak-foundations-installation-and-integrations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.