libre.sh/keycloak-scim
4
0
Fork 0
Code Issues 15 Pull requests Releases 1 Activity Actions

overview

Browse source
This commit is contained in:
Bill Burke 2016-05-12 17:48:03 -04:00
parent 79b2c295e4
commit c3a793de31
10 changed files with 305 additions and 133 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
SUMMARY.adoc
View file

@ -1,13 +1,13 @@
== Keycloak Reference Guide = {{book.title}}
//. link:topics/templates/document-attributes.adoc[] //. link:topics/templates/document-attributes.adoc[]
:imagesdir: images :imagesdir: images
. link:topics/preface.adoc[Preface] . link:topics/preface.adoc[Preface]
. link:topics/Overview.adoc[Overview] . link:topics/overview.adoc[Overview]
.. link:topics/overview_key_concepts.adoc[Key Concepts in Keycloak] .. link:topics/features.adoc[Features]
.. link:topics/overview_How_Security_Work_in_Keycloak.adoc[How Security Work in Keycloak?] .. link:topics/how.adoc[How Does Security Work?]
... link:topics/overview_permission_scopes.adoc[Permission Scopes] .. link:topics/concepts.adoc[Core Concepts and Terms]
. link:topics/admin-permissions.adoc[Master Admin Access Control] . link:topics/admin-permissions.adoc[Master Admin Access Control]
. link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control] . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
. link:topics/client-registration.adoc[Client Registration] . link:topics/client-registration.adoc[Client Registration]

76
book.json Executable file
View file

@ -0,0 +1,76 @@
{
"gitbook": "2.x.x",
"structure": {
"readme": "README.adoc"
},
"plugins": [
"toggle-chapters",
"ungrey",
"splitter"
],
"variables": {
"title": "Keycloak Administration Guide",
"community": true,
"product": false,
"images": "keycloak-images",
"appserver": {
"name": "Wildfly",
"version": "10",
"admindoc": {
"name": "JBoss EAP Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/"
},
"datasource": {
"name": "JBoss EAP Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/chap-Datasource_Management.html"
},
"network": {
"name": "JBoss EAP Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/chap-Network_and_Port_Configuration.html#Configure_interfaces"
},
"socket": {
"name": "JBoss EAP Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/sect-Socket_Binding_Groups.html"
},
"loadbalancer": {
"name": "JBoss EAP Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/sect-Web_HTTP_Connectors_and_HTTP_Clustering.html"
},
"jgroups": {
"name": "JBoss EAP Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/sect-JGroups.html"
}
},
"caching": {
"name": "JBoss Data Grid",
"version": "???",
"admindoc": {
"name": "JBoss Data Grid Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html/Administration_and_Configuration_Guide/index.html",
"eviction": "https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/7.0/html/Administration_and_Configuration_Guide/sect-Eviction_Strategies.html"
}
},
"jpa": {
"name": "Hibernate",
"version": "???",
"admindoc": {
"name": "JBoss Development Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Development_Guide/sect-Java_Persistence_API_JPA.html#sect-Configuration2"
}
},
"developerguide": {
"name": "Keycloak Server Developer Guide",
"link": "https://keycloak.gitbooks.io/server-developer-guide/content/"
},
"adminguide": {
"name": "Keycloak Adminstration Guide",
"link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/"
},
"project": {
"name": "Keycloak",
"version": "1.9.3.Final"
}
}
}

105
gitlab-conversion.py Executable file
View file

@ -0,0 +1,105 @@
import sys, os, re, json, shutil, errno
def transform(root, f, targetdir):
full = os.path.join(root, f)
input = open(full, 'r').read()
dir = os.path.join(targetdir, root)
if not os.path.exists(dir):
os.makedirs(dir)
output = open(os.path.join(dir, f), 'w')
input = applyTransformation(input)
output.write(input)
def applyTransformation(input):
for variable in re.findall(r"\{\{(.*?)\}\}", input):
tmp = variable.replace('.', '_')
input = input.replace(variable, tmp)
input = input.replace('{{', '{').replace('}}', '}')
input = re.sub(r"<<fake.+#", "<<", input)
for variable in re.findall(r"[ ]*{% if (.*?) %}", input):
tmp = variable.replace('.', '_')
input = input.replace(variable, tmp)
exp = re.compile("[ ]*{% if (.*?) %}(.*?)[ ]*{% endif %}", re.DOTALL)
input = re.sub(exp, "ifeval::[{\g<1>}==true]\g<2>endif::[]", input)
input = re.sub(r"image:(\.\./)*", "image:", input)
return input
indir = 'topics'
targetdir = 'target'
if len(sys.argv) > 1:
targetdir = sys.argv[1]
if os.path.exists(targetdir):
shutil.rmtree(targetdir)
shutil.copytree('images',os.path.join(targetdir, 'images'))
shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images'))
shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images'))
tmp = os.path.join(targetdir, 'topics')
if not os.path.exists(tmp):
os.makedirs(tmp)
# transform files
for root, dirs, filenames in os.walk(indir):
for f in filenames:
transform(root,f,targetdir)
# Create master.doc includes
input = open('SUMMARY.adoc', 'r').read()
output = open(os.path.join(targetdir, 'master.adoc'), 'w')
output.write("""
:toc:
:toclevels: 3
:numbered:
include::document-attributes.adoc[]
""")
input = re.sub(r"[ ]*\.+\s*link:(.*)\[(.*)\]", "include::\g<1>[]", input)
input = applyTransformation(input)
output.write(input)
# parse book.json file and create document attributes
with open('book.json') as data_file:
data = json.load(data_file)
variables = data['variables']
def makeAttributes(variables, variable, list):
for i in variables.keys():
if variable is None:
tmp = i
else:
tmp = variable + '_' + i
if isinstance(variables[i],dict):
makeAttributes(variables[i], tmp, list)
elif isinstance(variables[i],bool):
boolval = 'false'
if variables[i]:
boolval = 'true'
list.append({tmp: boolval})
else:
list.append({tmp: str(variables[i])})
attributeList = []
makeAttributes(variables, None, attributeList)
output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w')
for attribute in attributeList:
for k in attribute.keys():
output.write(':book_' + k + ": " + attribute[k] + "\n")
print "Transformation complete!"

93
topics/Overview.adoc
View file

@ -1,86 +1,11 @@
= Overview == Overview
Keycloak is an SSO solution for web apps, mobile and RESTful web services. {{book.project.name}} is a single sign on solution for web apps and RESTful web services. The goal of {{book.project.name}}
It is an authentication server where users can centrally login, logout, register, and manage their user accounts. is make security simple so that it is easy for application developers to secure the apps and services they have deployed
The Keycloak admin UI can manage roles and role mappings for any application secured by Keycloak. in their organization. Security features that developers normally have to write for themselves are provided out of the box
The Keycloak Server can also be used to perform social logins via the user's favorite social media site i.e. and are easily tailorable to the individual requirements of your organization. {{book.project.name}} provides customizable
Google, Facebook, Twitter etc. user interfaces for login, registration, adminstration, and account management. You can also use {{book.project.name}} as an
integration platform to hook it into existing LDAP and Active Directory servers. You can also delegate authentication to third
party identity providers like Facebook and Google+. {{book.project.name}} has tons of SPIs that you can use to customize every
aspect of the server.
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.

61
topics/overview/concepts.adoc Executable file
View file

@ -0,0 +1,61 @@
=== Core Concepts and Terms
There are some key concepts and terms you should be aware of before attempting to use {{book.project.name} to secure your web applications
and REST services.
users::
Users are entities that are able to log into your system. They can have attributes associated with themselves like email,
username, address, phone number, and birth day. They can be assign group membership and have specific roles assigned to them.
credentials:
Credentials are pieces of data that {{book.project.name}} uses to verify the identity of a user. Some examples are passwords,
one-time-passwords, digital certificates, or even fingerprints.
roles::
Roles identify a type or category of user. `Admin`, `user`, `manager`, and `employee` are all typical roles that may exist
in an organization. Applications often assign access and permissions to specific roles rather than individual users as dealing
with users can be too fine grained and hard to manage
user role mapping::
A user role mapping defines a mapping between a role and a user. A user can be associated with zero or more roles. This
role mapping information can be encapsulated into tokens and assertions so that applications can decide access permissions on
various resources they manage
composite roles::
A composite role is a role that can be associated with other roles. For example a `superuser` composite role could be associated with the
`sales-admin` and 'order-entry-admin` roles. If a user is mapped to the `superuser` role they also inherit the `sales-admin` and `order-entry-admin` roles.
groups::
Groups manage groups of users. Attributes can be defined for a group. You can map roles to a group as well. Users that become members of a group
inherit the attributes and role mappings that group defines.
realms::
A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another
and can only manage and authenticate the users that they manage
clients::
Clients are entities that can request {{book.project.name}} to authenticate a user. Most often, clients are applications and services that
want to use {{book.project.name}} to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request
identity information or an access token so that they can securely invoke other services on the network that are secured by {{book.project.name}}
consent::
Consent is when you as an admin want a user to give permission to a client before that client can participate in the authentication process.
After a user provides their credentials, {{book.project.name}} will pop up a screen identifying the client requesting a login and what identity
informationis requesting of the user. User can decide whether or not to grant the request.
session::
When a user logs in, a session is created to manage the login session. A session contains information like when the user logged in and what
applications have participated within single-sign on during that session. Both admins and users can view session information.
client templates::
When a client is registered you need to enter in a bunch of configuration information about that client. It is often useful to store a template
of this to make create new clients easier. {{book.project.name}} provides the concept of a client template for this.
user federation provider::
{{book.project.name}} can store and manage users. Often, companies already have LDAP or Active Directory services that store user and credential
information. You can point {{book.project.name}} to validate credentials from those external stores and pull in identity information.
identity provider::
An identity provider (IDP) is a service that can authenticate a user. {{book.project.name}} is an IDP.
identity provider federation::
{{book.project.name}} can be configured to delegate authentication to one or more IDPs. Social login via
Facebook or Google+ is an example of identity provider federation. You can also hook {{boook.project.name}} to delegate
authentication to any other Open ID Connect or SAML 2.0 IDP.
required actions::
Required actions are actions a user must before immediately after they log in. A user will not be able to complete the authentication process until these actions
are complete. For example, an admin may schedule users to reset their passwords every month. An `update password` required action would be set for all these
users.
authentication flows::
Authentication flows are work flows a user must perform when interacting with certain aspects of the system. A login flow can define
what credential types are required. A registration flow defines what profile information a user must enter and whether something like Recaptcha
must be used to filter out bots. Credential reset flow defines what actions a user must do before they can reset their password.
events::
Events are audit streams that admins can view and hook into.

37
topics/overview/features.adoc Normal file
View file

@ -0,0 +1,37 @@
=== 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 how you want auth responses to look.
* Can support any platform that has an Open ID Connect or SAML 2.0 client adapter. {{book.project.name}} does provide
client adapters for Pure HTML5/Javascript apps, JBoss AS7, JBoss EAP 6.x, JBoss EAP 7, Wildfly, Tomcat 7,
Tomcat 8, Jetty 9.1.x, Jetty 9.2.x, and Jetty 8.1.x.
* Tons of SPIs for customizing every aspect of the server.

12
topics/overview/how.adoc Executable file
View file

@ -0,0 +1,12 @@
=== How Does Security Work?
{{book.project.name}} is a separate server that you manage on your network. Applications are configured to point to and
be secured by this server. {{book.project.name}} uses open protocol standards like link:http://openid.net/connect[Open ID Connect]
or link:http://saml.xml.org/saml-specifications[SAML 2.0] to secure
your applications. Browser applications redirect a user's browser from the application to the {{book.project.name}} authentication
server where they enter their credentials. This is important because users are completely isolated from applications and
applications never see a user's credentials. Applications instead are given an identity token or assertion that is cryptographically
signed. These tokens can have identity information like username, address, email, and other profile data. They can also
hold permission data so that applications can make authorization decisions. These tokens can also be used to make secure
invocations on REST-based services.

15
topics/overview_How_Security_Work_in_Keycloak.adoc
View file

@ -1,15 +0,0 @@
== 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.

21
topics/overview_key_concepts.adoc
View file

@ -1,21 +0,0 @@
== 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.

8
topics/overview_permission_scopes.adoc
View file

@ -1,8 +0,0 @@
=== 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.