86 lines
6.5 KiB
Text
Executable file
86 lines
6.5 KiB
Text
Executable file
= Overview
|
|
|
|
Keycloak is an SSO solution for web apps, mobile and RESTful web services.
|
|
It is an authentication server where users can centrally login, logout, register, and manage their user accounts.
|
|
The Keycloak admin UI can manage roles and role mappings for any application secured by Keycloak.
|
|
The Keycloak Server can also be used to perform social logins via the user's favorite social media site i.e.
|
|
Google, Facebook, Twitter etc.
|
|
|
|
Features:
|
|
|
|
* SSO and Single Log Out for browser applications
|
|
* Social Login. Enable Google, GitHub, Facebook, Twitter, and other social providers with no code required.
|
|
* LDAP and Active Directory support.
|
|
* Optional User Registration
|
|
* Password and TOTP support (via Google Authenticator). Client cert auth coming soon.
|
|
* Forgot password support. User can have an email sent to them
|
|
* Reset password/totp. Admin can force a password reset, or set up a temporary password.
|
|
* Not-before revocation policies per realm, application, or user.
|
|
* User session management. Admin can view user sessions and what applications/clients have an access token. Sessions can be invalidated
|
|
per realm or per user.
|
|
* Pluggable theme and style support for user facing screens. Login, grant pages, account mgmt, and admin console all
|
|
can be styled, branded, and tailored to your application and organizational needs.
|
|
* Integrated Browser App to REST Service token propagation
|
|
* OAuth Bearer token auth for REST Services
|
|
* OAuth 2.0 Grant requests
|
|
* OpenID Connect Support.
|
|
* SAML Support.
|
|
* CORS Support
|
|
* CORS Web Origin management and validation
|
|
* Completely centrally managed user and role mapping metadata. Minimal configuration at the application side
|
|
* Admin Console for managing users, roles, role mappings, clients, user sessions and allowed CORS web origins.
|
|
* Account Management console that allows users to manage their own account, view their open sessions, reset passwords, etc.
|
|
* Deployable as a WAR, appliance, or on Openshift. Completely clusterable.
|
|
* Multitenancy support. You can host and manage multiple realms for multiple organizations. In the same auth server
|
|
and even within the same deployed application.
|
|
* Identity brokering/chaining. You can make the Keycloak server a child IDP to another SAML 2.0 or OpenID Connect IDP.
|
|
* Token claim, assertion, and attribute mappings. You can map user attributes, roles, and role names however you want
|
|
into a OIDC ID Token, Access Token, SAML attribute statements, etc. This feature allows you to basically
|
|
tailor however you want auth responses to look.
|
|
* Supports JBoss AS7, EAP 6.x, Wildfly, Tomcat 7, Tomcat 8, Jetty 9.1.x, Jetty 9.2.x, Jetty 8.1.x, and Pure JavaScript applications. Plans to support Node.js, RAILS, GRAILS, and other non-Java deployments
|
|
|
|
== Key Concepts in Keycloak
|
|
|
|
The core concept in Keycloak is a _Realm_.
|
|
A realm secures and manages security metadata for a set of users and registered clients.
|
|
Users can be created within a specific realm within the Administration console.
|
|
Roles (permission types) can be defined at the realm level and you can also set up user role mappings to assign these permissions to specific users.
|
|
|
|
A _client_ is a service that is secured by a realm.
|
|
You will often use Client for every Application secured by Keycloak.
|
|
When a user browses an application's web site, the application can redirect the user agent to the Keycloak Server and request a login.
|
|
Once a user is logged in, they can visit any other client (application) managed by the realm and not have to re-enter credentials.
|
|
This also hold true for logging out.
|
|
Roles can also be defined at the client level and assigned to specific users.
|
|
Depending on the client type, you may also be able to view and manage user sessions from the administration console.
|
|
|
|
In admin console there is switch _Consent required_ specified when creating/editing client.
|
|
When on, the client is not immediately granted all permissions of the user.
|
|
In addition to requesting the login credentials of the user, the Keycloak Server will also display a grant page asking the user if it is ok to grant allowed permissions to the client.
|
|
The granted consents are saved and every user can see his granted consents in Account Management UI and he can also revoke them for particular client.
|
|
Also admin can see and revoke the grants of particular user in Keycloak Admin Console UI.
|
|
|
|
== How Does Security Work in Keycloak?
|
|
|
|
Keycloak uses _access tokens_ to secure web invocations.
|
|
Access tokens contains security metadata specifying the identity of the user as well as the role mappings for that user.
|
|
The format of these tokens is a Keycloak extension to the http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-14[JSON Web Token] specification.
|
|
Each realm has a private and public key pair which it uses to digitally sign the access token using the http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-19[JSON Web Signature] specification.
|
|
Applications can verify the integrity of the digitally signed access token using the public key of the realm.
|
|
The protocols used to obtain this token is defined by the http://tools.ietf.org/html/rfc6749[OAuth 2.0] specification.
|
|
|
|
The interesting thing about using these _smart_ access tokens is that applications themselves are completely stateless as far as security metadata goes.
|
|
All the information they need about the user is contained in the token and there's no need for them to store any security metadata locally other than the public key of the realm.
|
|
|
|
Signed access tokens can also be propagated by REST client requests within an `Authorization` header.
|
|
This is great for distributed integration as applications can request a login from a client to obtain an access token, then invoke any aggregated REST invocations to other services using that access token.
|
|
So, you have a distributed security model that is centrally managed, yet does not require a Keycloak Server hit per request, only for the initial login.
|
|
|
|
=== Permission Scopes
|
|
|
|
Each client is configured with a set of permission scopes.
|
|
These are a set of roles that a client is allowed to ask permission for.
|
|
Access tokens are always granted at the request of a specific client.
|
|
This also holds true for SSO.
|
|
As you visit different sites, the application will redirect back to the Keycloak Server via the OAuth 2.0 protocol to obtain an access token specific to that application (client). The role mappings contained within the token are the intersection between the set of user role mappings and the permission scope of the client.
|
|
So, access tokens are tailor made for each client and contain only the information required for by them.
|