188 lines
10 KiB
XML
Executable file
188 lines
10 KiB
XML
Executable file
<!--
|
|
~ Copyright 2016 Red Hat, Inc. and/or its affiliates
|
|
~ and other contributors as indicated by the @author tags.
|
|
~
|
|
~ Licensed under the Apache License, Version 2.0 (the "License");
|
|
~ you may not use this file except in compliance with the License.
|
|
~ You may obtain a copy of the License at
|
|
~
|
|
~ http://www.apache.org/licenses/LICENSE-2.0
|
|
~
|
|
~ Unless required by applicable law or agreed to in writing, software
|
|
~ distributed under the License is distributed on an "AS IS" BASIS,
|
|
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
~ See the License for the specific language governing permissions and
|
|
~ limitations under the License.
|
|
-->
|
|
|
|
<chapter id="Overview">
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
|
|
|
|
</para>
|
|
<para>
|
|
Features:
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
SSO and Single Log Out for browser applications
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Social Login. Enable Google, GitHub, Facebook, Twitter social login with no code required.
|
|
</listitem>
|
|
|
|
<listitem>
|
|
LDAP and Active Directory support.
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Optional User Registration
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Password and TOTP support (via Google Authenticator). Client cert auth coming soon.
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Forgot password support. User can have an email sent to them
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Reset password/totp. Admin can force a password reset, or set up a temporary password.
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Not-before revocation policies per realm, application, or user.
|
|
</listitem>
|
|
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Integrated Browser App to REST Service token propagation
|
|
</listitem>
|
|
<listitem>
|
|
OAuth Bearer token auth for REST Services
|
|
</listitem>
|
|
<listitem>
|
|
OAuth 2.0 Grant requests
|
|
</listitem>
|
|
<listitem>
|
|
OpenID Connect Support.
|
|
</listitem>
|
|
<listitem>
|
|
SAML Support.
|
|
</listitem>
|
|
<listitem>
|
|
CORS Support
|
|
</listitem>
|
|
<listitem>
|
|
CORS Web Origin management and validation
|
|
</listitem>
|
|
<listitem>
|
|
Completely centrally managed user and role mapping metadata. Minimal configuration at the application side
|
|
</listitem>
|
|
<listitem>
|
|
Admin Console for managing users, roles, role mappings, clients, user sessions and allowed CORS web origins.
|
|
</listitem>
|
|
<listitem>
|
|
Account Management console that allows users to manage their own account, view their open sessions, reset passwords, etc.
|
|
</listitem>
|
|
<listitem>
|
|
Deployable as a WAR, appliance, or on Openshift. Completely clusterable.
|
|
</listitem>
|
|
<listitem>
|
|
Multitenancy support. You can host and manage multiple realms for multiple organizations. In the same auth server
|
|
and even within the same deployed application.
|
|
</listitem>
|
|
<listitem>
|
|
Identity brokering/chaining. You can make the Keycloak server a child IDP to another SAML 2.0 or OpenID Connect IDP.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
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
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section>
|
|
<title>Key Concepts in Keycloak</title>
|
|
<para>
|
|
The core concept in Keycloak is a <emphasis>Realm</emphasis>. 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.
|
|
</para>
|
|
<para>
|
|
A <emphasis>client</emphasis> 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.
|
|
</para>
|
|
<para>
|
|
In admin console there is switch <emphasis>Consent required</emphasis> 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.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>How Does Security Work in Keycloak?</title>
|
|
<para>
|
|
Keycloak uses <emphasis>access tokens</emphasis> 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 <ulink url="http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-14">JSON Web Token</ulink> specification. Each realm has a private and public key pair
|
|
which it uses to digitally sign the access token using the <ulink url="http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-19">JSON Web Signature</ulink> 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
|
|
<ulink url="http://tools.ietf.org/html/rfc6749">OAuth 2.0</ulink> specification.
|
|
</para>
|
|
<para>
|
|
The interesting thing about using these <emphasis>smart</emphasis> 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.
|
|
</para>
|
|
<para>
|
|
Signed access tokens can also be propagated by REST client requests within an <literal>Authorization</literal>
|
|
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.
|
|
</para>
|
|
<section>
|
|
<title>Permission Scopes</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|