aasingh
commit
fb6a37b8f7
68 changed files with 361 additions and 482 deletions
5
.gitignore
vendored
5
.gitignore
vendored
|
|
@ -45,3 +45,8 @@ catalog.xml
|
|||
#########
|
||||
target
|
||||
|
||||
|
||||
# Gitbook
|
||||
|
||||
_book
|
||||
node_modules
|
||||
|
|
|
|||
|
|
@ -41,8 +41,9 @@
|
|||
.. link:topics/clients/client-saml.adoc[SAML Clients]
|
||||
... link:topics/clients/saml/idp-initiated-login.adoc[IDP Initiated Login]
|
||||
... link:topics/clients/saml/entity-descriptors.adoc[SAML Entity Descriptors]
|
||||
{% if book.community %}
|
||||
.. link:topics/clients/client-link.adoc[Client Links]
|
||||
.. link:topics/clients/client-registration.adoc[Client Registration]
|
||||
{% endif %}
|
||||
.. link:topics/clients/protocol-mappers.adoc[Token and Assertion Mappings]
|
||||
.. link:topics/clients/installation.adoc[Generating Client Adapter Config]
|
||||
.. link:topics/clients/client-templates.adoc[Client Templates]
|
||||
|
|
|
|||
2
book.json
Executable file → Normal file
2
book.json
Executable file → Normal file
|
|
@ -70,7 +70,7 @@
|
|||
},
|
||||
"installguide": {
|
||||
"name": "Server Installation and Configuration Guide",
|
||||
"link": "https://keycloak.gitbooks.io/server-install-guide/content/"
|
||||
"link": "https://keycloak.gitbooks.io/server-installation-and-configuration/content/"
|
||||
},
|
||||
"adapterguide": {
|
||||
"name": "Securing Client Applications Guide",
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
== User Account Service
|
||||
|
||||
{{book.project.name}} has a built in User Account Service which every user has access to. This service allows users to manage their account,
|
||||
change their credentials, update their profile, and view their login sessions. The URL to this service is `<server-root/auth/realms/\{realm-name}/account`.
|
||||
change their credentials, update their profile, and view their login sessions. The URL to this service is `<server-root>/auth/realms/\{realm-name}/account`.
|
||||
|
||||
.Account Service
|
||||
image:../{{book.images}}/account-service-profile.png[]
|
||||
|
|
@ -18,12 +18,12 @@ image:../{{book.images}}/account-service-password.png[]
|
|||
|
||||
The `Authenticator` menu item allows the user to set up OTP if they desire. This will only show up if OTP is a valid authentication mechanism for your realm.
|
||||
Users are given directions to install https://fedorahosted.org/freeotp/[FreeOTP] or https://play.google.com/[Google Authenticator] on their mobile device to be their OTP generator.
|
||||
The bar code you see in the screen shot can be scanned into the FreeOTP or Google Authenticator mobile application for nice and easy setup.
|
||||
The QR code you see in the screen shot can be scanned into the FreeOTP or Google Authenticator mobile application for nice and easy setup.
|
||||
|
||||
.OTP Authenticator
|
||||
image:../{{book.images}}/account-service-authenticator.png[]
|
||||
|
||||
The `Federated Identity` menu item allows the user to link their account with an <<identity-broker.adoc#_identity-broker, identity broker>> (this is usually used to link social provier
|
||||
The `Federated Identity` menu item allows the user to link their account with an <<fake/../identity-broker.adoc#_identity-broker, identity broker>> (this is usually used to link social provier
|
||||
accounts together). This will show the list of external identity providers you have configured for your realm.
|
||||
|
||||
.Federated Identity
|
||||
|
|
@ -41,7 +41,7 @@ image:../{{book.images}}/account-service-apps.png[]
|
|||
|
||||
=== Themeable
|
||||
|
||||
Like all UIs in {{book.project.name}} the User Account Service is completely themeable and internationalizable.
|
||||
Like all UIs in {{book.project.name}}, the User Account Service is completely themeable and internationalizable.
|
||||
See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,6 +2,6 @@
|
|||
|
||||
== Admin Console Access Control and Permissions
|
||||
|
||||
Each realm created on the {{book.project.name}} has a dedicated Admin Console from which that realm can be managed from.
|
||||
Each realm created on the {{book.project.name}} has a dedicated Admin Console from which that realm can be managed.
|
||||
The `master` realm is a special realm that allows admins to manage more than one realm on the system. You can also
|
||||
define fine-grain access to users in different realms to manage the server. This chapter goes over all the scenarios for this.
|
||||
define fine-grained access to users in different realms to manage the server. This chapter goes over all the scenarios for this.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
=== Master Realm Access Control
|
||||
|
||||
The `master` realm in {{book.project.name}} is a special realm and treated differently that other realms.
|
||||
The `master` realm in {{book.project.name}} is a special realm and treated differently than other realms.
|
||||
Users in the {{book.project.name}} `master` realm can be granted permission to manage zero or more realms that are deployed on the {{book.project.name}} server.
|
||||
When a realm is created, {{book.project.name}} automatically creates various roles that grant fine-grain permissions to access that new realm.
|
||||
Access to The Admin Console and Admin REST endpoints can be controlled by mapping these roles to users in the `master` realm.
|
||||
|
|
@ -16,7 +16,7 @@ These are:
|
|||
* create-realm
|
||||
|
||||
Users with the `admin` role are super users and have full access to manage any realm on the server. Users with the `create-realm` role
|
||||
are allowed to create new realms. Any new realm they create they will be granted full access to.
|
||||
are allowed to create new realms. They will be granted full access to any new realm they create.
|
||||
|
||||
==== Realm Specific Roles
|
||||
|
||||
|
|
@ -42,6 +42,6 @@ The roles available are:
|
|||
* manage-identity-providers
|
||||
* impersonation
|
||||
|
||||
Assign the roles you want to your users and they will only be able to use that specific part of the administration console
|
||||
Assign the roles you want to your users and they will only be able to use that specific part of the administration console.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Each realm has a dedicated Admin Console that can be accessed by going to the ur
|
|||
Users within that realm can be granted realm management permissions by assigning specific user role mappings.
|
||||
|
||||
Each realm has a built-in client called `realm-management`. You can view this client by going to the
|
||||
`Clients` left menu item of your realm. This client define client-level roles that specify permissions that can be granted to manage the realm.
|
||||
`Clients` left menu item of your realm. This client defines client-level roles that specify permissions that can be granted to manage the realm.
|
||||
|
||||
* view-realm
|
||||
* view-users
|
||||
|
|
@ -23,5 +23,5 @@ Each realm has a built-in client called `realm-management`. You can view this c
|
|||
* manage-identity-providers
|
||||
* impersonation
|
||||
|
||||
Assign the roles you want to your users and they will only be able to use that specific part of the administration console
|
||||
Assign the roles you want to your users and they will only be able to use that specific part of the administration console.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Enter the username and password you created on the Welcome Page or the `add-user
|
|||
.Admin Console
|
||||
image:../{{book.images}}/admin-console.png[]
|
||||
|
||||
The left pull down menu allows you to pick a realm you want to manage or to create a new one. The right pull down menu allows you to view your user account or logout.
|
||||
The left drop down menu allows you to pick a realm you want to manage or to create a new one. The right drop down menu allows you to view your user account or logout.
|
||||
If you are curious about a certain feature, button, or field within the Admin Console, simply hover your mouse
|
||||
over any question mark `?` icon. This will pop up tooltip text to describe the area of the console you are interested in.
|
||||
The image above shows the tooltip in action.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
== Authentication
|
||||
|
||||
There's a few features you should be aware of when configuring authentication for your realm. Many organizations
|
||||
have strict password an OTP policies that you can enforce via settings in the Admin Console. You may or may not
|
||||
There are a few features you should be aware of when configuring authentication for your realm. Many organizations
|
||||
have strict password and OTP policies that you can enforce via settings in the Admin Console. You may or may not
|
||||
want to require different credential types for authentication. You may want to give users the option to login via
|
||||
Kerberos or disable or enable various built in credential types. This chapter covers all of these topics.
|
||||
|
|
@ -6,9 +6,9 @@ An _authentication flow_ is a container for all authentications, screens, and ac
|
|||
{{book.project.name}} work flows.
|
||||
If you go to the admin console `Authentication` left menu item and go to the `Flows` tab, you can view all the defined flows
|
||||
in the system and what actions and checks each flow requires. This section does a walk through of the browser login flow. In the
|
||||
left drop down list selected `browser` to come to the screen shown below:
|
||||
left drop down list select `browser` to come to the screen shown below:
|
||||
|
||||
.browser flow
|
||||
.Browser Flow
|
||||
image:../../{{book.images}}/browser-flow.png[]
|
||||
|
||||
If you hover over the tooltip (the tiny question mark) to the right of the flow selection list, this will describe what the
|
||||
|
|
@ -38,10 +38,10 @@ This is better described in an example. Let's walk through the `browser` authen
|
|||
Since the cookie provider returned success and each execution at this level of the flow is _alternative_, no other execution is executed and this results in a successful login.
|
||||
. Next the flow looks at the Kerberos execution. This authenticator is disabled by default and will be skipped.
|
||||
. The next execution is a subflow called Forms. Since this subflow is marked as _alternative_ it will not be executed if the `Cookie` authentication type passed.
|
||||
This subflow contains additional authentication type that need to be executed.
|
||||
This subflow contains additional authentication type that needs to be executed.
|
||||
The executions for this subflow are loaded and the same processing logic occurs
|
||||
. The first execution in the Forms subflow is the Username Password Form. This authentication type renders the username and password page.
|
||||
it is marked as _required_ so the use must enter in a valid username and password.
|
||||
It is marked as _required_ so the user must enter in a valid username and password.
|
||||
. The next execution is the OTP Form.
|
||||
This is marked as _optional_. If the user has OTP set up, then this authentication type must run and be successful. If the user doesn't
|
||||
have OTP set up, this authentication type is ignored.
|
||||
|
|
|
|||
|
|
@ -43,14 +43,14 @@ At least you will need to:
|
|||
For example if your {{book.project.name}} server will be running on `www.mydomain.org` you may need to add principal `HTTP/www.mydomain.org@MYDOMAIN.ORG`
|
||||
assuming that MYDOMAIN.ORG will be your Kerberos realm.
|
||||
+
|
||||
For example on MIT Kerberos you can run "kadmin" session.
|
||||
If you are on same machine where is MIT Kerberos, you can simply use command:
|
||||
For example on MIT Kerberos you can run a "kadmin" session.
|
||||
If you are on the same machine where is MIT Kerberos, you can simply use the command:
|
||||
|
||||
[source]
|
||||
----
|
||||
sudo kadmin.local
|
||||
----
|
||||
Then add HTTP principal and export his key to keytab file with the commands like:
|
||||
Then add HTTP principal and export his key to a keytab file with the commands like:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
@ -59,14 +59,14 @@ addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG
|
|||
ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG
|
||||
----
|
||||
|
||||
Keytab file `/tmp/http.keytab` will need to be accessible on the host where {{book.project.name}} server will be running.
|
||||
The Keytab file `/tmp/http.keytab` will need to be accessible on the host where {{book.project.name}} server will be running.
|
||||
|
||||
==== Setup and configuration of {{book.project.name}} server
|
||||
|
||||
You need to install a kerberos client on your machine. This is also platform dependent.
|
||||
If you are on Fedora, Ubuntu or RHEL, you can install the package `freeipa-client`, which contains a Kerberos client and bunch of other utilities.
|
||||
Configure kerberos client (on linux it's in file `/etc/krb5.conf` ). You need to put your Kerberos realm and at least configure the HTTP domains your server will be running on.
|
||||
For the example realm MYDOMAIN.ORG you may configure `domain_realm` section like this:
|
||||
If you are on Fedora, Ubuntu or RHEL, you can install the package `freeipa-client`, which contains a Kerberos client and several other utilities.
|
||||
Configure the kerberos client (on linux it's in file `/etc/krb5.conf` ). You need to put your Kerberos realm and at least configure the HTTP domains your server will be running on.
|
||||
For the example realm MYDOMAIN.ORG you may configure the `domain_realm` section like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
@ -77,15 +77,15 @@ For the example realm MYDOMAIN.ORG you may configure `domain_realm` section like
|
|||
|
||||
Next you need to export the keytab file with the HTTP principal and make sure the file is accessible to the process under which {{book.project.name}} server is running.
|
||||
For production, it's ideal if it's readable just by this process and not by someone else.
|
||||
For MIT Kerberos example above, we already exported keytab to `/tmp/http.keytab` . If your KDC and {{book.project.name}} are running on same host,
|
||||
For the MIT Kerberos example above, we already exported keytab to `/tmp/http.keytab` . If your KDC and {{book.project.name}} are running on same host,
|
||||
you have that file already available.
|
||||
|
||||
===== Enable SPNEGO Processing
|
||||
|
||||
{{book.project.name}} does not have SPNEGO protocol support turned on by default. So, you have to go to the <<fake/../../authentication/flows.adoc#_authentication-flows, browser flow>>
|
||||
{{book.project.name}} does not have the SPNEGO protocol support turned on by default. So, you have to go to the <<fake/../../authentication/flows.adoc#_authentication-flows, browser flow>>
|
||||
and enable `Kerberos`.
|
||||
|
||||
.browser flow
|
||||
.Browser Flow
|
||||
image:../../{{book.images}}/browser-flow.png[]
|
||||
|
||||
Switch the `Kerberos` requirement from _disabled_ to either _alternative_ or _required_. _Alternative_ basically means that Kerberos is optional. If
|
||||
|
|
@ -95,7 +95,7 @@ to _required_ then all users must have Kerberos enabled for their browser.
|
|||
===== Configure Kerberos User Storage Federation Provider
|
||||
|
||||
Now that the SPNEGO protocol is turned on at the authentication server, you'll need to configure how {{book.project.name}} interprets the Kerberos ticket.
|
||||
This is done through <fake/../../user-federation.adoc#_user-storage-federation,User Storage Federation>>. We have 2 different federation providers with Kerberos authentication support.
|
||||
This is done through <<fake/../../user-federation.adoc#_user-storage-federation,User Storage Federation>>. We have 2 different federation providers with Kerberos authentication support.
|
||||
|
||||
If you want to authenticate with Kerberos backed by an LDAP server, you have to first configure the <<fake/../../user-federation/ldap.adoc#_ldap, LDAP Federation Provider>>.
|
||||
If you look at the configuration page for your LDAP provider you'll see a `Kerberos Integration` section.
|
||||
|
|
@ -112,17 +112,17 @@ left menu item and select `Kerberos` from the right `Add provider` select box.
|
|||
.Kerberos User Storage Provider
|
||||
image:../../{{book.images}}/kerberos-provider.png[]
|
||||
|
||||
This provider simply parses the Kerberos ticket for principal information and does a small import into the local {{book.project.name}} database.
|
||||
User profile information like first name, last name, and email are not provisioned. Just simple user principal information.
|
||||
This provider parses the Kerberos ticket for simple principal information and does a small import into the local {{book.project.name}} database.
|
||||
User profile information like first name, last name, and email are not provisioned.
|
||||
|
||||
==== Setup and configuration of client machines
|
||||
|
||||
Clients need to install kerberos client and setup krb5.conf as described above.
|
||||
Additionally they need to enable SPNEGO login support in their browser.
|
||||
See link:http://www.microhowto.info/howto/configure_firefox_to_authenticate_using_spnego_and_kerberos.html[configuring Firefox for Kerberos] if you are using that browser.
|
||||
URI `.mydomain.org` must be allowed in `network.negotiate-auth.trusted-uris` config option.
|
||||
URI `.mydomain.org` must be allowed in the `network.negotiate-auth.trusted-uris` config option.
|
||||
|
||||
In windows domain, clients usually don't need to configure anything special as IE is already able to participate in SPNEGO authentication for the windows domain.
|
||||
In a Windows domain, clients usually don't need to configure anything special as IE is already able to participate in SPNEGO authentication for the Windows domain.
|
||||
|
||||
{% if book.community %}
|
||||
==== Example setups
|
||||
|
|
@ -138,12 +138,12 @@ See details https://github.com/mposolda/keycloak-freeipa-docker/blob/master/READ
|
|||
|
||||
===== ApacheDS testing Kerberos server
|
||||
|
||||
For quick testing and unit tests, we use very simple http://directory.apache.org/apacheds/[ApacheDS] Kerberos server.
|
||||
You need to build {{book.project.name}} from sources and then run Kerberos server with maven-exec-plugin from our testsuite.
|
||||
For quick testing and unit tests, we use a very simple http://directory.apache.org/apacheds/[ApacheDS] Kerberos server.
|
||||
You need to build {{book.project.name}} from sources and then run the Kerberos server with maven-exec-plugin from our testsuite.
|
||||
See details https://github.com/keycloak/keycloak/blob/master/misc/Testsuite.md#kerberos-server[here] .
|
||||
{% endif %}
|
||||
|
||||
==== Credential delegation
|
||||
==== Credential Delegation
|
||||
|
||||
Kerberos 5 supports the concept of credential delegation. In this scenario, your applications may want access to the Kerberos ticket so that
|
||||
they can re-use it to interact with other services secured by Kerberos. Since the SPNEGO protocol is processed in the {{book.project.name}} server,
|
||||
|
|
@ -154,21 +154,35 @@ This is enabled in the `Mappers` tab of the application's
|
|||
client page. See <<fake/../../clients/protocol-mappers.adoc#_protocol-mappers, Protocol Mappers>> chapter for more details.
|
||||
|
||||
Applications will need to deserialize the claim it receives from {{book.project.name}} before it can use it to make GSS calls against other services.
|
||||
We have an example, that shows this in detail.
|
||||
It's in `examples/kerberos` in the {{book.project.name}} example distribution or demo distribution download.
|
||||
You can also check the example sources directly https://github.com/keycloak/keycloak/blob/master/examples/kerberos[here] .
|
||||
|
||||
Once you deserialize the credential from the access token to the GSSCredential object, then GSSContext will need to be created with this credential
|
||||
Once you deserialize the credential from the access token to the GSSCredential object, the GSSContext will need to be created with this credential
|
||||
passed to the method `GSSManager.createContext` for example like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
// Obtain accessToken in your application.
|
||||
KeycloakPrincipal keycloakPrincipal = (KeycloakPrincipal) servletReq.getUserPrincipal();
|
||||
AccessToken accessToken = keycloakPrincipal.getKeycloakSecurityContext().getToken();
|
||||
|
||||
// Retrieve kerberos credential from accessToken and deserialize it
|
||||
String serializedGssCredential = (String) accessToken.getOtherClaims().
|
||||
get(org.keycloak.common.constants.KerberosConstants.GSS_DELEGATION_CREDENTIAL);
|
||||
|
||||
GSSCredential deserializedGssCredential = org.keycloak.common.util.KerberosSerializationUtils.
|
||||
deserializeCredential(serializedGssCredential);
|
||||
|
||||
// Create GSSContext to call other kerberos-secured services
|
||||
GSSContext context = gssManager.createContext(serviceName, krb5Oid,
|
||||
deserializedGssCredFromKeycloakAccessToken, GSSContext.DEFAULT_LIFETIME);
|
||||
----
|
||||
deserializedGssCredential, GSSContext.DEFAULT_LIFETIME);
|
||||
----
|
||||
|
||||
{% if book.community %}
|
||||
We have an example, that shows this in detail.
|
||||
It's in `examples/kerberos` in the {{book.project.name}} example distribution or demo distribution download.
|
||||
You can also check the example sources directly https://github.com/keycloak/keycloak/blob/master/examples/kerberos[here] .
|
||||
{% endif %}
|
||||
|
||||
|
||||
Note that you also need to configure `forwardable` kerberos tickets in `krb5.conf` file and add support for delegated credentials to your browser.
|
||||
For details, see the kerberos example from {{book.project.name}} examples set as mentioned above.
|
||||
|
||||
WARNING: Credential delegation has some security implications so only use it if you really need it.
|
||||
It's highly recommended to use it together with HTTPS.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
=== OTP Policies
|
||||
|
||||
{{book.project.name}} has a number of policies you can set up for your FreeOTP or Google Authenticator One-Time Password
|
||||
generator. Click on the `Authentication` left menu item and got to the `OTP Policy` tab.
|
||||
generator. Click on the `Authentication` left menu item and go to the `OTP Policy` tab.
|
||||
|
||||
.OTP Policy
|
||||
image:../../{{book.images}}/otp-policy.png[]
|
||||
|
|
@ -13,15 +13,15 @@ generated from information configured on the `OTP Policy` tab.
|
|||
|
||||
==== TOTP vs. HOTP
|
||||
|
||||
There are two different algorithms to choose from for your OTP generators. Time Based (TOTP) and Counter Based (HOTP) based.
|
||||
For TOTP, your token generator will hash the current time and a share secret. The server validates the OTP by comparing
|
||||
There are two different algorithms to choose from for your OTP generators. Time Based (TOTP) and Counter Based (HOTP).
|
||||
For TOTP, your token generator will hash the current time and a shared secret. The server validates the OTP by comparing
|
||||
the all hashes within a certain window of time to the submitted value. So, TOTPs are valid only for a short window of time (usually 30 seconds).
|
||||
For HOTP a shared counter is used instead of the current time. The server increments the counter each successful OTP login. So, valid OTPs only
|
||||
For HOTP a shared counter is used instead of the current time. The server increments the counter with each successful OTP login. So, valid OTPs only
|
||||
change after a successful login.
|
||||
|
||||
TOTP is considered a little more secure because the matchable OTP is only valid for a short window of time while the OTP for HOTP can
|
||||
be valid for an indeterminate amount of time. HOTP is much more user friendly as the user won't have to hurry to enter in their
|
||||
OTP before the time interval is up. With the way {{book.project.name}} has implement TOTP this distinction becomes a little more
|
||||
OTP before the time interval is up. With the way {{book.project.name}} has implemented TOTP this distinction becomes a little more
|
||||
blurry. HOTP requires a database update every time the server wants to increment the counter. This can be a performance drain
|
||||
on the authentication server when there is heavy load. So, to provide a more efficient alternative, TOTP does not remember passwords
|
||||
used. This bypasses the need to do any DB updates, but the downside is that TOTPs can be re-used in the valid time interval. For future
|
||||
|
|
@ -50,7 +50,7 @@ Number of Digits::
|
|||
Look Ahead Window::
|
||||
How many counters ahead should the server try and match the hash? The default value is 1. This exists to cover the case
|
||||
where the user's counter gets ahead of the server's. This can often happen as users often increment the counter
|
||||
manually too many times by accident. This value really should be increased to like a value of 10 or so.
|
||||
manually too many times by accident. This value really should be increased to a value of 10 or so.
|
||||
Initial Counter::
|
||||
What is the value of the initial counter?
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ but pretty much unacceptable in production environment. {{book.project.name}} h
|
|||
through the Admin Console.
|
||||
|
||||
Click on the `Authentication` left menu item and go to the `Password Policy` tab. Choose the policy you want to add in the
|
||||
right side pull down list box. This will add the policy in the table on the screen. Choose the parameters for the policy.
|
||||
right side drop down list box. This will add the policy in the table on the screen. Choose the parameters for the policy.
|
||||
Hit the `Save` button to store your changes.
|
||||
|
||||
.Password Policy
|
||||
|
|
|
|||
|
|
@ -1,10 +1,11 @@
|
|||
[[_clients]]
|
||||
|
||||
== Managing Clients
|
||||
|
||||
Clients are entities that can request authentication of a user. Clients come in two forms.
|
||||
he first type of client is an application that wants
|
||||
The first type of client is an application that wants
|
||||
to participate in single-sign-on. These clients just want {{book.project.name}} to provide security for them. The other type
|
||||
of client is one that is requesting an access token so that it can invoke on other services on behalf of the authenticated user.
|
||||
of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.
|
||||
This section discusses various aspects around configuring clients and various ways to do it.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
=== OIDC Clients
|
||||
|
||||
<<fake/../../sso-protocols/oidc.adoc#_oidc,OpenID Connect>> is the preferred protocol to secure applications. It was designed from the ground up to be web friendly
|
||||
and works best with HTML5/JavaScript applications.
|
||||
and work best with HTML5/JavaScript applications.
|
||||
|
||||
To create a OIDC client go to the `Clients` left menu item. On this page you'll see a `create` button on the right.
|
||||
To create an OIDC client go to the `Clients` left menu item. On this page you'll see a `Create` button on the right.
|
||||
|
||||
.Clients
|
||||
image:../../{{book.images}}/clients.png[]
|
||||
|
|
@ -15,7 +15,7 @@ This will bring you to the `Add Client` page.
|
|||
.Add Client
|
||||
image:../../{{book.images}}/add-client-oidc.png[]
|
||||
|
||||
Enter in the `Client ID` of the client. This should be a simple string
|
||||
Enter in the `Client ID` of the client. This should be a simple
|
||||
alpha-numeric string that will be used in requests and in the {{book.project.name}} database to identity the client.
|
||||
Next select `openid-connect` in the `Client Protocol` drop down box.
|
||||
Ignore the `Client Template` listbox for now,
|
||||
|
|
@ -40,6 +40,7 @@ the value of this field by setting up a replacement string value i.e. $\{myapp}.
|
|||
for more information.
|
||||
|
||||
*Description*
|
||||
|
||||
This specifies the description of the client. This can also be localized.
|
||||
|
||||
*Enabled*
|
||||
|
|
@ -58,39 +59,36 @@ If you've ever done a social login to Google, you'll often see a similar page.
|
|||
This defines the type of the OIDC client.
|
||||
|
||||
_confidential_::
|
||||
Confidential access type is for clients that need to perform a browser login and that you want to require a client secret when they turn an access code into an access token,
|
||||
(see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). The advantages of this is that it is a little extra security.
|
||||
Confidential access type is for clients that need to perform a browser login and require a client secret when they turn an access code into an access token,
|
||||
(see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). The advantage of this is that it is a little extra security.
|
||||
Since {{book.project.name}} requires you to register valid redirect-uris, we're not exactly sure what this little extra security is though.
|
||||
:) The disadvantages of this access type is that confidential access type is pointless for pure JavaScript clients as anybody could easily figure out your client's secret!
|
||||
|
||||
_public_::
|
||||
Public access type is for clients that need to perform a browser login and that you feel that the added extra security of confidential access type is not needed.
|
||||
FYI, Pure javascript clients are by nature public.
|
||||
Pure javascript clients are by nature public.
|
||||
|
||||
_bearer-only_::
|
||||
Bearer-only access type means that the application only allows bearer token requests.
|
||||
If this is turned on, this application cannot participate in browser logins.
|
||||
|
||||
_direct access only_::
|
||||
This switch is for clients that only use the <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Direct Access Grant>> protocol to obtain access tokens.
|
||||
|
||||
*Root URL*
|
||||
|
||||
If {{book.project.name}} uses any configured relative URLs, this value is prepended to them.
|
||||
If {{book.project.name}} uses any configured relative URLs, this value is prepended to them.
|
||||
|
||||
*Valid Redirect URIs*
|
||||
|
||||
This is a required field. Enter in a URL pattern and click the + sign to add. Click the - sign next to URLs you want to remove.
|
||||
Remember that you still have to click the `Save` button!
|
||||
Only wildcards, * ,are allowed at the end of of a URI, i.e. http://host.com/*
|
||||
Wildcards (\*) are only allowed at the end of a URI, i.e. http://host.com/*
|
||||
|
||||
You should take extra precautions when registering valid redirect URI patterns as if you make
|
||||
You should take extra precautions when registering valid redirect URI patterns. If you make
|
||||
them too general you are vulnerable to attacks. See <<fake/../../threat/redirect.adoc#_unspecific-redirect-uris, Threat Model Mitigation>> chapter
|
||||
for more information.
|
||||
|
||||
*Base URL*
|
||||
|
||||
If {{book.project.name}} needs to link to the client, this URL would be used.
|
||||
If {{book.project.name}} needs to link to the client, this URL is used.
|
||||
|
||||
*Standard Flow Enabled*
|
||||
|
||||
|
|
@ -114,8 +112,8 @@ See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more informa
|
|||
*Web Origins*
|
||||
|
||||
This option centers around link:http://www.w3.org/TR/cors/[CORS] which stands for Cross-Origin Resource Sharing.
|
||||
If executing browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different than the one the
|
||||
JavaScript code came from, then the request uses the CORS.
|
||||
If browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different from the one the
|
||||
JavaScript code came from, then the request must use CORS.
|
||||
The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed.
|
||||
This protocol exists to protect against XSS, CSRF and other JavaScript-based attacks.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,146 +0,0 @@
|
|||
=== Client Registration
|
||||
|
||||
In order for an application or service to utilize {{book.project.name}} it has to register a client in {{book.project.name}}.
|
||||
An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through {{book.project.name}}'s client registration service.
|
||||
|
||||
The Client Registration Service provides built-in support for {{book.project.name}} Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors.
|
||||
It's also possible to plugin custom client registration providers if required.
|
||||
The Client Registration Service endpoint is `auth/realms/\{realm-name}/clients-registrations/\{provider}`.
|
||||
|
||||
The built-in supported `providers` are:
|
||||
|
||||
* default
|
||||
* install
|
||||
* openid-connect
|
||||
* saml2-entity-descriptor
|
||||
|
||||
The following sections will describe how to use the different providers.
|
||||
|
||||
==== Authentication
|
||||
|
||||
To invoke the Client Registration Services you need a token.
|
||||
The token can be a standard bearer token, a initial access token or a registration access token.
|
||||
|
||||
===== Bearer Token
|
||||
|
||||
The bearertoken can be issued on behalf of a user or a Service Account.
|
||||
The following permissions are required to invoke the endpoints (see <<fake/../../admin-console-permissions.adoc#_admin_permissions,Admin Permissions>> for more details):
|
||||
|
||||
* create-client
|
||||
+`manage-client`
|
||||
* view-client
|
||||
+`manage-client`
|
||||
* manage-client
|
||||
|
||||
If you are using a regular bearer token to create clients we recommend using a token from on behalf of a Service Account with only the `create-client` role.
|
||||
See the <<fake/../../clients/oidc/service-accounts.adoc#_service_accounts,Service Accounts>> section for more details.
|
||||
|
||||
===== Initial Access Token
|
||||
|
||||
The best approach to create new clients is by using initial access tokens.
|
||||
An initial access token can only be used to create clients and has a configurable expiration as well as a configurable limit on how many clients can be created.
|
||||
|
||||
An initial access token can be created through the admin console.
|
||||
To create a new initial access token first select the realm in the admin console, then click on `Realm Settings` in the menu on the left, followed by `Initial Access Tokens` in the tabs displayed in the page.
|
||||
|
||||
You will now be able to see any existing initial access tokens.
|
||||
If you have access you can delete tokens that are no longer required.
|
||||
You can only retrieve the value of the token when you are creating it.
|
||||
To create a new token click on `Create`.
|
||||
You can now optionally add how long the token should be valid, also how many clients can be created using the token.
|
||||
After you click on `Save` the token value is displayed.
|
||||
It is important that you copy/paste this token now as you won't be able to retrieve it later.
|
||||
If you forget to copy/paste it, then delete the token and create another one.
|
||||
The token value is used as a standard bearer token when invoking the Client Registration Services, by adding it to the Authorization header in the request.
|
||||
For example:
|
||||
|
||||
[source]
|
||||
----
|
||||
Authorization: bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmMjJmNzQyYy04ZjNlLTQ2M....
|
||||
----
|
||||
|
||||
===== Registration Access Token
|
||||
|
||||
When you create a client through the Client Registration Service the response will include a registration access token.
|
||||
The registration access token provides access to retrieve the client configuration later, but also to update or delete the client.
|
||||
The registration access token is included with the request in the same way as a bearer token or initial access token.
|
||||
Registration access tokens are only valid once when it's used the response will include a new token.
|
||||
|
||||
If a client was created outside of the Client Registration Service it won't have a registration access token associated with it.
|
||||
You can create one through the admin console.
|
||||
This can also be useful if you loose the token for a particular client.
|
||||
To create a new token find the client in the admin console and click on `Credentials`.
|
||||
Then click on `Generate registration access token`.
|
||||
|
||||
==== {{book.project.name}} Representations
|
||||
|
||||
The `default` client registration provider can be used to create, retrieve, update and delete a client.
|
||||
It uses {{book.project.name}} Client Representation format which provides support for configuring clients exactly as they can be configured through the admin console, including for example configuring protocol mappers.
|
||||
|
||||
To create a client create a Client Representation (JSON) then do a HTTP POST to: `auth/realms/<realm>/clients-registrations/default`.
|
||||
It will return a Client Representation that also includes the registration access token.
|
||||
You should save the registration access token somewhere if you want to retrieve the config, update or delete the client later.
|
||||
|
||||
To retrieve the Client Representation then do a HTTP GET to: `auth/realms/<realm>/clients-registrations/default/<client id>`.
|
||||
It will also return a new registration access token.
|
||||
|
||||
To update the Client Representation then do a HTTP PUT to with the updated Client Representation to: `auth/realms/<realm>/clients-registrations/default/<client id>`.
|
||||
It will also return a new registration access token.
|
||||
|
||||
To delete the Client Representation then do a HTTP DELETE to: `auth/realms/<realm>/clients-registrations/default/<client id>`
|
||||
|
||||
==== {{book.project.name}} Adapter Configuration
|
||||
|
||||
The `installation` client registration provider can be used to retrieve the adapter configuration for a client.
|
||||
In addition to token authentication you can also authenticate with client credentials using HTTP basic authentication.
|
||||
To do this include the following header in the request:
|
||||
|
||||
[source]
|
||||
----
|
||||
Authorization: basic BASE64(client-id + ':' + client-secret)
|
||||
----
|
||||
|
||||
To retrieve the Adapter Configuration then do a HTTP GET to: `auth/realms/<realm>/clients-registrations/install/<client id>`
|
||||
|
||||
No authentication is required for public clients.
|
||||
This means that for the JavaScript adapter you can load the client configuration directly from {{book.project.name}} using the above URL.
|
||||
|
||||
==== OpenID Connect Dynamic Client Registration
|
||||
|
||||
{{book.project.name}} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://tools.ietf.org/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://tools.ietf.org/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol].
|
||||
|
||||
The endpoint to use these specifications to register clients in {{book.project.name}} is: `auth/realms/<realm>/clients-registrations/oidc[/<client id>]`.
|
||||
|
||||
This endpoints can also be found in the OpenID Connect Discovery endpoint for the realm: `auth/realms/<realm>/.well-known/openid-configuration`.
|
||||
|
||||
==== SAML Entity Descriptors
|
||||
|
||||
The SAML Entity Descriptor endpoint only supports using SAML v2 Entity Descriptors to create clients.
|
||||
It doesn't support retrieving, updating or deleting clients.
|
||||
For those operations the {{book.project.name}} representation endpoints should be used.
|
||||
When creating a client a {{book.project.name}} Client Representation is returned with details about the created client, including a registration access token.
|
||||
|
||||
To create a client do a HTTP POST with the SAML Entity Descriptor to: `auth/realms/<realm>/clients-registrations/saml2-entity-descriptor`.
|
||||
|
||||
==== Client Registration Java API
|
||||
|
||||
The Client Registration Java API makes it easy to use the Client Registration Service using Java.
|
||||
To use include the dependency `org.keycloak:keycloak-client-registration-api:>VERSION<` from Maven.
|
||||
|
||||
For full instructions on using the Client Registration refer to the JavaDocs.
|
||||
Below is an example of creating a client:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
String initialAccessToken = "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmMjJmNzQyYy04ZjNlLTQ2M....";
|
||||
|
||||
ClientRepresentation client = new ClientRepresentation();
|
||||
client.setClientId(CLIENT_ID);
|
||||
|
||||
ClientRegistration reg = ClientRegistration.create().url("http://keycloak/auth/realms/myrealm/clients").build();
|
||||
reg.auth(Auth.token(initialAccessToken));
|
||||
|
||||
client = reg.create(client);
|
||||
|
||||
String registrationAccessToken = client.getRegistrationAccessToken();
|
||||
----
|
||||
10
topics/clients/client-saml.adoc
Executable file → Normal file
10
topics/clients/client-saml.adoc
Executable file → Normal file
|
|
@ -5,7 +5,7 @@
|
|||
Both POST and Redirect bindings are supported.
|
||||
You can choose to require client signature validation and can have the server sign and/or encrypt responses as well.
|
||||
|
||||
To create a SAML client go to the `Clients` left menu item. On this page you'll see a `create` button on the right.
|
||||
To create a SAML client go to the `Clients` left menu item. On this page you'll see a `Create` button on the right.
|
||||
|
||||
.Clients
|
||||
image:../../{{book.images}}/clients.png[]
|
||||
|
|
@ -23,7 +23,7 @@ we'll go over that later in this chapter.
|
|||
Finally enter in the `Client SAML Endpoint` URL. Enter the
|
||||
URL you want the {{book.project.name}} server to send SAML requests and responses to. Usually applications have only one URL for processing SAML requests.
|
||||
If your application has different URLs for its bindings, don't worry, you can fix this in the `Settings` tab of the client.
|
||||
application in the `Root URL` field and click `Save`. This will create the client and bring you to the client `Settings`
|
||||
Click `Save`. This will create the client and bring you to the client `Settings`
|
||||
tab.
|
||||
|
||||
.Client Settings
|
||||
|
|
@ -82,7 +82,7 @@ Force POST Binding::
|
|||
|
||||
Front Channel Logout::
|
||||
If true, this application requires a browser redirect to be able to perform a logout.
|
||||
For example, the application may require a cookie to be reset which could only be done by a done via a redirect.
|
||||
For example, the application may require a cookie to be reset which could only be done via a redirect.
|
||||
If this switch is false, then {{book.project.name}} will invoke a background SAML request to logout the application.
|
||||
|
||||
Force Name ID Format::
|
||||
|
|
@ -99,14 +99,14 @@ Root URL::
|
|||
Valid Redirect URIs::
|
||||
This is an optional field. Enter in a URL pattern and click the + sign to add. Click the - sign next to URLs you want to remove.
|
||||
Remember that you still have to click the `Save` button!
|
||||
Only wildcards, * ,are allowed at the end of of a URI, i.e. http://host.com/*. This field is used when the exact SAML
|
||||
Wildcards (\*) are only allowed at the end of of a URI, i.e. http://host.com/*. This field is used when the exact SAML
|
||||
endpoints are not registered and {{book.project.name}} is pull the Assertion Consumer URL from the request.
|
||||
|
||||
Base URL::
|
||||
If {{book.project.name}} needs to link to the client, this URL would be used.
|
||||
|
||||
Master SAML Processing URL::
|
||||
This URL will be used for all SAML requests and responsed directed to the SP.
|
||||
This URL will be used for all SAML requests and the response will be directed to the SP.
|
||||
It will be used as the Assertion Consumer Service URL and the Single Logout Service URL.
|
||||
If a login request contains the Assertion Consumer Service URL, that will take precedence, but this URL must be valided by a registered Valid Redirect URI pattern
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
|
||||
=== Generating Client Adapter Config
|
||||
|
||||
The {{book.project.name}} can pre-generate configure files that you can use to install a client adapter for in your application's
|
||||
The {{book.project.name}} can pre-generate configuration files that you can use to install a client adapter for in your application's
|
||||
deployment environment. A number of adapter types are supported for both OIDC and SAML. Go to the `Installation` tab of the
|
||||
client you want to generate configuration for.
|
||||
|
||||
image:../../{{book.images}}/client-installation.png[]
|
||||
|
||||
Select the `format option` you want configuration generated for. All {{book.project.name}} client adapters for OIDC and SAML
|
||||
Select the `Format Option` you want configuration generated for. All {{book.project.name}} client adapters for OIDC and SAML
|
||||
are supported. The mod-auth-mellon Apache HTTPD adapter for SAML is supported as well as standard SAML entity descriptor files.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ type of client you have to configure the client's credentials.
|
|||
.Credentials Tab
|
||||
image:../../../{{book.images}}/client-credentials.png[]
|
||||
|
||||
The `Client Authenticator` list box is the type of credential you are going to use for your confidential client.
|
||||
The `Client Authenticator` list box specifies the type of credential you are going to use for your confidential client.
|
||||
It defaults to client ID and secret. The secret is automatically generated for you and the `Regenerate Secret`
|
||||
button allows you to recreate this secret if you want or need to.
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ generate these via an external tool and just import the client's certificate.
|
|||
.Import Certificate
|
||||
image:../../../{{book.images}}/import-client-cert.png[]
|
||||
|
||||
There's multiple formats you can import from, just choose the archive format you have the certificate stored in,
|
||||
There are multiple formats you can import from, just choose the archive format you have the certificate stored in,
|
||||
select the file, and click the `Import` button.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
=== Service Accounts
|
||||
|
||||
Each OIDC client has a built in _service account_ which allows them to obtain an access token.
|
||||
Each OIDC client has a built in _service account_ which allows it to obtain an access token.
|
||||
This is covered in the OAuth 2.0 specifiation under <<fake/../../../sso-protocols/oidc.adoc#_oidc-auth-flows,Client Credentials Grant>>
|
||||
To use this feature you must set the <<fake/../../../clients/client-oidc.adoc#_access-type, Access Type>> of your client to `confidential`. When you do this,
|
||||
the `Service Accounts Enabled` switch will appear. You need to turn on this switch. Also make sure that you have
|
||||
|
|
@ -10,14 +10,14 @@ configured your <<fake/../../../clients/oidc/confidential.adoc#_client-credentia
|
|||
|
||||
To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in {{book.project.name}} admin console for this client.
|
||||
In tab `Service Account Roles` you can configure the roles available to the service account retrieved on behalf of this client.
|
||||
Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are intersection of scopes and the service account roles.
|
||||
Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are the intersection of scopes and the service account roles.
|
||||
|
||||
The REST URL to invoke on is `/\{server-root-usualy-auth}/realms/\{realm-name}/protocol/openid-connect/token`.
|
||||
Invoking on this URL is a POST request and requires you to post the client credentials.
|
||||
By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate client with signed JWT assertion or any other custom mechanism for client authentication.
|
||||
You also need to use parameter `grant_type=client_credentials` as per OAuth2 specification.
|
||||
By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication.
|
||||
You also need to use the parameter `grant_type=client_credentials` as per the OAuth2 specification.
|
||||
|
||||
For example the POST invocation to retrieve service account can look like this:
|
||||
For example the POST invocation to retrieve a service account can look like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
@ -50,4 +50,4 @@ Pragma: no-cache
|
|||
}
|
||||
----
|
||||
|
||||
The retrieved access token can be refreshed or logged out by out-of-bound request.
|
||||
The retrieved access token can be refreshed or logged out by an out-of-bound request.
|
||||
|
|
|
|||
|
|
@ -15,19 +15,19 @@ an OIDC based client.
|
|||
.Mappers Tab
|
||||
image:../../{{book.images}}/mappers-oidc.png[]
|
||||
|
||||
Every client has a bunch of built-in mappers that are created for it by default. They map things like, for example, email address to
|
||||
a specific claim in the identity and access token. Their function should each be self explanatory from their name. There's
|
||||
is additional pre-configured mappers that are not attached to the client that you can add
|
||||
Each client has several built-in mappers that are created for it by default. They map things like, for example, email address to
|
||||
a specific claim in the identity and access token. Their function should each be self explanatory from their name. There
|
||||
are additional pre-configured mappers that are not attached to the client that you can add
|
||||
by clicking the `Add Builtin` button.
|
||||
|
||||
Each mapper has common settings as well as additional ones depending on which type of mapper you are adding. Click the `edit` button
|
||||
Each mapper has common settings as well as additional ones depending on which type of mapper you are adding. Click the `Edit` button
|
||||
next to one of the mappers in the list to get to the config screen.
|
||||
|
||||
.Mapper Config
|
||||
image:../../{{book.images}}/mapper-config.png[]
|
||||
|
||||
The best way to find out what a config option is is to moveover the tooltips. There are a few config options that
|
||||
are common to all mappers.
|
||||
The best way to learn about a config option is to hover over its tooltip. There are a few config options that
|
||||
are common to all mappers:
|
||||
|
||||
Consent::
|
||||
If your client requires consent, this mapper will be displayed on the consent screen shown to the user.
|
||||
|
|
@ -40,7 +40,7 @@ Consent Text::
|
|||
Most OIDC mappers also allow you to control where the claim gets put. You can opt to include or exclude the claim from both the
|
||||
_id_ and _access_ tokens by fiddling with the `Add to ID token` and `Add to access token` switches.
|
||||
|
||||
Finaly, you can also add other mapper types. if you go back to the `Mappers` tab, click the `Create` button.
|
||||
Finally, you can also add other mapper types. If you go back to the `Mappers` tab, click the `Create` button.
|
||||
|
||||
.Add Mapper
|
||||
image:../../{{book.images}}/add-mapper.png[]
|
||||
|
|
|
|||
3
topics/events.adoc
Executable file → Normal file
3
topics/events.adoc
Executable file → Normal file
|
|
@ -1,7 +1,8 @@
|
|||
|
||||
== Auditing and Events
|
||||
|
||||
{{book.project.name}} provides a rich set of auditing capabilities. Every single login action can be recorded and stored in
|
||||
the database and reviewed in the Admin Console. All admin actions can also be recorded and reviewed. There is also a Listener SPI
|
||||
in which plugins can listen for these events and perform some action. Built in ones include a simple log file and the ability
|
||||
with which plugins can listen for these events and perform some action. Built in listeners include a simple log file and the ability
|
||||
to send an email if an event occurs.
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
|
||||
Any action an admin performs within the admin console can be recorded for auditing purposes.
|
||||
The Admin Console performs administrative functions by invoking on the {{book.project.name}} REST interface. {{book.project.name}}
|
||||
audits the admin APIs be storing these REST invocations. These REST invocations can then be viewed in the Admin Console.
|
||||
audits these REST invocations. The resulting events can then be viewed in the Admin Console.
|
||||
|
||||
To enable auditing of Admin actions, go to the `Events` left menu item and select the `Config` tab.
|
||||
|
||||
|
|
@ -15,8 +15,7 @@ In the `Admin Events Settings` section, turn on the `Save Events` switch.
|
|||
.Admin Event Configuration
|
||||
image:../../{{book.images}}/admin-events-settings.png[]
|
||||
|
||||
The `Include Representation` switch will include any JSON document that is sent to the admin REST API when they are being
|
||||
invoked upon. This allows you to view exactly what an admin has done, but can lead to a lot of information stored in the
|
||||
The `Include Representation` switch will include any JSON document that is sent through the admin REST API. This allows you to view exactly what an admin has done, but can lead to a lot of information stored in the
|
||||
database. The `Clear admin events` button allows you to wipe out the current information stored.
|
||||
|
||||
To view the admin events go to the `Admin Events` tab.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
|
||||
=== Login Events
|
||||
|
||||
Login events occur for things like when a user logs in successfully, when somebody enters in a bad password, when a user account
|
||||
is updated. Really every single event that happens to a user can be recorded and viewed. By default, no events are stored
|
||||
or are viewable in the Admin Console. Only error events are logged to the console and the server's log file. To start
|
||||
Login events occur for things like when a user logs in successfully, when somebody enters in a bad password, or when a user account
|
||||
is updated. Every single event that happens to a user can be recorded and viewed. By default, no events are stored
|
||||
or viewed in the Admin Console. Only error events are logged to the console and the server's log file. To start
|
||||
persisting you'll need to enable storage. Go to the `Events` left menu item and select the `Config` tab.
|
||||
|
||||
.Event Configuration
|
||||
|
|
@ -15,16 +15,16 @@ To start storing events you'll need to turn the `Save Events` switch to on under
|
|||
image:../../{{book.images}}/login-events-settings.png[]
|
||||
|
||||
The `Saved Types` field allows you to specify which event types you want to store in the event store. The `Clear events`
|
||||
button allows you to delete all the events in the database. The `Expiration` file allows you to specify how long you want
|
||||
to keep events stored for. Once you've enabled storage of login events and decided on you settings, don't forget to click
|
||||
the `Save` button on the button of this page.
|
||||
button allows you to delete all the events in the database. The `Expiration` field allows you to specify how long you want
|
||||
to keep events stored. Once you've enabled storage of login events and decided on your settings, don't forget to click
|
||||
the `Save` button on the bottom of this page.
|
||||
|
||||
To view events, go to the `Login Events` tab.
|
||||
|
||||
.Login Events
|
||||
image:../../{{book.images}}/login-events.png[]
|
||||
|
||||
As you can see, there's a lot of information stored and, if you are storing every event, there's a lot of events stored for
|
||||
As you can see, there's a lot of information stored and, if you are storing every event, there are a lot of events stored for
|
||||
each login action. The `Filter` button on this page allows you to filter which events you are actually interested in.
|
||||
|
||||
.Login Event Filter
|
||||
|
|
@ -37,31 +37,31 @@ In this screenshot, we're filtering only `Login` events. Clicking the `Update`
|
|||
|
||||
Login events:
|
||||
|
||||
* Login - A user has logged in
|
||||
* Register - A user has registered
|
||||
* Logout - A user has logged out
|
||||
* Code to Token - An application/client has exchanged a code for a token
|
||||
* Refresh Token - An application/client has refreshed a token
|
||||
* Login - A user has logged in.
|
||||
* Register - A user has registered.
|
||||
* Logout - A user has logged out.
|
||||
* Code to Token - An application/client has exchanged a code for a token.
|
||||
* Refresh Token - An application/client has refreshed a token.
|
||||
|
||||
Account events:
|
||||
|
||||
* Social Link - An account has been linked to a social provider
|
||||
* Remove Social Link - A social provider has been removed from an account
|
||||
* Update Email - The email address for an account has changed
|
||||
* Update Profile - The profile for an account has changed
|
||||
* Send Password Reset - A password reset email has been sent
|
||||
* Update Password - The password for an account has changed
|
||||
* Update TOTP - The TOTP settings for an account has changed
|
||||
* Remove TOTP - TOTP has been removed from an account
|
||||
* Send Verify Email - A email verification email has been sent
|
||||
* Verify Email - The email address for an account has been verified
|
||||
* Social Link - An account has been linked to a social provider.
|
||||
* Remove Social Link - A social provider has been removed from an account.
|
||||
* Update Email - The email address for an account has changed.
|
||||
* Update Profile - The profile for an account has changed.
|
||||
* Send Password Reset - A password reset email has been sent.
|
||||
* Update Password - The password for an account has changed.
|
||||
* Update TOTP - The TOTP settings for an account have changed.
|
||||
* Remove TOTP - TOTP has been removed from an account.
|
||||
* Send Verify Email - An email verification email has been sent.
|
||||
* Verify Email - The email address for an account has been verified.
|
||||
|
||||
For all events there is a corresponding error event.
|
||||
|
||||
==== Event Listener
|
||||
|
||||
Event listeners listen for events and perform an action based on that event. There are two built in
|
||||
ones that come with {{book.project.name}}: Logging Event Listener and an Email Event Listener.
|
||||
listeners that come with {{book.project.name}}: Logging Event Listener and Email Event Listener.
|
||||
|
||||
The Logging Event Listener writes to a log file whenever an error event occurs and is enabled by default.
|
||||
Here's an example log message:
|
||||
|
|
@ -76,10 +76,10 @@ Here's an example log message:
|
|||
----
|
||||
|
||||
This logging is very useful if you want to use a tool like Fail2Ban to detect if there is a hacker bot somewhere that
|
||||
is trying to guess user passwords. You can parse the log file for `LOGIN_ERROR` and pull out the IP Address, feed this information
|
||||
into Fail2Ban so that it do what it does to prevent attacks.
|
||||
is trying to guess user passwords. You can parse the log file for `LOGIN_ERROR` and pull out the IP Address. Then feed this information
|
||||
into Fail2Ban so that it can help prevent attacks.
|
||||
|
||||
The Email Event Listener sends an email to the users account when an event occurs.
|
||||
The Email Event Listener sends an email to the user's account when an event occurs.
|
||||
The Email Event Listener only supports the following events at the moment:
|
||||
|
||||
* Login Error
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@
|
|||
|
||||
{{book.project.name}} has the ability export and import the entire database.
|
||||
This can be especially useful if you want to migrate your whole {{book.project.name}} database from one environment to another
|
||||
or migrate to different database (for example from MySQL to Oracle). Export and import
|
||||
is triggered at server boot time and it's parameters are past in via Java System properties.
|
||||
Its important to note that because import and export happens at server startup, that no other actions should be taken on the server
|
||||
or migrate to a different database (for example from MySQL to Oracle). Export and import
|
||||
is triggered at server boot time and its parameters are passed in via Java system properties.
|
||||
It is important to note that because import and export happens at server startup, no other actions should be taken on the server
|
||||
or the database while this happens.
|
||||
|
||||
You can export/import your database either to:
|
||||
|
|
@ -21,7 +21,7 @@ If you are importing files which were previously exported, the files already fol
|
|||
* {REALM_NAME}-users-{INDEX}.json, such as "acme-roadrunner-affairs-users-0.json" for the first users file of the realm named "acme-roadrunner-affairs"
|
||||
|
||||
If you export to a directory, you can also specify the number of users that will be stored in each JSON file.
|
||||
So if you have very large amount of users in your database, you likely don't want to import them into single file as the file might be very big.
|
||||
So if you have very large number of users in your database, you likely don't want to import them into single file as the file might be very big.
|
||||
|
||||
To export into unencrypted directory you can use:
|
||||
|
||||
|
|
@ -51,29 +51,29 @@ bin/standalone.sh -Dkeycloak.migration.action=import
|
|||
Other available options are:
|
||||
|
||||
-Dkeycloak.migration.realmName::
|
||||
can be used if you want to export just one specified realm instead of all.
|
||||
This property is used if you want to export just one specified realm instead of all.
|
||||
If not specified, then all realms will be exported.
|
||||
|
||||
-Dkeycloak.migration.usersExportStrategy::
|
||||
can be used to specify for Directory providers to specify where to import users.
|
||||
This property is used to specify where users are exported.
|
||||
Possible values are:
|
||||
* DIFFERENT_FILES - Users will be exported into more different files according to maximum number of users per file. This is default value
|
||||
* SKIP - exporting of users will be skipped completely
|
||||
* REALM_FILE - All users will be exported to same file with realm (So file like "foo-realm.json" with both realm data and users)
|
||||
* SAME_FILE - All users will be exported to same file but different than realm (So file like "foo-realm.json" with realm data and "foo-users.json" with users)
|
||||
* DIFFERENT_FILES - Users will be exported into different files according to the maximum number of users per file. This is default value.
|
||||
* SKIP - Exporting of users will be skipped completely.
|
||||
* REALM_FILE - All users will be exported to same file with the realm settings. (The result will be a file like "foo-realm.json" with both realm data and users.)
|
||||
* SAME_FILE - All users will be exported to same file but different from the realm file. (The result will be a file like "foo-realm.json" with realm data and "foo-users.json" with users.)
|
||||
|
||||
-Dkeycloak.migration.usersPerFile::
|
||||
can be used to specify number of users per file (and also per DB transaction). It's 5000 by default.
|
||||
This property is used to specify the number of users per file (and also per DB transaction). It's 5000 by default.
|
||||
It's used only if usersExportStrategy is DIFFERENT_FILES
|
||||
|
||||
-Dkeycloak.migration.strategy::
|
||||
is used during import.
|
||||
It can be used to specify how to proceed if realm with same name already exists in the database where you are going to import data.
|
||||
This property is used during import.
|
||||
It can be used to specify how to proceed if a realm with same name already exists in the database where you are going to import data.
|
||||
Possible values are:
|
||||
* IGNORE_EXISTING - Ignore importing if realm of this name already exists
|
||||
* OVERWRITE_EXISTING - Remove existing realm and import it again with new data from JSON file.
|
||||
If you want to fully migrate one environment to another and ensure that the new environment will contain same data
|
||||
like the old one, you can specify this.
|
||||
* IGNORE_EXISTING - Ignore importing if a realm of this name already exists.
|
||||
* OVERWRITE_EXISTING - Remove existing realm and import it again with new data from the JSON file.
|
||||
If you want to fully migrate one environment to another and ensure that the new environment will contain the same data
|
||||
as the old one, you can specify this.
|
||||
|
||||
When importing realm files that weren't exported before, the option `keycloak.import` can be used.
|
||||
If more than one realm file needs to be imported, a comma separated list of file names can be specified.
|
||||
|
|
|
|||
|
|
@ -3,9 +3,9 @@
|
|||
|
||||
Default groups allow you to automatically assign group membership whenever any new user is created or imported through
|
||||
<<fake/../../user-federation.adoc#_user-storage-federation, User Storage Federation>> or <<fake/../../identity-broker.adoc#_identity_broker, Identity Brokering>>.
|
||||
To specify _default groups go to the `Groups` left menu item, and click the `Default Groups` tab.
|
||||
To specify default groups go to the `Groups` left menu item, and click the `Default Groups` tab.
|
||||
|
||||
.Default Roles
|
||||
.Default Groups
|
||||
image:../../{{book.images}}/default-groups.png[]
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ In {{book.project.name}}, Groups are just a collection of users that you can app
|
|||
Roles define a type of user and applications assign permission and access control to roles
|
||||
|
||||
Aren't <<fake/../../roles/composite.adoc#_composite-roles,Composite Roles>> also similar to Groups?
|
||||
Logically they provide the same exact functionality, but the difference is conceptual
|
||||
Logically they provide the same exact functionality, but the difference is conceptual.
|
||||
Composite roles should be used to apply the permission model to your set of services and applications.
|
||||
Groups should focus on collections of users and their roles in your organization.
|
||||
Use groups to manage users, composite roles to manage applications and services.
|
||||
Use groups to manage users. Use composite roles to manage applications and services.
|
||||
|
|
|
|||
|
|
@ -6,13 +6,14 @@ An Identity Broker is an intermediary service that connects multiple service pro
|
|||
As an intermediary service, the identity broker is responsible for creating
|
||||
a trust relationship with an external identity provider in order to use its identities to access internal services exposed by service providers.
|
||||
|
||||
From an user perspective, an identity broker provides an user-centric and centralized way to manage identities across different security
|
||||
domains or realms, where an existing account can be linked with one or more identities from different identity providers or even created
|
||||
From a user perspective, an identity broker provides a user-centric and centralized way to manage identities across different security
|
||||
domains or realms. An existing account can be linked with one or more identities from different identity providers or even created
|
||||
based on the identity information obtained from them.
|
||||
|
||||
An identity provider is usually based on a specific protocol that is used to authenticate and communicate authentication and authorization information to their users.
|
||||
It can be a social provider such as Facebook, Google or Twitter, a business partner which you want to allow its users to access your services or a cloud-based identity
|
||||
It can be a social provider such as Facebook, Google or Twitter. It can be a business partner whose users need to access your services. Or it an be a cloud-based identity
|
||||
service that you want to integrate with.
|
||||
|
||||
Usually, identity providers are based on the following protocols:
|
||||
|
||||
* `SAML v2.0`
|
||||
|
|
|
|||
|
|
@ -25,9 +25,9 @@ image:../../{{book.images}}/identity-provider-login-page.png[]
|
|||
|
||||
|
||||
Social::
|
||||
Social providers allows you to enable social authentication to your realm.
|
||||
Social providers allow you to enable social authentication in your realm.
|
||||
{{book.project.name}} makes it easy to let users log in to your application using an existing account with a social network.
|
||||
Currently Facebook, Google, Twitter, GitHub, LinkedIn, Microsoft and StackOverflow are supported with more planned for the future.
|
||||
Currently Facebook, Google, Twitter, GitHub, LinkedIn, Microsoft, and StackOverflow are supported with more planned for the future.
|
||||
|
||||
Protocol-based::
|
||||
Protocol-based providers are those that rely on a specific protocol in order to authenticate and authorize users.
|
||||
|
|
@ -44,10 +44,10 @@ Regardless the identity provider you are creating, you'll see the following conf
|
|||
|Configuration|Description
|
||||
|
||||
|Alias
|
||||
|The alias is an unique identifier for an identity provider. It is used to reference internally an identity provider.
|
||||
Some protocols require a redirect URI or callback url in order to communicate with an identity provider. For instance, OpenID Connect.
|
||||
|The alias is an unique identifier for an identity provider. It is used to reference an identity provider internally.
|
||||
Some protocols such as OpenID Connect require a redirect URI or callback url in order to communicate with an identity provider.
|
||||
In this case, the alias is used to build the redirect URI.
|
||||
Every single identity provider must have an alias. For example, facebook, google, idp.acme.com, etc.
|
||||
Every single identity provider must have an alias. Examples are facebook, google, idp.acme.com, etc.
|
||||
|
||||
|Enabled
|
||||
|Turn the provider on/off
|
||||
|
|
@ -56,11 +56,11 @@ Regardless the identity provider you are creating, you'll see the following conf
|
|||
|Whether or not to store the token received from the identity provider.
|
||||
|
||||
|Stored Tokens Readable
|
||||
|Whether or not users are allowed to retrieve the stored identity provider token. This also applies the _broker_ client-level
|
||||
|Whether or not users are allowed to retrieve the stored identity provider token. This also applies to the _broker_ client-level
|
||||
role _read token_
|
||||
|
||||
|Trust email
|
||||
|If the identity provider supplies an email address this email address will be trusted. If the realm required email validation
|
||||
|If the identity provider supplies an email address this email address will be trusted. If the realm required email validation,
|
||||
users that log in from this IDP will not have to go through the email verification process.
|
||||
|
||||
|Authenticate By Default
|
||||
|
|
@ -72,10 +72,10 @@ Regardless the identity provider you are creating, you'll see the following conf
|
|||
|
||||
|First Login Flow
|
||||
|This is the authentication flow that will be triggered for users that log into {{book.project.name}} through this IDP
|
||||
for the first time ever
|
||||
for the first time ever.
|
||||
|
||||
|Post Login Flow
|
||||
|Authentication flow that is triggered after the user finishes logging in with the external identity provider
|
||||
|Authentication flow that is triggered after the user finishes logging in with the external identity provider.
|
||||
|===
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -9,19 +9,19 @@ there can be two situations:
|
|||
* There is already a {{book.project.name}} user account imported and linked with the authenticated identity provider account.
|
||||
In this case, {{book.project.name}} will just authenticate as the existing user and redirect back to application.
|
||||
* There is not yet an existing {{book.project.name}} user account imported and linked for this external user.
|
||||
Usually you just want to register and import the new account into {{book.project.name}} database, but what if there is existing
|
||||
Usually you just want to register and import the new account into {{book.project.name}} database, but what if there is an existing
|
||||
{{book.project.name}} account with the same email? Automatically linking the existing local account to the external
|
||||
identity provider is a potential security hole as you can't always trust the information you get from the external identity provider.
|
||||
|
||||
Different organizations have different requirements when dealing with some of the conflicts and situations listed above.
|
||||
For this, there is a `First Login Flow` option in the IDP settings which allows you to choose a <<fake/../../authentication/flows.adoc#_authentication-flows, workflow>> that will be
|
||||
used after a user logs in from an external IDP the first time.
|
||||
By default it points to `first broker login` flow, but you can configure and use your own flow and use different flows for different identity providers etc.
|
||||
By default it points to `first broker login` flow, but you can configure and use your own flow and use different flows for different identity providers.
|
||||
|
||||
The flow itself is configured in admin console under `Authentication` tab.
|
||||
When you choose `First Broker Login` flow, you will see what authenticators are used by default.
|
||||
You can either re-configure existing flow (For example disable some authenticators, mark some of them as `required`, configure some authenticators etc).
|
||||
Or you can even create new authentication flow and/or write your own Authenticator implementations and use it in your flow.
|
||||
You can re-configure the existing flow. (For example you can disable some authenticators, mark some of them as `required`, configure some authenticators, etc).
|
||||
Or you can even create a new authentication flow and/or write your own Authenticator implementations and use it in your flow.
|
||||
See link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more details.
|
||||
|
||||
==== Default First Login Flow
|
||||
|
|
@ -29,35 +29,35 @@ See link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more det
|
|||
Let's describe the default behaviour provided by `First Broker Login` flow.
|
||||
|
||||
Review Profile::
|
||||
This authenticator might display the profile info page, where user can review his profile retrieved from identity provider.
|
||||
This authenticator might display the profile info page, where the user can review his profile retrieved from an identity provider.
|
||||
The authenticator is configurable.
|
||||
You can set `Update Profile On First Login` option.
|
||||
You can set the `Update Profile On First Login` option.
|
||||
When `On`, users will be always presented with the profile page asking for additional information in order to federate their identities.
|
||||
When `missing`, users will be presented with the profile page only if some mandatory information (email, first name, last name) is not provided by identity provider.
|
||||
When `missing`, users will be presented with the profile page only if some mandatory information (email, first name, last name) is not provided by the identity provider.
|
||||
If `Off`, the profile page won't be displayed, unless user clicks in later phase on `Review profile info` link (page displayed in later phase
|
||||
by `Confirm Link Existing Account` authenticator)
|
||||
|
||||
Create User If Unique::
|
||||
This authenticator checks if there is already existing {{book.project.name}} account with same email or username like the account from identity provider.
|
||||
If it's not, then authenticator just creates a new local {{book.project.name}} account and links it with identity provider and the whole flow is finished.
|
||||
This authenticator checks if there is already an existing {{book.project.name}} account with same email or username like the account from the identity provider.
|
||||
If it's not, then the authenticator just creates a new local {{book.project.name}} account and links it with the identity provider and the whole flow is finished.
|
||||
Otherwise it goes to the next `Handle Existing Account` subflow.
|
||||
If you always want to ensure that there is no duplicated account, you can mark this authenticator as `REQUIRED` . In this case, the user
|
||||
will see the error page if there is existing {{book.project.name}} account and user needs to link his identity provider account through Account management.
|
||||
will see the error page if there is existing {{book.project.name}} account and the user will need to link his identity provider account through Account management.
|
||||
|
||||
Confirm Link Existing Account::
|
||||
On the info page, the user will see that there is an existing {{book.project.name}} account with same email.
|
||||
He can either review his profile again and use different email or username (flow is restarted and goes back to `Review Profile` authenticator).
|
||||
He can review his profile again and use different email or username (flow is restarted and goes back to `Review Profile` authenticator).
|
||||
Or he can confirm that he wants to link the identity provider account with his existing {{book.project.name}} account.
|
||||
Disable this authenticator if you don't want users to see this confirmation page, but go straight to linking identity provider account by email verification or re-authentication.
|
||||
|
||||
Verify Existing Account By Email::
|
||||
This authenticator is `ALTERNATIVE` by default, so it's used only if the realm has SMTP setup configured.
|
||||
It will send mail to user, where he can confirm that he wants to link identity provider with his {{book.project.name}} account.
|
||||
It will send mail to the user, where he can confirm that he wants to link the identity provider with his {{book.project.name}} account.
|
||||
Disable this if you don't want to confirm linking by email, but instead you always want users to reauthenticate with their password (and alternatively OTP).
|
||||
|
||||
Verify Existing Account By Re-authentication::
|
||||
This authenticator is used if email authenticator is disabled or non-available (SMTP not configured for realm). It will display login screen
|
||||
where the user needs to authenticate with his password to link his {{book.project.name}} account with Identity provider.
|
||||
This authenticator is used if email authenticator is disabled or non-available (SMTP not configured for realm). It will display a login screen
|
||||
where the user needs to authenticate with his password to link his {{book.project.name}} account with the Identity provider.
|
||||
User can also re-authenticate with some different identity provider, which is already linked to his {{book.project.name}} account.
|
||||
You can also force users to use OTP, otherwise it's optional and used only if OTP is already set for the user account.
|
||||
You can also force users to use OTP. Otherwise it's optional and used only if OTP is already set for the user account.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ You can import the SAML and OpenID Connect metadata provided by the external IDP
|
|||
of the realm. This allows you to extract user profile metadata and other information so that you can make it available to your
|
||||
applications.
|
||||
|
||||
Each new user that logs into your realm via an external identity provider will be have an entry for it created in the local
|
||||
Each new user that logs into your realm via an external identity provider will have an entry for it created in the local
|
||||
{{book.project.name}} database. The act of importing metadata from the SAML or OIDC assertions and claims will create this data
|
||||
with the local realm database.
|
||||
|
||||
|
|
@ -23,8 +23,8 @@ image:../../{{book.images}}/identity-provider-mapper.png[]
|
|||
Select a mapper from the `Mapper Type` list. Hover over the tooltip to see a description of what the mapper does. The
|
||||
tooltips also describe what configuration information you need to enter. Click `Save` and your new mapper will be added.
|
||||
|
||||
For JSON based claims, you can use dot notation for nesting and square brackets to access fields in array by index.
|
||||
For JSON based claims, you can use dot notation for nesting and square brackets to access array fields by index.
|
||||
For example 'contact.address[0].country'.
|
||||
|
||||
To investigate structure of user profile JSON data provided by social providers you can enable `DEBUG` level logger `org.keycloak.social.user_profile_dump`.
|
||||
To investigate the structure of user profile JSON data provided by social providers you can enable the `DEBUG` level logger `org.keycloak.social.user_profile_dump`.
|
||||
This is done in the server's app-server configuration file (domain.xml or standalone.xml).
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
as defined by the specification in order to authenticate the user and authorize access.
|
||||
|
||||
To begin configuring an OIDC provider, go to the `Identity Providers` left menu item
|
||||
and selected `OpenID Connect v1.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `OpenID Connect v1.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../{{book.images}}/oidc-add-identity-provider.png[]
|
||||
|
|
|
|||
|
|
@ -3,7 +3,8 @@
|
|||
=== Brokering Overview
|
||||
|
||||
When using {{book.project.name}} as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm.
|
||||
Instead , they are presented with a list of identity providers from where they can pick one and authenticate.
|
||||
Instead, they are presented with a list of identity providers from which they can authenticate.
|
||||
|
||||
You can also configure a default broker.
|
||||
In this case the user will not be given a choice, but instead be redirected directly to the parent broker.
|
||||
The following diagram demonstrates the steps involved when using {{book.project.name}} to broker an external identity provider:
|
||||
|
|
@ -13,7 +14,7 @@ image:../../images/identity_broker_flow.png[]
|
|||
|
||||
. User is not authenticated and requests a protected resource in a client application.
|
||||
. The client applications redirects the user to {{book.project.name}} to authenticate.
|
||||
. At this point the user is presented to the login page where there is a list of identity providers supported by a realm.
|
||||
. At this point the user is presented with the login page where there is a list of identity providers supported by a realm.
|
||||
. User selects one of the identity providers by clicking on its respective button or link.
|
||||
. {{book.project.name}} issues an authentication request to the target identity provider asking for authentication and the user
|
||||
is redirected to the login page of the identity provider.
|
||||
|
|
@ -27,20 +28,20 @@ image:../../images/identity_broker_flow.png[]
|
|||
If it is a new user, {{book.project.name}} may ask the identity provider for information about the user if that info doesn't already exist in the token.
|
||||
This is what we call _identity federation_.
|
||||
If the user already exists {{book.project.name}} may ask him to link the identity returned from the identity provider with his existing account.
|
||||
A process that we call _account linking_.
|
||||
We call this process _account linking_.
|
||||
What exactly is done is configurable and can be specified by setup of <<fake/../../identity-broker/first-login-flow.adoc#_identity_broker_first_login,First Login Flow>> . At the end of this step, {{book.project.name}} authenticates the user and issues its own token in order to access the requested resource in the service provider.
|
||||
. Once the user is locally authenticated, {{book.project.name}} redirects the user to the service provider by sending the token previously issued during the local authentication.
|
||||
. The service provider receives the token from {{book.project.name}} and allows access to the protected resource.
|
||||
|
||||
There are some variations of this flow that we will talk about later.
|
||||
For instance, instead of presenting a list of identity providers, the client application request a specific one.
|
||||
Or you can tell {{book.project.name}} to force the user to provide additional information before federate his identity.
|
||||
For instance, instead of presenting a list of identity providers, the client application can request a specific one.
|
||||
Or you can tell {{book.project.name}} to force the user to provide additional information before federating his identity.
|
||||
|
||||
NOTE: Different protocols may require different authentication flows.
|
||||
At this moment, all the identity providers supported by {{book.project.name}} use a flow just like described above.
|
||||
However, despite the protocol in use, user experience should be pretty much the same.
|
||||
|
||||
As you may notice, at the end of the authentication process {{book.project.name}} will always issue its own token to client applications,
|
||||
what this means is that client applications are completely decoupled from external identity providers.
|
||||
As you may notice, at the end of the authentication process {{book.project.name}} will always issue its own token to client applications.
|
||||
What this means is that client applications are completely decoupled from external identity providers.
|
||||
They don't need to know which protocol (eg.: SAML, OpenID Connect, OAuth, etc) was used or how the user's identity was validated.
|
||||
They only need to know about {{book.project.name}} !
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
{{book.project.name}} can broker identity providers based on the SAML v2.0 protocol.
|
||||
|
||||
To begin configuring an OIDC provider, go to the `Identity Providers` left menu item
|
||||
and selected `OpenID Connect v1.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `SAML v2.0` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../{{book.images}}/saml-add-identity-provider.png[]
|
||||
|
|
@ -12,7 +12,7 @@ image:../../{{book.images}}/saml-add-identity-provider.png[]
|
|||
The initial configuration options on this page are described in <<fake/../../identity-broker/configuration.adoc#_general-idp-config, General IDP Configuration>>.
|
||||
You must define the SAML configuration options as well. They basically describe the SAML IDP you are communicating with.
|
||||
|
||||
.SAML Confnig
|
||||
.SAML Config
|
||||
|===
|
||||
|Configuration|Description
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ You can also import all this configuration data by providing a URL or XML file t
|
|||
Once you create a SAML provider, there is an `EXPORT` button that appears when viewing that provider.
|
||||
Clicking this button will export a SAML SP entity descriptor which you can use to import into the external SP provider.
|
||||
|
||||
This metadata is also available publically by going to the URL
|
||||
This metadata is also available publicly by going to the URL
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -4,5 +4,5 @@
|
|||
For Internet facing applications, it is quite burdensome for users to have to register at your site to obtain access.
|
||||
It requires them to remember yet another username and password combination. Social identity providers allow you to delegate
|
||||
authentication to a semi-trusted and respected entity where the user probably already has an account.
|
||||
{{book.project.name}} provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, Github, LinkedId, Microsoft and StackOverflow.
|
||||
{{book.project.name}} provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, Github, LinkedIn, Microsoft and StackOverflow.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
==== Facebook
|
||||
|
||||
There are a number of steps you have to complete to be able to login to Facebook. First, go to the `Identity Providers` left menu item
|
||||
and selected `Facebook` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `Facebook` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../../{{book.images}}/facebook-add-identity-provider.png[]
|
||||
|
|
@ -34,12 +34,13 @@ for the application. Click the `Settings` left menu item.
|
|||
.Create a New App ID
|
||||
image:../../../images/facebook-app-settings.png[]
|
||||
|
||||
Click on the `+ Add Platform` button at the end of this page and select the `Website` icon. Cut and past the `Redirect URI` from the
|
||||
Click on the `+ Add Platform` button at the end of this page and select the `Website` icon. Copy and paste the `Redirect URI` from the
|
||||
{{book.project.name}} `Add identity provider` page into the `Site URL` of the Facebook `Website` settings block.
|
||||
|
||||
.Specify Website
|
||||
image:../../../images/facebook-app-settings-website.png[]
|
||||
|
||||
After this it is necessary to make facebook app public. Click `App Review` left menu item and switch button to "Yes".
|
||||
|
||||
You will need also to obtain the App ID and App Secret from this page so you can enter them into the {{book.project.name}} `Add identity provider` page.
|
||||
Go back to {{book.project.name}} and specify those items and finally save your Facebook Identity Provider.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
==== Github
|
||||
|
||||
There are a number of steps you have to complete to be able to login to Github. First, go to the `Identity Providers` left menu item
|
||||
and selected `Github` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `Github` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../../{{book.images}}/github-add-identity-provider.png[]
|
||||
|
|
@ -11,7 +11,7 @@ You can't click save yet, as you'll need to obtain a `Client ID` and `Client Sec
|
|||
page is the `Redirect URI`. You'll have to provide that to Github when you register {{book.project.name}} as a client there, so
|
||||
copy this URI to your clipboard.
|
||||
|
||||
To enable login with Github you first have to register an application project in the and a client in
|
||||
To enable login with Github you first have to register an application project in
|
||||
https://github.com/settings/applications[GitHub Application Settings]. Select the `Developer applications` tab.
|
||||
|
||||
NOTE: Github often changes the look and feel of application registration, so these directions might not always be up to date and the
|
||||
|
|
@ -28,7 +28,7 @@ image:../../../images/github-register-app.png[]
|
|||
|
||||
You'll have to copy the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page and enter it into the
|
||||
`Authorization callback URL` field on the Github `Register a new OAuth application` page. Once you've completed this
|
||||
page you will be brough to the application's management page.
|
||||
page you will be brought to the application's management page.
|
||||
|
||||
.Github App Page
|
||||
image:../../../images/github-app-page.png[]
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
==== Google
|
||||
|
||||
There are a number of steps you have to complete to be able to login to Google. First, go to the `Identity Providers` left menu item
|
||||
and selected `Google` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `Google` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../../{{book.images}}/google-add-identity-provider.png[]
|
||||
|
|
@ -38,7 +38,7 @@ and click the `Google+ API` link.
|
|||
image:../../../images/google-api-list.png[]
|
||||
|
||||
Click the `Enable` button on this page. You will get a message that you must create the credentials of your project.
|
||||
So click the `Go to Credentials` button
|
||||
So click the `Go to Credentials` button.
|
||||
|
||||
.Go To Credentials
|
||||
image:../../../images/google-go-to-credentials.png[]
|
||||
|
|
@ -59,7 +59,7 @@ Select `Web server` and `User data` and click the `What credentials do I need?`
|
|||
image:../../../images/google-create-oauth-id.png[]
|
||||
|
||||
Next you'll need to create an OAuth 2.0 client ID. Specify the name you want for your client. You'll also need to
|
||||
cut and paste the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page into the
|
||||
copy and paste the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page into the
|
||||
`Authorized redirect URIs` field. After you do this, click the `Create client ID` button.
|
||||
|
||||
When users log into Google from {{book.project.name}} they will see a consent screen from Google which will ask the user
|
||||
|
|
@ -78,5 +78,5 @@ Go back to {{book.project.name}} and specify those items.
|
|||
|
||||
One config option to note on the `Add identity provider` page for Google is the `Default Scopes` field.
|
||||
This field allows you to manually specify the scopes that users must authorize when authenticating with this provider.
|
||||
For a complete list of scopes, please take a look at link:https://developers.google.com/oauthplayground/. By default, {{book.project.name}}
|
||||
For a complete list of scopes, please take a look at https://developers.google.com/oauthplayground/ . By default, {{book.project.name}}
|
||||
uses the following scopes: `openid` `profile` `email`.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
==== LinkedIn
|
||||
|
||||
There are a number of steps you have to complete to be able to login to LinkedIn. First, go to the `Identity Providers` left menu item
|
||||
and selected `LinkedIn` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `LinkedIn` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../../{{book.images}}/linked-in-add-identity-provider.png[]
|
||||
|
|
@ -25,13 +25,13 @@ Click on the `Create Application` button. This will bring you to the `Create a
|
|||
.Create App
|
||||
image:../../../images/linked-in-create-app.png[]
|
||||
|
||||
Use any value for `Application Name`, `Website URL`, `Description`, `Developer Contact Email` and `Phone` you want.
|
||||
Select `r_basicprofile` and `r_emailaddress` in the `Default Scope` section.
|
||||
Click the `Add Application` button. This will bring you to the new application's settings page.
|
||||
Use any value for `Company Name`, `Name`, `Description`, and `Application Use`.
|
||||
Click the `Submit` button. This will bring you to the new application's settings page.
|
||||
|
||||
.App Settings
|
||||
image:../../../images/linked-in-app-settings.png[]
|
||||
|
||||
Select `r_basicprofile` and `r_emailaddress` in the `Default Application Permissions` section.
|
||||
You'll have to copy the `Redirect URI` from the {{book.project.name}} `Add Identity Provider` page and enter it into the
|
||||
`OAuth 2.0` `Authorized Redirect URLs` field on the LinkedIn app settings page. Don't forget to click `Update` button after
|
||||
you do this!
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
==== Microsoft
|
||||
|
||||
There are a number of steps you have to complete to be able to login to Microsoft. First, go to the `Identity Providers` left menu item
|
||||
and selected `Microsoft` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `Microsoft` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../../{{book.images}}/microsoft-add-identity-provider.png[]
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
==== StackOverflow
|
||||
|
||||
There are a number of steps you have to complete to be able to login to StackOverflow. First, go to the `Identity Providers` left menu item
|
||||
and selected `StackOverflow` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `StackOverflow` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../../{{book.images}}/stack-overflow-add-identity-provider.png[]
|
||||
|
|
@ -16,7 +16,7 @@ NOTE: StackOverflow often changes the look and feel of application registration,
|
|||
.Register Application
|
||||
image:../../../images/stack-overflow-app-register.png[]
|
||||
|
||||
Enter in the application name and the dns domain name of your application and click `Register your Application`. Type in anything you want
|
||||
Enter in the application name and the OAuth Domain Name of your application and click `Register your Application`. Type in anything you want
|
||||
for the other items.
|
||||
|
||||
.Settings
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
==== Twitter
|
||||
|
||||
There are a number of steps you have to complete to be able to login to Twitter. First, go to the `Identity Providers` left menu item
|
||||
and selected `Twitter` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
and select `Twitter` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
|
||||
|
||||
.Add Identity Provider
|
||||
image:../../../{{book.images}}/twitter-add-identity-provider.png[]
|
||||
|
|
@ -11,7 +11,7 @@ You can't click save yet, as you'll need to obtain a `Client ID` and `Client Sec
|
|||
page is the `Redirect URI`. You'll have to provide that to Twitter when you register {{book.project.name}} as a client there, so
|
||||
copy this URI to your clipboard.
|
||||
|
||||
To enable login with Twtter you first have to create an application in the https://dev.twitter.com/apps[Twitter Developer Console].
|
||||
To enable login with Twtter you first have to create an application in the https://dev.twitter.com/apps[Twitter Application Management].
|
||||
|
||||
.Register Application
|
||||
image:../../../images/twitter-app-register.png[]
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
|
||||
=== Client Suggested Identity Provider
|
||||
|
||||
Each identity provider has an option `Authenticate By Default`, which allows that Identity provider is automatically selected during authentication.
|
||||
User won't even see the {{book.project.name}} login page and will instead be automatically redirected to the default identity provider.
|
||||
Each identity provider has an option `Authenticate By Default`, which allows that Identity provider to be automatically selected during authentication.
|
||||
The user won't see the {{book.project.name}} login page and will instead be automatically redirected to the default identity provider.
|
||||
|
||||
OIDC applications can also bypass the {{book.project.name}} login page by specifying a hint on which
|
||||
identity provider they want to use.
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Authorization: Bearer {keycloak_access_token}
|
|||
An application must have authenticated with {{book.project.name}} and have received an access token. This access token
|
||||
will need to have the `broker` client-level role `read-token` set. This means that the user must have a role mapping for this role
|
||||
and the client application must have that role within its scope.
|
||||
In this case, given that you are accessing an protected service in {{book.project.name}}, you need to send the access token issued by {{book.project.name}} during the user authentication.
|
||||
In this case, given that you are accessing a protected service in {{book.project.name}}, you need to send the access token issued by {{book.project.name}} during the user authentication.
|
||||
|
||||
In the broker configuration page you can automatically assign this role to newly imported users by turning on the `Stored Tokens Readable` switch.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
|
||||
== Login Page Settings
|
||||
|
||||
There are a bunch of nice built in login page features you can enable if you need the functionality.
|
||||
There are several nice built in login page features you can enable if you need the functionality.
|
||||
|
|
@ -18,7 +18,7 @@ to a page where they can enter in their username or email and receive an email w
|
|||
.Forgot Password Page
|
||||
image:../../{{book.images}}/forgot-password-page.png[]
|
||||
|
||||
The text sent in the email is completely configurable you just need to extend or edit the theme associated with it.
|
||||
The text sent in the email is completely configurable. You just need to extend or edit the theme associated with it.
|
||||
See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information.
|
||||
|
||||
When the user clicks on the email link, they will be asked to update their password, and, if they have an OTP generator
|
||||
|
|
|
|||
|
|
@ -6,25 +6,25 @@ 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.
|
||||
username, address, phone number, and birth day. They can be assigned group membership and have specific roles assigned to them.
|
||||
authentication::
|
||||
The process of identifying and validating a user.
|
||||
authorization::
|
||||
The process of granting access to a user.
|
||||
credentials:
|
||||
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
|
||||
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.
|
||||
`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.
|
||||
|
|
@ -36,14 +36,14 @@ clients::
|
|||
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}}
|
||||
client adapters::
|
||||
Client adapters are plugins that you have to install into your application environment to be able to communicate and be secured by {{book.project.name}}. {{book.project.name}}
|
||||
has a number of ones for different platforms that you can download. There's also third-party ones you can get for environments that we don't cover.
|
||||
Client adapters are plugins that you install into your application environment to be able to communicate and be secured by {{book.project.name}}. {{book.project.name}}
|
||||
has a number of adapters for different platforms that you can download. There are also third-party adapters you can get for environments that we don't cover.
|
||||
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.
|
||||
information is requested of the user. User can decide whether or not to grant the request.
|
||||
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
|
||||
When a client is registered you need to enter 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.
|
||||
client role::
|
||||
Clients can define roles that are specific to them. This is basically a role namespace dedicated to the client.
|
||||
|
|
@ -56,7 +56,7 @@ assertion::
|
|||
Information about a user. This usually pertains to an XML blob that is included in a SAML authentication response that
|
||||
provided identity metadata about an authenticated user.
|
||||
service account::
|
||||
Each client has a built in service account which allows them to obtain an access token.
|
||||
Each client has a built in service account which allows it to obtain an access token.
|
||||
direct grant::
|
||||
A way for a client to obtain an access token on behalf of a user via a REST invocation.
|
||||
protocol mappers::
|
||||
|
|
@ -72,18 +72,18 @@ 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
|
||||
Facebook or Google+ is an example of identity provider federation. You can also hook {{book.project.name}} to delegate
|
||||
authentication to any other Open ID Connect or SAML 2.0 IDP.
|
||||
identity provider mappers::
|
||||
When doing IDP federation you can map incoming tokens and assertions to user and session attributes. This helps you propagate identity information from the external IDP
|
||||
to your client requesting authentication.
|
||||
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
|
||||
Required actions are actions a user must perform during the authentication process. 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
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ this to add a realm.
|
|||
image:../../{{book.images}}/add-realm-menu.png[]
|
||||
|
||||
This menu option will bring you to the `Add Realm` page. Specify the realm name you want to define and click the `Create` button.
|
||||
Alternatively you and import a JSON document that defines your new realm. We'll go over this in more detail in the
|
||||
Alternatively you can import a JSON document that defines your new realm. We'll go over this in more detail in the
|
||||
<<fake/../../export-import.adoc#_export_import, Export and Import>> chapter.
|
||||
|
||||
.Create Realm
|
||||
|
|
|
|||
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
=== Email Settings
|
||||
|
||||
{{book.project.name}} sends emails to users to verify their email address, when the forget their passwords, or when an admin needs to
|
||||
{{book.project.name}} sends emails to users to verify their email address, when they forget their passwords, or when an admin needs to
|
||||
receive notifications about a server event.
|
||||
To enable {{book.project.name}} to send emails you need to provide {{book.project.name}} with your SMTP server settings.
|
||||
This is configured per realm. Go to the `Realm Settings` left menu
|
||||
item and click the `Email` tab.
|
||||
|
||||
.Themes Tab
|
||||
.Email Tab
|
||||
image:../../{{book.images}}/email-tab.png[]
|
||||
|
||||
As emails are used for recovering usernames and passwords it's recommended to use SSL or TLS, especially if the SMTP server is on an external network.
|
||||
|
|
|
|||
|
|
@ -2,10 +2,10 @@
|
|||
=== Realm Key Pairs
|
||||
|
||||
The authentication protocols that are used by {{book.project.name}} require cryptographic signatures and sometimes even
|
||||
encryption. {{book.project.name}} uses a asymmetric key pair, a private and public key to accomplish this. When a realm
|
||||
encryption. {{book.project.name}} uses an asymmetric key pair, a private and public key to accomplish this. When a realm
|
||||
is created a key pair is automatically generated. It is recommended that you cycle this key pair occasionally. How often
|
||||
you do this is dependent on your organizational needs and security requirements as you have to make sure every application
|
||||
that needs the public or certificate of your realm get this updated. This can be a lot of work!
|
||||
that needs the public key or certificate of your realm gets this updated. This can be a lot of work!
|
||||
|
||||
To cycle a key pair click on the `Realm Settings` left menu item, go to the `Keys` tab, and push the `Generate new keys` button.
|
||||
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ The link:{{book.developerguide.link}}[{{book.developerguide.name}}] goes into ho
|
|||
|
||||
==== Internationalization
|
||||
|
||||
Every UI screen is internationalized in {{book.project.name}}. The default language is english, but if you turn on the
|
||||
Every UI screen is internationalized in {{book.project.name}}. The default language is English, but if you turn on the
|
||||
`Internationalization` switch on the `Theme` tab you can choose which locales you want to support and what the default locale
|
||||
will be. The next time a user logs in, they will be able to choose a language on the login page to use for the login screens,
|
||||
User Account Management UI, and Admin Console. The link:{{book.developerguide.link}}[{{book.developerguide.name}}] explains
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ client registered with the realm, attackers can get access tokens that have a br
|
|||
network is compromised. This is where _client scope_ becomes important.
|
||||
|
||||
_Client scope_ is a way to limit the roles that get declared inside an access token. When a client requests that a user
|
||||
be authenticated the access token they receive back will only contain the role mappings you've explicitly specified
|
||||
be authenticated, the access token they receive back will only contain the role mappings you've explicitly specified
|
||||
for the client's scope. This allows you to limit the permissions each individual access token has rather than giving the
|
||||
client access to all of the user's permissions. By default, each client gets all the role mappings of the user.
|
||||
You can view this in the `Scope` tab of each client.
|
||||
|
|
@ -18,7 +18,7 @@ You can view this in the `Scope` tab of each client.
|
|||
.Full Scope
|
||||
image:../../{{book.images}}/full-client-scope.png[]
|
||||
|
||||
As you can see from the picture, you can see that the effect roles of the scope are every declared role in the realm.
|
||||
You can see from the picture that the effective roles of the scope are every declared role in the realm.
|
||||
To change this default behavior, you must explicitly turn off the `Full Scope Allowed` switch and declare the specific roles you want in each individual
|
||||
client. Alternatively, you can also use <<fake/../../clients/clienttemplates.adoc#_client_templates, client templates>>
|
||||
to define the scope for a whole set of clients.
|
||||
|
|
|
|||
|
|
@ -19,6 +19,6 @@ consent page for the user.
|
|||
|
||||
=== Client Roles
|
||||
|
||||
Client roles are basically a namespace dedicated to clients. Each client gets its own namespace. Client roles are managed
|
||||
Client roles are basically a namespace dedicated to a client. Each client gets its own namespace. Client roles are managed
|
||||
under the `Roles` tab under each individual client. You interact with this UI the same way you do for realm level roles.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
== User Session Management
|
||||
|
||||
When a user logs into a realm, {{book.project.name}} maintains a user session for them and remembers each and every client they
|
||||
have visited within the session. There's a lot of administrative
|
||||
have visited within the session. There are a lot of administrative
|
||||
functions that realm admins can perform on these user sessions. They can view login stats for the entire realm and dive down
|
||||
into each client to see who is logged in and where. Admins can logout a user or set of users from the Admin Console. They
|
||||
can revoke tokens and setup all the token and session timeouts there too.
|
||||
can revoke tokens and set up all the token and session timeouts there too.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ users in the realm by clicking the `Logout all` button on the right side of this
|
|||
==== Logout All Limitations
|
||||
|
||||
Any SSO cookies set will now be invalid and clients that request authentication in active browser sessions will now have to
|
||||
relogin. Only certain clients are notified of this logout event, specifically clients that are using the {{book.projec.name}}
|
||||
re-login. Only certain clients are notified of this logout event, specifically clients that are using the {{book.projec.name}}
|
||||
OIDC client adapter. Other client types (i.e. SAML) will not receive a backchannel logout request.
|
||||
|
||||
It is important to note that any outstanding access tokens are not revoked by clicking `Logout all`. They have to
|
||||
|
|
@ -29,7 +29,7 @@ image:../../{{book.images}}/application-sessions.png[]
|
|||
|
||||
==== User Drilldown
|
||||
|
||||
If you go to the `Sessions` tab of an individual user, you can also view there session information.
|
||||
If you go to the `Sessions` tab of an individual user, you can also view the session information.
|
||||
|
||||
.User Sessions
|
||||
image:../../{{book.images}}/user-sessions.png[]
|
||||
|
|
|
|||
|
|
@ -2,19 +2,19 @@
|
|||
|
||||
=== Offline Access
|
||||
|
||||
The Offline access is the feature described in http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification] .
|
||||
The idea is that during login, your client application will request Offline token instead of classic Refresh token.
|
||||
Offline access is a feature described in http://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification] .
|
||||
The idea is that during login, your client application will request an Offline token instead of a classic Refresh token.
|
||||
The application can save this offline token in a database or on disk and can use it later even if user is logged out.
|
||||
This is useful if your application needs to do some "offline" actions on behalf of user even if user is not online
|
||||
like periodic backup of some data every night etc.
|
||||
This is useful if your application needs to do some "offline" actions on behalf of user even when the user is not online.
|
||||
An example is a periodic backup of some data every night.
|
||||
|
||||
Your application is responsible to persist the offline token in some storage (usually database) and then use it to manually retrieve new access token from {{book.project.name}} server.
|
||||
Your application is responsible for persisting the offline token in some storage (usually a database) and then using it to manually retrieve new access token from {{book.project.name}} server.
|
||||
|
||||
The difference between classic Refresh token and Offline token is, that offline token will never expire and is not subject of `SSO Session Idle timeout` .
|
||||
The difference between a classic Refresh token and an Offline token is, that an offline token will never expire and is not subject of `SSO Session Idle timeout` .
|
||||
The offline token is valid even after a user logout or server restart.
|
||||
However you do need to use the offline token for refresh token action at least once per each 30 days ( The value can be changed in admin console.
|
||||
It is `Offline Session Idle timeout` ). Also if you enable option `Revoke refresh tokens`, then each offline token can be used just once.
|
||||
So after refresh, you always need to store new offline token from refresh response into your DB instead of the previous one.
|
||||
However you do need to use the offline token for a refresh token action at least once per 30 days ( This value can be changed in admin console.
|
||||
It is `Offline Session Idle timeout` ). Also if you enable the option `Revoke refresh tokens`, then each offline token can be used just once.
|
||||
So after refresh, you always need to store the new offline token from refresh response into your DB instead of the previous one.
|
||||
|
||||
Users can view and revoke offline tokens that have been granted by them in the <<fake/../../account.adoc#_account-service, User Account Service>>.
|
||||
The admin user can revoke offline tokens for individual users in admin console in the `Consent` tab of a particular user.
|
||||
|
|
@ -24,7 +24,7 @@ Offline tokens can also be revoked by setting a <<fake/../../sessions/revocation
|
|||
To be able to issue an offline token, users need to have the role mapping for the realm-level role `offline_access`.
|
||||
Clients also need to have that role in their scope.
|
||||
|
||||
The client can request offline token by adding the parameter `scope=offline_access` when sending authorization request to {{book.project.name}}.
|
||||
The {{book.project.name}} OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (ie.
|
||||
The client can request an offline token by adding the parameter `scope=offline_access` when sending authorization request to {{book.project.name}}.
|
||||
The {{book.project.name}} OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (i.e.
|
||||
http://localhost:8080/customer-portal/secured?scope=offline_access ). The Direct Access Grant and Service Accounts also
|
||||
support offline tokens if you include `scope=offline_access` in the body of the authentication request.
|
||||
|
|
|
|||
|
|
@ -14,29 +14,29 @@ Let's walk through each of the items on this page.
|
|||
|Configuration|Description
|
||||
|
||||
|Revoke Refresh Token
|
||||
|For OIDC clients that doing the refresh token flow, this flag, if on, will revoke that refresh token and issue another with the request that the client has to use.
|
||||
|For OIDC clients that are doing the refresh token flow, this flag, if on, will revoke that refresh token and issue another with the request that the client has to use.
|
||||
This basically means that refresh tokens have a one time use.
|
||||
|
||||
|SSO Session Idle
|
||||
|Also pertains to OIDC clients. If the user is not active for long than this timeout, the user session will be invalidated. How is idle time checked?
|
||||
|Also pertains to OIDC clients. If the user is not active for longer than this timeout, the user session will be invalidated. How is idle time checked?
|
||||
A client requesting authentication will bump the idle timeout. Referesh token requests will also bump the idle timeout.
|
||||
|
||||
|SSO Session Max
|
||||
|Maximum time before a user session is expired and invalidated. This is a hard number and time. It controls the maximum time
|
||||
a user session can remain active, irregardless of activity.
|
||||
a user session can remain active, regardless of activity.
|
||||
|
||||
|Offline Session Idle
|
||||
|For <<fake/../../sessions/offline.adoc#_offline-access, offline access>>, this is the time the session is allowed
|
||||
to remain Idle before the offline token is revoked.
|
||||
|
||||
|Access Token Lifespan
|
||||
|When an OIDC access token is created, this value effects the expiration.
|
||||
|When an OIDC access token is created, this value affects the expiration.
|
||||
|
||||
|Client login timeout
|
||||
|This is the maximum time that a client has to finish the Authentication Code Flow in OIDC.
|
||||
|
||||
|Login timeout
|
||||
|Total time a login must take. Anything beyond this time and the user will have to start the authentication process over.
|
||||
|Total time a login must take. If authentication takes longer than this time then the user will have to start the authentication process over.
|
||||
|
||||
|Login action timeout
|
||||
|Maximum time a user can spend on any one page in the authentication process.
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@
|
|||
|
||||
link:http://openid.net/connect/[Open ID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0].
|
||||
While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization
|
||||
protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define a
|
||||
protocol. OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards. These standards define an
|
||||
identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way.
|
||||
|
||||
There is really two types of use cases when using OIDC. The first is an application that asks the {{book.project.name}} server to authenticate
|
||||
There are really two types of use cases when using OIDC. The first is an application that asks the {{book.project.name}} server to authenticate
|
||||
a user for them. After a successful login, the application will receive an _identity token_ and an _access token_. The _identity token_
|
||||
contains information about the user such as username, email, and other profile information. The _access token_ is digitally signed by
|
||||
the realm and contains access information (like user role mappings) that the application can use to determine what resources the user
|
||||
|
|
@ -30,14 +30,14 @@ OIDC and OAuth 2.0 specifications so only a brief overview will be provided here
|
|||
|
||||
===== Authorization Code Flow
|
||||
|
||||
This is a browser-based protocol and what we recommend you use to authenticate and authorize browser-based applications. It makes
|
||||
heavy use of browser redirects to obtain an _identity_ and _access_ token. Here's a brief summary
|
||||
This is a browser-based protocol and it is what we recommend you use to authenticate and authorize browser-based applications. It makes
|
||||
heavy use of browser redirects to obtain an _identity_ and _access_ token. Here's a brief summary:
|
||||
|
||||
. Browser visits application. The application notices the user is not logged in, so it redirects the browser to {{book.project.name}}
|
||||
to be authenticated. The application passes along a callback URL (a redirect URL) as a query parameter in this browser redirect
|
||||
that {{book.project.name}} will use when it finishes authentication.
|
||||
. {{book.project.name}} authenticates the user and creates a one-time, very short lived, temporary code. {{book.project.name}}
|
||||
redirects back to the application using the callback URL provided earlier and additionally adding the temporary code
|
||||
redirects back to the application using the callback URL provided earlier and additionally adds the temporary code
|
||||
as a query parameter in the callback URL.
|
||||
. The application extracts the temporary code and makes a background out of band REST invocation to {{book.project.name}}
|
||||
to exchange the code for an _identity_, _access_ and _refresh_ token. Once this temporary code has been used once
|
||||
|
|
@ -53,18 +53,16 @@ has revoked access. This makes things more secure and more scalable.
|
|||
Another important aspect of this flow is the concept of a _public_ vs. a _confidential_ client. _Confidential_ clients are required
|
||||
to provide a client secret when they exchange the temporary codes for tokens. _Public_ clients are not required to provide this client secret.
|
||||
_Public_ clients are perfectly fine so long as HTTPS is strictly enforced and you are very strict about what redirect URIs are registered for the
|
||||
client. HTML5/JavaScript clients actually always have to be _public_ clients because there is no way to transmit the client secret to them in a secure
|
||||
client. HTML5/JavaScript clients always have to be _public_ clients because there is no way to transmit the client secret to them in a secure
|
||||
manner. Again, this is ok so long as you use HTTPS and strictly enforce redirect URI registration. This guide goes more detail
|
||||
into this in the
|
||||
|
||||
// DOCS REMARK: Please update the cross-reference as it does not resolve correctly. <<fake/../../client.adoc,Client>> chapter.
|
||||
into this in the <<fake/../../clients.adoc#_clients, Managing Clients>> chapter.
|
||||
|
||||
===== Implicit Flow
|
||||
|
||||
This is a browser-based protocol that is similar to Authorization Code Flow except there are fewer requests and no refresh tokens involved.
|
||||
We do not recommend this flow as there remains the possibility of _access_ tokens being leaked in the browser history as tokens are transmitted
|
||||
via redirect URIs (see below). Also, since this flow doesn't provide the client with a refresh token, access tokens would either have to
|
||||
be long-lived or users would have to re-authenticate when they expired. This flow is supported because its in the OIDC and OAuth 2.0 specification.
|
||||
be long-lived or users would have to re-authenticate when they expired. This flow is supported because it is in the OIDC and OAuth 2.0 specification.
|
||||
Here's a brief summary of the protocol:
|
||||
|
||||
. Browser visits application. The application notices the user is not logged in, so it redirects the browser to {{book.project.name}}
|
||||
|
|
@ -77,7 +75,7 @@ Here's a brief summary of the protocol:
|
|||
|
||||
===== Resource Owner Password Credentials Grant (Direct Grants)
|
||||
|
||||
This is referred to in the Admin Console as _Direct Grants_ This is used by REST clients that want to obtain a token on behalf of a user. It is one HTTP POST request that contains
|
||||
This is referred to in the Admin Console as _Direct Grants_. This is used by REST clients that want to obtain a token on behalf of a user. It is one HTTP POST request that contains
|
||||
the credentials of the user as well as the id of the client and the client's secret (if it is a confidential client). The user's credentials
|
||||
are sent within form parameters. The HTTP response contains
|
||||
_identity_, _access_, and _refresh_ tokens.
|
||||
|
|
@ -86,6 +84,7 @@ _identity_, _access_, and _refresh_ tokens.
|
|||
|
||||
This is also used by REST clients, but instead of obtaining a token that works on behalf
|
||||
of an external user, a token is created based on the metadata and permissions of a service account that is associated with the client.
|
||||
More info together with example is in <<fake/../../clients/oidc/service-accounts.adoc#_service_accounts,Service Accounts>> chapter.
|
||||
|
||||
==== {{book.project.name}} Server OIDC URI Endpoints
|
||||
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
=== OIDC vs. SAML
|
||||
|
||||
Choosing between OIDC and SAML is not just a matter of using a newer, sexier protocol (OIDC) instead of the old, mature, dinosaur (SAML).
|
||||
{{book.project.name}} has chosen OIDC as the protocol we use to both recommend and write all our extensions on top of.
|
||||
{{book.project.name}} has chosen OIDC as the protocol we recommend. It is also what we use with all of our extensions.
|
||||
SAML tends to be a bit more verbose than OIDC.
|
||||
|
||||
Beyond verbosity of exchanged data, if you compare the specifications you'll find that OIDC was designed to work with the
|
||||
web while SAML was retrofitted to work on top of the web. For example,
|
||||
OIDC is also much better suited for HTML5/JavaScript applications because it is
|
||||
OIDC is much better suited for HTML5/JavaScript applications because it is
|
||||
much much simpler to implement on the client side than SAML. Since tokens are in the JSON format,
|
||||
they can be directly consumed by JavaScript. Also, you'll find many nice little switches and features that
|
||||
make implementing security in your web applications easier. For example, check out the iframe trick that the specification
|
||||
|
|
|
|||
|
|
@ -2,13 +2,11 @@
|
|||
|
||||
=== SAML
|
||||
|
||||
link://https://saml.org/fill/this/in[SAML 2.0] is a similar specification to OIDC but a lot older and more mature. It has its roots in SOAP and the plethora
|
||||
link:http://saml.xml.org/saml-specifications[SAML 2.0] is a similar specification to OIDC but a lot older and more mature. It has its roots in SOAP and the plethora
|
||||
of WS-* specifications so it tends to be a bit more verbose than OIDC. SAML 2.0 is primarily an authentication protocol
|
||||
that works by exchanging XML documents between the authentication server and the application. XML signatures and encryption
|
||||
is used to verify requests and responses.
|
||||
|
||||
In {{book.project.name}} SAML serves two types of use cases: browser applications and REST invocations.
|
||||
|
||||
There is really two types of use cases when using SAML. The first is an application that asks the {{book.project.name}} server to authenticate
|
||||
a user for them. After a successful login, the application will receive an XML document that contains
|
||||
something called a SAML assertion that specify various attributes about the user. This XML document is digitally signed by
|
||||
|
|
@ -22,7 +20,7 @@ to obtain an SAML assertion it can use to invoke on other remote services on beh
|
|||
|
||||
SAML defines a few different ways to exchange XML documents when executing the authentication protocol. The _Redirect_ and _Post_ bindings
|
||||
cover browser based applications. The _ECP_ binding covers REST invocations. There are other binding types but {{book.project.name}} only
|
||||
supports those 3.
|
||||
supports those three.
|
||||
|
||||
===== Redirect Binding
|
||||
|
||||
|
|
@ -31,14 +29,14 @@ how it works.
|
|||
|
||||
. The user visits the application and the application finds the user is not authenticated. It generates an XML authentication
|
||||
request document and encodes it as a query param in a URI that is used to redirect to the {{book.project.name}} server.
|
||||
Depending on your settings, the application may also digitally sign this XML document and also stuffs this signature as a query
|
||||
param in the redirect URI to {{book.project.name}}. This is signature is used to validate the client that sent this
|
||||
Depending on your settings, the application may also digitally sign this XML document and also stuff this signature as a query
|
||||
param in the redirect URI to {{book.project.name}}. This signature is used to validate the client that sent this
|
||||
request.
|
||||
. The browser is redirected to {{book.project.name}}. The server extracts the XML auth request document and verifies
|
||||
the digital signature if required. The user then has to enter in their credentials to be authenticated
|
||||
the digital signature if required. The user then has to enter in their credentials to be authenticated.
|
||||
. After authentication, the server generates an XML authentication response document. This document contains
|
||||
a SAML assertion that holds metadata about the user like name, address, email, and also an role mappings the user
|
||||
might have. This document is almost always digitally signed and using XML signatures, and may also be encrypted.
|
||||
a SAML assertion that holds metadata about the user like name, address, email, and any role mappings the user
|
||||
might have. This document is almost always digitally signed using XML signatures, and may also be encrypted.
|
||||
. The XML auth response document is then encoded as a query param in a redirect URI that brings the browser back
|
||||
to the application. The digital signature is also included as a query param.
|
||||
. The application receives the redirect URI and extracts the XML document and verifies the realm's signature to make
|
||||
|
|
@ -47,7 +45,7 @@ how it works.
|
|||
|
||||
===== POST Binding
|
||||
|
||||
The SAML _POST_ binding works almost the exact same way as the _Redirect_ Binding, but instead of GET requests, XML
|
||||
The SAML _POST_ binding works almost the exact same way as the _Redirect_ binding, but instead of GET requests, XML
|
||||
documents are exchanged by POST requests. The _POST_ Binding uses JavaScript to trick the browser into making a POST request to
|
||||
the {{book.project.name}} server or application when exchanging documents. Basically HTTP responses contain an HTML document
|
||||
that contains an HTML form with embedded JavaScript. When the page is loaded, the JavaScript automatically invokes the form.
|
||||
|
|
@ -55,13 +53,14 @@ You really don't need to know about this stuff, but it is a pretty clever trick.
|
|||
|
||||
===== ECP
|
||||
|
||||
TODO. Ask Pedro to fill in.
|
||||
ECP stands for "Enhanced Client or Proxy", a SAML v.2.0 profile which allows for the exchange of SAML attributes outside the context of a web browser.
|
||||
This is used most often for REST or SOAP-based clients.
|
||||
|
||||
==== {{book.project.name}} Server OIDC URI Endpoints
|
||||
==== {{book.project.name}} Server SAML URI Endpoints
|
||||
|
||||
{{book.project.name}} really only has one endpoint for all SAML requests.
|
||||
|
||||
http(s)://authserver.host/auth/realms/\{realm-name}/protocol/saml
|
||||
`http(s)://authserver.host/auth/realms/\{realm-name}/protocol/saml`
|
||||
|
||||
All bindings use this endpoint.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,15 +7,15 @@ Out of the box we have support for LDAP and Active Directory.
|
|||
Before you dive into this, you should understand how {{book.project.name}} does federation.
|
||||
|
||||
{{book.project.name}} performs federation a bit differently than other products/projects.
|
||||
The vision of {{book.project.name}} is that it is an out of the box solution that should provide a core set of feature irregardless of the backend user storage you want to use.
|
||||
The vision of {{book.project.name}} is that it is an out of the box solution that should provide a core set of features regardless of the backend user storage you want to use.
|
||||
Because of this requirement/vision, {{book.project.name}} has a set data model that all of its services use.
|
||||
Most of the time when you want to federate an external user store, much of the metadata that would be needed to provide this complete feature set does not exist in that external store.
|
||||
For example your LDAP server may only provide password validation, but not support TOTP or user role mappings.
|
||||
The {{book.project.name}} User Federation SPI was written to support these completely variable configurations.
|
||||
|
||||
The way user federation works is that {{book.project.name}} will import your federated users on demand to its local storage.
|
||||
How much metadata that is imported depends on the underlying federation plugin and how that plugin is configured.
|
||||
Some federation plugins may only import the username into {{book.project.name}} storage, others might import everything from name, address, and phone number, to user role mappings.
|
||||
How much metadata is imported depends on the underlying federation plugin and how that plugin is configured.
|
||||
Some federation plugins may only import the username into {{book.project.name}} storage. Others might import everything from name, address, and phone number, to user role mappings.
|
||||
Some plugins might want to import credentials directly into {{book.project.name}} storage and let {{book.project.name}} handle credential validation.
|
||||
Others might want to handle credential validation themselves.
|
||||
The goal of the User Storage Federation SPI is to support all of these scenarios.
|
||||
|
|
@ -27,5 +27,5 @@ To add a storage provider go to the `User Federation` left menu item in the Admi
|
|||
.User Federation
|
||||
image:../{{book.images}}/user-federation.png[]
|
||||
|
||||
On the right side, there is a `Add Provider` list box. Choose the provider you want to add and you will be brought to the configuration page of that provider.
|
||||
On the right side, there is an `Add Provider` list box. Choose the provider you want to add and you will be brought to the configuration page of that provider.
|
||||
|
||||
|
|
|
|||
66
topics/user-federation/ldap.adoc
Executable file → Normal file
66
topics/user-federation/ldap.adoc
Executable file → Normal file
|
|
@ -3,7 +3,7 @@
|
|||
=== LDAP and Active Directory
|
||||
|
||||
{{book.project.name}} comes with a built-in LDAP/AD plugin.
|
||||
By default, it is set up only to import username, email, first and last name, but you are free to configure additional <<_ldap_mappers,mappers>>
|
||||
By default, it is set up only to import username, email, first name, and last name. But you are free to configure additional <<_ldap_mappers,mappers>>
|
||||
and add more attributes or delete the default ones.
|
||||
It supports password validation via LDAP/AD protocols and different user metadata synchronization modes.
|
||||
To configure a federated LDAP store go to the Admin Console.
|
||||
|
|
@ -14,20 +14,20 @@ Selecting _ldap_ will bring you to the ldap configuration page.
|
|||
|
||||
==== Edit Mode
|
||||
|
||||
Users, through the <<fake/../../account.adoc#_account-service, User Account Service, and admins through the Admin Console
|
||||
Users, through the <<fake/../../account.adoc#_account-service, User Account Service>>, and admins through the Admin Console
|
||||
have the ability to modify user metadata. Depending on your setup you may or may not have LDAP update privileges. The
|
||||
`Edit Mode` configuration option defines the edit policy you have with your LDAP store.t privileges you have.
|
||||
`Edit Mode` configuration option defines the edit policy you have with your LDAP store.
|
||||
|
||||
READONLY::
|
||||
Username, email, first and last name and other mapped attributes will be unchangeable.
|
||||
Username, email, first name, last name, and other mapped attributes will be unchangeable.
|
||||
{{book.project.name}} will show an error anytime anybody tries to update these fields.
|
||||
Also, password updates will not be supported.
|
||||
|
||||
WRITABLE::
|
||||
Username, email, first and last name, other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store.
|
||||
Username, email, first name, last name, and other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store.
|
||||
|
||||
UNSYNCED::
|
||||
Any changes to username, email, first and last name, and passwords will be stored in {{book.project.name}} local storage.
|
||||
Any changes to username, email, first name, last name, and passwords will be stored in {{book.project.name}} local storage.
|
||||
It is up to you to figure out how to synchronize back to LDAP. This allows {{book.project.name}} deployments to support
|
||||
updates of user metadata on a read-only LDAP server.
|
||||
|
||||
|
|
@ -40,7 +40,7 @@ Priority::
|
|||
The priority of this provider when looking up users or for adding registrations.
|
||||
|
||||
Sync Registrations::
|
||||
If a new user is added through a registration page or admin console, should the user be eligible to be synchronized to this provider.
|
||||
If a new user is added through a registration page or admin console, should the user be eligible to be synchronized to this provider?
|
||||
|
||||
Allow Kerberos authentication::
|
||||
Enable Kerberos/SPNEGO authentication in realm with users data provisioned from LDAP.
|
||||
|
|
@ -57,21 +57,21 @@ When you configure a secured connection URL to your LDAP store(for example `ldap
|
|||
The important thing is to properly configure a truststore on the {{book.project.name}} server side, because SSL won't work
|
||||
if {{book.project.name}} can't trust the SSL connection with LDAP ({{book.project.name}}.
|
||||
|
||||
The global truststore for the {{book.project.name}} can be configured with Truststore SPI. Please check out the link:{{book.installguide.link}}[book.installguide.name}}] for more detail.
|
||||
If you don't configure truststore SPI, the truststore will fallback to the default mechanism provided by Java (either the file provided by system property `javax.net.ssl.trustStore`
|
||||
or the cacerts file from JDK if the system property is not set).
|
||||
The global truststore for the {{book.project.name}} can be configured with the Truststore SPI. Please check out the link:{{book.installguide.link}}[{{book.installguide.name}}] for more detail.
|
||||
If you don't configure the truststore SPI, the truststore will fallback to the default mechanism provided by Java (either the file provided by system property `javax.net.ssl.trustStore`
|
||||
or the cacerts file from the JDK if the system property is not set).
|
||||
|
||||
There is configuration property `Use Truststore SPI` in the LDAP federation provider configuration, where you can choose whether the Truststore SPI is used.
|
||||
By default, the value is `ldaps only`, which is fine for most of deployments. The Truststore SPI will only be used
|
||||
There is a configuration property `Use Truststore SPI` in the LDAP federation provider configuration, where you can choose whether the Truststore SPI is used.
|
||||
By default, the value is `ldaps only`, which is fine for most deployments. The Truststore SPI will only be used
|
||||
if the connection to LDAP starts with `ldaps`.
|
||||
|
||||
==== Sync of LDAP users to {{book.project.name}}
|
||||
|
||||
LDAP Federation Provider will automatically take care of synchronization (import) of needed LDAP users into the {{book.project.name}} local database.
|
||||
As users log in, the LDAP Federation provider will import the LDAP user
|
||||
into then {{book.project.name}} database and then authenticate against the LDAP password. This is the only time users will be imported.
|
||||
into the {{book.project.name}} database and then authenticate against the LDAP password. This is the only time users will be imported.
|
||||
If you go to the `Users` left menu item in the Admin Console and click the `View all users` button, you will only see those LDAP users that
|
||||
have been authenticated at least once by {{book.project.name}}. It is implemented this way so that admins don't accidentally try and import a huge LDAP DB of users.
|
||||
have been authenticated at least once by {{book.project.name}}. It is implemented this way so that admins don't accidentally try to import a huge LDAP DB of users.
|
||||
|
||||
If you want to sync all LDAP users into the {{book.project.name}} database, you may configure and enable the `Sync Settings` of the LDAP provider you configured.
|
||||
There are 2 types of synchronization:
|
||||
|
|
@ -85,50 +85,50 @@ Periodic Changed users sync::
|
|||
When syncing occurs, only those users that were created or updated after the last sync will be updated and/or imported.
|
||||
|
||||
The best way to handle syncing is to click the `Synchronize all users` button when you first create the LDAP provider,
|
||||
then set up a periodic sync of changed users. The configuration page for your LDAP Provider has a bunch of options to support you here.
|
||||
then set up a periodic sync of changed users. The configuration page for your LDAP Provider has several options to support you.
|
||||
|
||||
[[_ldap_mappers]]
|
||||
==== LDAP/Federation mappers
|
||||
|
||||
LDAP mappers are `listeners`, which are triggered by LDAP Federation provider at various points and provide another extension point to LDAP integration.
|
||||
They are triggered when a user logs in via LDAP and needs to be imported, during {{book.project.name}} initiated registration, or when a user is queried from the Admin Console
|
||||
LDAP mappers are `listeners`, which are triggered by the LDAP Federation provider at various points, provide another extension point to LDAP integration.
|
||||
They are triggered when a user logs in via LDAP and needs to be imported, during {{book.project.name}} initiated registration, or when a user is queried from the Admin Console.
|
||||
When you create an LDAP Federation provider, {{book.project.name}} will automatically provide set of builtin `mappers` for this provider.
|
||||
You are free to change this set and create new mapper or update/delete existing ones.
|
||||
You are free to change this set and create a new mapper or update/delete existing ones.
|
||||
|
||||
User Attribute Mapper::
|
||||
This allows you to specify which LDAP attribute is mapped to which attribute of {{book.project.name}} User.
|
||||
So, for example, you can configure that LDAP attribute `mail` to the attribute `email` in {{book.project.name}} database.
|
||||
For this mapper implementation, there is always one-to-one mapping (one LDAP attribute is mapped to one {{book.project.name}} attribute)
|
||||
This allows you to specify which LDAP attribute is mapped to which attribute of {{book.project.name}} user.
|
||||
So, for example, you can configure that LDAP attribute `mail` to the attribute `email` in the {{book.project.name}} database.
|
||||
For this mapper implementation, there is always a one-to-one mapping (one LDAP attribute is mapped to one {{book.project.name}} attribute)
|
||||
|
||||
FullName Mapper::
|
||||
This allows to specify that the full name of user, which is saved in some LDAP attribute (usually `cn` ) will be mapped to `firstName` and `lastname` attributes in the {{book.project.name}} database.
|
||||
Having `cn` to contain full name of user is common case for some LDAP deployments.
|
||||
This allows you to specify that the full name of the user, which is saved in some LDAP attribute (usually `cn` ) will be mapped to `firstName` and `lastname` attributes in the {{book.project.name}} database.
|
||||
Having `cn` to contain full name of user is a common case for some LDAP deployments.
|
||||
|
||||
Role Mapper::
|
||||
This allows to configure role mappings from LDAP into {{book.project.name}} role mappings.
|
||||
One Role mapper can be used to map LDAP roles (usually groups from particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of specified client.
|
||||
It's not a problem to configure more Role mappers for same LDAP provider.
|
||||
This allows you to configure role mappings from LDAP into {{book.project.name}} role mappings.
|
||||
One Role mapper can be used to map LDAP roles (usually groups from a particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of a specified client.
|
||||
It's not a problem to configure more Role mappers for the same LDAP provider.
|
||||
So for example you can specify that role mappings from groups under
|
||||
`ou=main,dc=example,dc=org` will be mapped to realm role mappings and role mappings from groups under
|
||||
`ou=finance,dc=example,dc=org` will be mapped to client role mappings of client `finance` .
|
||||
|
||||
Hardcoded Role Mapper::
|
||||
This mapper will grant specified {{book.project.name}} role to each {{book.project.name}} user linked with LDAP.
|
||||
This mapper will grant a specified {{book.project.name}} role to each {{book.project.name}} user linked with LDAP.
|
||||
|
||||
Group Mapper::
|
||||
This allows to configure group mappings from LDAP into {{book.project.name}} group mappings.
|
||||
Group mapper can be used to map LDAP groups from particular branch of LDAP tree into groups in {{book.project.name}}.
|
||||
And it will also propagate user-group mappings from LDAP into user-group mappings in {{book.project.name}}.
|
||||
This allows you to configure group mappings from LDAP into {{book.project.name}} group mappings.
|
||||
Group mapper can be used to map LDAP groups from a particular branch of an LDAP tree into groups in {{book.project.name}}.
|
||||
It will also propagate user-group mappings from LDAP into user-group mappings in {{book.project.name}}.
|
||||
|
||||
MSAD User Account Mapper::
|
||||
This mapper is specific to Microsoft Active Directory (MSAD). It's able to tightly integrate the MSAD user account state
|
||||
into the {{book.project.name}} account state (account enabled, password is expired etc).
|
||||
It's using the `userAccountControl` and `pwdLastSet` LDAP attributes. (both are specific to MSAD and are not LDAP standard).
|
||||
For example if `pwdLastSet` is `0`, the {{book.project.name}} user is required to update their password
|
||||
and there will be UPDATE_PASSWORD required action added to the user. If `userAccountControl` is
|
||||
and there will be an UPDATE_PASSWORD required action added to the user. If `userAccountControl` is
|
||||
`514` (disabled account) the {{book.project.name}} user is disabled as well.
|
||||
|
||||
By default, there is set of User Attribute mappers that map basic {{book.project.name}} user attributes like username, first name, lastname and email to corresponding LDAP attributes.
|
||||
By default, there is set of User Attribute mappers that map basic {{book.project.name}} user attributes like username, first name, lastname, and email to corresponding LDAP attributes.
|
||||
You are free to extend these and provide additional attribute mappings.
|
||||
Admin console provides tooltips, which should help on how to configure corresponding mappers.
|
||||
Admin console provides tooltips, which should help with configuring the corresponding mappers.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
=== User Attributes
|
||||
|
||||
Beyond basic user metadata like name and email, you can store arbitrary user attributes. Choose a user to manage
|
||||
then click on their `Attributes` tab.
|
||||
then click on the `Attributes` tab.
|
||||
|
||||
.Users
|
||||
image:../../{{book.images}}/user-attributes.png[]
|
||||
|
|
|
|||
|
|
@ -25,5 +25,5 @@ If OTP is optional in your realm, the user will have to go to the User Account M
|
|||
OTP generator. If OTP is required, then the user will be asked to re-configure a new OTP generator when they log in.
|
||||
|
||||
Like passwords, you can alternatively send an email to the user that will ask them to reset their OTP generator. Choose
|
||||
`Configure OTP` in the `Reset Actions` list box and click the `Rest Actions Email`. The sent email
|
||||
`Configure OTP` in the `Reset Actions` list box and click the `Send Email` button. The sent email
|
||||
contains a link that will bring the user to the OTP setup screen.
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
|
||||
It is often useful for an admin to impersonate a user. For example, a user may be experiencing a bug in one of your applications and
|
||||
an admin may want to impersonate the user to see if they can duplicate the problem. Admins with the appropriate permission
|
||||
can impersonate a user. There is two locations an admin can initiate impersonation. The first is on the `Users` list tab.
|
||||
can impersonate a user. There are two locations an admin can initiate impersonation. The first is on the `Users` list tab.
|
||||
|
||||
.Users
|
||||
image:../../{{book.images}}/user-search.png[]
|
||||
|
|
@ -20,7 +20,7 @@ Near the bottom of the page you can see the `Impersonate` button. Click that to
|
|||
|
||||
When impersonating, if the admin and the user are in the same realm, then the admin will be logged out and automatically logged
|
||||
in as the user being impersonated. If the admin and user are not in the same realm, the admin will remain logged in, but additionally
|
||||
be logged in as the user in that user's realm. In both cases, the browser will be redirected to the impersonated user's User Accoutn Management
|
||||
be logged in as the user in that user's realm. In both cases, the browser will be redirected to the impersonated user's User Account Management
|
||||
page.
|
||||
|
||||
Any user with the realm's `impersonation` role can impersonate a user. Please see the <<fake/../../admin-console-permissions.adoc#_admin_permissions,Admin Console Access Control>> chapter
|
||||
|
|
|
|||
|
|
@ -1,37 +1,37 @@
|
|||
[[_recaptcha]]
|
||||
|
||||
==== Recaptcha Support
|
||||
==== reCAPTCHA Support
|
||||
|
||||
To safeguard registration against bots, {{book.project.name}} has integration with Google Recaptcha.
|
||||
To safeguard registration against bots, {{book.project.name}} has integration with Google reCAPTCHA.
|
||||
To enable this you need to first go to link:https://developers.google.com/recaptcha/[Google Recaptcha Website]
|
||||
and create an API key so that you can get your recaptcha site key and secret.
|
||||
and create an API key so that you can get your reCAPTCHA site key and secret.
|
||||
(FYI, localhost works by default so you don't have to specify a domain).
|
||||
|
||||
Next, there's a few steps you need to perform in the {{book.project.name}} Admin Console.
|
||||
Click the `Authentication` left menu itme and go to the `Flows` tab. Select the `Registration` flow from the drop down
|
||||
Next, there are a few steps you need to perform in the {{book.project.name}} Admin Console.
|
||||
Click the `Authentication` left menu item and go to the `Flows` tab. Select the `Registration` flow from the drop down
|
||||
list on this page.
|
||||
|
||||
.Registration Flow
|
||||
image:../../{{book.images}}/registration-flow.png[]
|
||||
|
||||
|
||||
Set the 'Recaptcha' requirement to `Required` by clicking the appropriate radio button. This will enable
|
||||
Recaptcha on the screen. Next, you have to enter in the Recaptcha site key and secret that you generated at the Google Recaptcha Website.
|
||||
Click on the 'Configure' button that is to the right of the Recaptcha flow entry and enter in the Recaptcha site key and secret on this config page.
|
||||
Set the 'reCAPTCHA' requirement to `Required` by clicking the appropriate radio button. This will enable
|
||||
reCAPTCHA on the screen. Next, you have to enter in the reCAPTCHA site key and secret that you generated at the Google reCAPTCHA Website.
|
||||
Click on the 'Configure' button that is to the right of the reCAPTCHA flow entry and enter in the reCAPTCHA site key and secret on this config page.
|
||||
|
||||
.Recaptcha Config Page
|
||||
image:../../{{book.images}}/recaptcha-config.png[]
|
||||
|
||||
|
||||
The final step you have to do is to change some default HTTP response headers that {{book.project.name}} sets. {{book.project.name}}
|
||||
will prevent website from including any login page within an iframe. This is to prevent clickjacking attacks. You need to
|
||||
will prevent a website from including any login page within an iframe. This is to prevent clickjacking attacks. You need to
|
||||
authorize Google to use the registration page within an iframe. Go to
|
||||
the `Realm Settings` left menu item and then go to the `Security Defenses` tab. Y
|
||||
ou'll need to add `https://www.google.com` to the values of both the `X-Frame-Options` and `Content-Security-Policy` headers.
|
||||
the `Realm Settings` left menu item and then go to the `Security Defenses` tab. You will need to add `https://www.google.com` to the
|
||||
values of both the `X-Frame-Options` and `Content-Security-Policy` headers.
|
||||
|
||||
.Authorizing Iframes
|
||||
image:../../{{book.images}}/security-headers.png[]
|
||||
|
||||
Once you do this, Recaptcha should show up on your registration page. You may want to edit _register.ftl_ in your login
|
||||
theme to muck around with the placement and styling of the recaptcha button. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
|
||||
Once you do this, reCAPTCHA should show up on your registration page. You may want to edit _register.ftl_ in your login
|
||||
theme to muck around with the placement and styling of the reCAPTCHA button. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
|
||||
for more information on extending and creating themes.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
|
||||
=== Required Actions
|
||||
|
||||
Required Actions are tasks that a user must finish before they are allowed to log in. A user must enter
|
||||
in their credentials before required actions are executed. Once a required action is completed, the user will not have
|
||||
Required Actions are tasks that a user must finish before they are allowed to log in. A user must provide their credentials before required actions are executed. Once a required action is completed, the user will not have
|
||||
to perform the action again.
|
||||
Here are an explanation of some of the built in required action types:
|
||||
|
||||
|
|
@ -16,7 +15,7 @@ Verify Email::
|
|||
Update Profile::
|
||||
This required action asks the user to update their profile information, i.e. their name, address, email, and/or phone number.
|
||||
|
||||
Admins can set add required actions for each individual user with the user's `Details` tab in the Admin Console.
|
||||
Admins can add required actions for each individual user within the user's `Details` tab in the Admin Console.
|
||||
|
||||
.Setting Required Action
|
||||
image:../../{{book.images}}/user-required-action.png[]
|
||||
|
|
@ -33,7 +32,7 @@ the default required actions go to the `Authentication` left menu item and click
|
|||
.Default Required Actions
|
||||
image:../../{{book.images}}/default-required-actions.png[]
|
||||
|
||||
Simple click the checkbox in the `Default Action` column of the required actions that you want to be executed when a brand new user logs in.
|
||||
Simply click the checkbox in the `Default Action` column of the required actions that you want to be executed when a brand new user logs in.
|
||||
|
||||
==== Terms and Conditions
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +1,19 @@
|
|||
|
||||
=== Searching For Users
|
||||
|
||||
If you need to manage a specific user, click on `Users` in the left menu bar. T
|
||||
If you need to manage a specific user, click on `Users` in the left menu bar.
|
||||
|
||||
.Users
|
||||
image:../../{{book.images}}/users.png[]
|
||||
|
||||
This menu option brings you to the user list page. In the search box you can type in a full name, last name, or email address
|
||||
you want to search for in the user database. The query will bring up all users that match your criteria. The `View all users` button
|
||||
will list every user in the system. This can be a dangerous operation if you have tens of thousands of users stored. Some backends
|
||||
like LDAP don't have a way to page through users and must return the whole user set! So be careful before you execute a view all search.
|
||||
will list every user in the system. This will search just local {{book.project.name}} database and not the federated database (ie. LDAP)
|
||||
because some backends like LDAP don't have a way to page through users. So if you want the users from federated backend to be synced into {{book.project.name}}
|
||||
database you need to either:
|
||||
|
||||
* Adjust search criteria. That will sync just the backend users matching the criteria into {{book.project.name}} database.
|
||||
* Go to `User Federation` tab and click `Sync all users` or `Sync changed users` in the page with your federation provider.
|
||||
|
||||
See <<fake/../../user-federation.adoc#_user-storage-federation,User Federation>> for more details.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue