Brief Introduction about Keycloak
Keycloak is an open source solution for user identity and access management that you can self-host. It makes securing your applications and services easier with minimal effort. You don’t need to deal with storing or authenticating users as everything is available out of the box. Keycloak offers the following features:
- Single sign-on and single logout
- Support for standard protocols such as OpenID Connect (OIDC), OAuth 2.0, and SAML 2.0
- Flexible authentication and authorization
- Multi-factor authentication (MFA) such as one-time passwords (OTP)
- Social logins such as Google, Facebook, and Twitter
- Centralized user management
- Support for directory services such as LDAP and Active Directory
- Customization and extensibility
- Easy setup and integration using provided client adapters.
Keycloak Core Concepts and Architecture
A Keycloak realm is like a namespace that allows you to manage all of your metadata and configurations. You can create as many realms as you like. The default realm is called master
which is dedicated to manage Keycloak and should not be used for your own applications. Basically you need to create a new realm to get started. Following are the entities that being managed by a single realm:-
- Clients
- Roles
- Identity Providers (OIDC 1.0, Keycloak OIDC, SAML 2.0, Social Logins)
- User Federation (Kerberos, LDAP)
- Authentication configurations
- User Management (Groups, Users)
- UI Themes
- Realm settings
Following image illustrates the architecture of Keycloak software;
User Authentication using Keycloak
Keycloak as Identity Provider to Frontend Application
Following image illustrates how a user is authenticated when accessing the frontend application;
SSO Integration
Web SSO is the most useful feature where you login once to access all applications. Keycloak also supports single logout that can be propagated to all clients. This works for web, mobile and desktop applications.
Following image illustrates the authentication flow of a logged-in user accessing another frontend application;
How backend services work with Keycloak
Following image illustrates the flow on how the backend services work with Keycloak to validate the access token;
Understanding Keycloak Tokens
Keycloak works based on tokens. Following are the few things that describe a token in Keycloak, especially for OAuth2 and OIDC protocol:
- The token is a signed self-contained JSON Web Token (JWT).
- The token contains claims that hold metadata and user information.
- The token is issued by Keycloak that is signed with a realm private key.
- The token is verified using the realm public key.
- The token has limited lifespan which is revokable.
Following are the available types of token when authenticating with Keycloak:
Access token | Usually it has short-lived lifespan (minutes) and it is used for accessing resources. |
Refresh token | Usually it has long-lived lifespan (days) and it is used for requesting new tokens. |
Offline token | A special refresh token that “never” expires. |
ID token | Contains information about user (used by OIDC). |
Example Screenshots of Keycloak UI
Keycloak Admin Console

Keycloak User Account Console

Keycloak Admin REST API Examples
These are the most common REST APIs that I used for applications. To learn more about what else that’s available, please check out Keycloak Admin REST API documentation page.
Authenticate as Keycloak Admin
curl --location --request POST '<KEYCLOAK_SERVER>/auth/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<KEYCLOAK_ADMIN_USER>' \
--data-urlencode 'password=<KEYCLOAK_ADMIN_PASS>' \
--data-urlencode 'client_id=admin-cli'
Get user list executed from a specific user account
Following are the prerequisite steps that needed to be applied on Keycloak Admin Console:
- From a selected realm, go to Manage ⟶ Users.
- To apply for a specific user, click on “View all users” button then click on selected user ID.
- Go to Role Mappings tab, select
realm-management
from the Client Roles. - Scroll down in Available Roles, find
view-users
and add it into Assigned Roles.
Alternatively, this can be applied as a default value for all newly registered users;
- From a selected realm, go to Manage ⟶ Roles.
- Select
realm-management
from the Client Roles. - Scroll down in Available Roles, find
view-users
and add it into Client Default Roles.
Get the access token:
curl --location --request POST '<KEYCLOAK_SERVER>/auth/realms/<REALM>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<USERNAME>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'
Use the access token to get the user list:
curl --location --request GET '<KEYCLOAK_SERVER>/auth/admin/realms/<REALM>/users' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Get a specific user info
Get the access token:
curl --location --request POST '<KEYCLOAK_SERVER>/auth/realms/<REALM>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<USERNAME>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'
Grab the user ID and use it to get the respective user info:
curl --location --request GET 'https://<KEYCLOAK_SERVER>/auth/admin/realms/<REALM>/users/<USER_ID>' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Get user roles from a specific user
Get the access token:
curl --location --request POST '<KEYCLOAK_SERVER>/auth/realms/<REALM>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<USERNAME>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'
Grab the user ID and use it get the user roles:
curl --location --request GET '<KEYCLOAK_SERVER>/auth/admin/realms/<REALM>/users/<USER_ID>/role-mappings' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Quick Deployment of Keycloak via Docker Compose
Example of docker-compose.yml
file:
version: '3.5'
volumes:
pgkeycloak-data:
name: acme_pgkeycloak-data
networks:
acme:
driver: bridge
name: acme_network
services:
pgkeycloak:
image: postgres:12-alpine
container_name: keycloak_database
volumes:
- pgkeycloak-data:/var/lib/postgresql/data
environment:
POSTGRES_DB: keycloak
POSTGRES_USER: keycloakdb
POSTGRES_PASSWORD: ${KEYCLOAK_DB_PASSWORD}
ports:
- "5432:5432"
networks:
- acme
keycloak:
container_name: keycloak_service
image: keycloak:latest
environment:
KEYCLOAK_USER: ${KEYCLOAK_ADMIN_USER}
KEYCLOAK_PASSWORD: ${KEYCLOAK_ADMIN_PASS}
PROXY_ADDRESS_FORWARDING: "true"
DB_USER: keycloakdb
DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD}
DB_DATABASE: keycloak
DB_ADDR: pgkeycloak
DB_VENDOR: postgres
DB_SCHEMA: public
ports:
- "8080:8080"
- "8443:8443"
networks:
- acme
depends_on:
- pgkeycloak
You can use following docker-compose CLI to get started:
$ docker-compose -f path/to/docker-compose.yml up -d
There are a lot of great resources that you could find online (simply google it) to learn more about Keycloak, and the best way to start is to visit its official website.