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

Fix headers in oidc chapter

Browse source
This commit is contained in:
Stian Thorgersen 2016-06-09 15:12:10 +02:00
parent 060ccb64ad
commit fba771b1e3
25 changed files with 92 additions and 92 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
topics/oidc/java/adapter-context.adoc
View file

@ -1,4 +1,4 @@
=== Security Context ==== Security Context
The `KeycloakSecurityContext` interface is available if you need to access to the tokens directly. This could be useful if you want to retrieve additional The `KeycloakSecurityContext` interface is available if you need to access to the tokens directly. This could be useful if you want to retrieve additional
details from the token (such as user profile information) or you want to invoke a RESTful service that is protected by {{book.project.name}}. details from the token (such as user profile information) or you want to invoke a RESTful service that is protected by {{book.project.name}}.

2
topics/oidc/java/adapter_error_handling.adoc
View file

@ -1,6 +1,6 @@
[[_adapter_error_handling]] [[_adapter_error_handling]]
=== Error Handling ==== Error Handling
{{book.project.name}} has some error handling facilities for servlet based client adapters. {{book.project.name}} has some error handling facilities for servlet based client adapters.
When an error is encountered in authentication, {{book.project.name}} will call `HttpServletResponse.sendError()`. When an error is encountered in authentication, {{book.project.name}} will call `HttpServletResponse.sendError()`.

12
topics/oidc/java/application-clustering.adoc
View file

@ -1,5 +1,5 @@
[[_applicationclustering]] [[_applicationclustering]]
=== Application Clustering ==== Application Clustering
{% if book.community %} {% if book.community %}
This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS. This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS.
@ -18,7 +18,7 @@ There are a few options available depending on whether your application is:
Dealing with clustering is not quite as simple as for a regular application. Mainly due to the fact that both the browser and the server-side application Dealing with clustering is not quite as simple as for a regular application. Mainly due to the fact that both the browser and the server-side application
sends requests to {{book.project.name}}, so it's not as simple as enabling sticky sessions on your load balancer. sends requests to {{book.project.name}}, so it's not as simple as enabling sticky sessions on your load balancer.
==== Stateless token store ===== Stateless token store
By default, the web application secured by {{book.project.name}} uses the HTTP session to store security context. This means that you either have to By default, the web application secured by {{book.project.name}} uses the HTTP session to store security context. This means that you either have to
enable sticky sessions or replicate the HTTP session. enable sticky sessions or replicate the HTTP session.
@ -40,7 +40,7 @@ Another small limitation is limited support for Single-Sign Out. It works withou
application itself as the adapter will delete the KEYCLOAK_ADAPTER_STATE cookie. However, back-channel logout initialized from a different application isn't application itself as the adapter will delete the KEYCLOAK_ADAPTER_STATE cookie. However, back-channel logout initialized from a different application isn't
propagated by {{book.project.name}} to applications using cookie store. Hence it's recommended to use a short value for the access token timeout (for example 1 minute). propagated by {{book.project.name}} to applications using cookie store. Hence it's recommended to use a short value for the access token timeout (for example 1 minute).
==== Relative URI optimization ===== Relative URI optimization
In deployment scenarios where {{book.project.name}} and the application is hosted on the same domain (through a reverse proxy or load balancer) it can be In deployment scenarios where {{book.project.name}} and the application is hosted on the same domain (through a reverse proxy or load balancer) it can be
convenient to use relative URI options in your client configuration. convenient to use relative URI options in your client configuration.
@ -50,7 +50,7 @@ With relative URIs the URI is resolved as relative to the URL of the URL used to
For example if the URL to your application is `https://acme.org/myapp` and the URL to {{book.project.name}} is `https://acme.org/auth`, then you can use For example if the URL to your application is `https://acme.org/myapp` and the URL to {{book.project.name}} is `https://acme.org/auth`, then you can use
the redirect-uri `/myapp` instead of `https://acme.org/myapp`. the redirect-uri `/myapp` instead of `https://acme.org/myapp`.
==== Admin URL configuration ===== Admin URL configuration
Admin URL for a particular client can be configured in the {{book.project.name}} Administration Console. Admin URL for a particular client can be configured in the {{book.project.name}} Administration Console.
It's used by the {{book.project.name}} server to send backend requests to the application for various tasks, like logout users or push revocation policies. It's used by the {{book.project.name}} server to send backend requests to the application for various tasks, like logout users or push revocation policies.
@ -66,7 +66,7 @@ For example the way backchannel logout works is:
If admin URL contains `${application.session.host}` it will be replaced with the URL to the node associated with the HTTP session. If admin URL contains `${application.session.host}` it will be replaced with the URL to the node associated with the HTTP session.
[[_registration_app_nodes]] [[_registration_app_nodes]]
==== Registration of application nodes ===== Registration of application nodes
The previous section describes how {{book.project.name}} can send logout request to node associated with a specific HTTP session. The previous section describes how {{book.project.name}} can send logout request to node associated with a specific HTTP session.
However, in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them. However, in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them.
@ -98,7 +98,7 @@ the adapter configuration). You can also manually add and remove cluster nodes i
on the automatic registration feature or if you want to remove stale application nodes in the event your not using the automatic unregistration feature. on the automatic registration feature or if you want to remove stale application nodes in the event your not using the automatic unregistration feature.
[[_refresh_token_each_req]] [[_refresh_token_each_req]]
==== Refresh token in each request ===== Refresh token in each request
By default the application adapter will only refresh the access token when it's expired. However, you can also configure the adapter to refresh the token on every By default the application adapter will only refresh the access token when it's expired. However, you can also configure the adapter to refresh the token on every
request. This may have a performance impact as your application will send more requests to the {{book.project.name}} server. request. This may have a performance impact as your application will send more requests to the {{book.project.name}} server.

4
topics/oidc/java/fuse-adapter.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter]] [[_fuse_adapter]]
=== JBoss Fuse Adapter ==== JBoss Fuse Adapter
NOTE: JBoss Fuse is a Technology Preview feature and is not fully supported NOTE: JBoss Fuse is a Technology Preview feature and is not fully supported
@ -17,7 +17,7 @@ What is supported for Fuse is:
* Security for http://cxf.apache.org/[Apache CXF] endpoints running on default engine provided by CXF servlet. * Security for http://cxf.apache.org/[Apache CXF] endpoints running on default engine provided by CXF servlet.
* Security for SSH and JMX admin access. * Security for SSH and JMX admin access.
==== How to secure your web applications inside Fuse ===== How to secure your web applications inside Fuse
Basically all mentioned web applications require to inject {{book.project.name}} Jetty authenticator into underlying Jetty server . The steps to achieve it are bit different Basically all mentioned web applications require to inject {{book.project.name}} Jetty authenticator into underlying Jetty server . The steps to achieve it are bit different
according to application type. The details are described in individual sub-chapters. according to application type. The details are described in individual sub-chapters.

2
topics/oidc/java/fuse/camel.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter_camel]] [[_fuse_adapter_camel]]
==== Apache Camel Application ===== Apache Camel Application
* You can secure your Apache camel endpoint using http://camel.apache.org/jetty.html[camel-jetty] component by adding securityHandler with `KeycloakJettyAuthenticator` and * You can secure your Apache camel endpoint using http://camel.apache.org/jetty.html[camel-jetty] component by adding securityHandler with `KeycloakJettyAuthenticator` and
proper security constraints injected. You can add file `OSGI-INF/blueprint/blueprint.xml` into your camel application with the configuration similar to below. proper security constraints injected. You can add file `OSGI-INF/blueprint/blueprint.xml` into your camel application with the configuration similar to below.

2
topics/oidc/java/fuse/classic-war.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter_classic_war]] [[_fuse_adapter_classic_war]]
==== Secure Classic WAR application ===== Secure Classic WAR application
The needed steps to secure your WAR are: The needed steps to secure your WAR are:

2
topics/oidc/java/fuse/cxf-builtin.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter_cxf_builtin]] [[_fuse_adapter_cxf_builtin]]
==== Secure Apache CXF Endpoint on default Jetty Engine ===== Secure Apache CXF Endpoint on default Jetty Engine
Some services automatically come with deployed servlets on startup. One of such services is CXF servlet running on Some services automatically come with deployed servlets on startup. One of such services is CXF servlet running on
http://localhost:8181/cxf context. Securing such endpoints is quite tricky. The approach, which {{book.project.name}} is currently using, http://localhost:8181/cxf context. Securing such endpoints is quite tricky. The approach, which {{book.project.name}} is currently using,

2
topics/oidc/java/fuse/cxf-separate.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter_cxf_separate]] [[_fuse_adapter_cxf_separate]]
==== Secure Apache CXF Endpoint on separate Jetty ===== Secure Apache CXF Endpoint on separate Jetty
It's recommended to run your CXF endpoints secured by {{book.project.name}} on separate Jetty engine. This is the setup described in this section. It's recommended to run your CXF endpoints secured by {{book.project.name}} on separate Jetty engine. This is the setup described in this section.

8
topics/oidc/java/fuse/fuse-admin.adoc
View file

@ -1,8 +1,8 @@
[[_fuse_adapter_admin]] [[_fuse_adapter_admin]]
==== Secure Fuse Admin Services ===== Secure Fuse Admin Services
===== SSH authentication to Fuse terminal ====== SSH authentication to Fuse terminal
{{book.project.name}} mainly addresses usecases for authentication of web applications, however if your other web services and applications are protected {{book.project.name}} mainly addresses usecases for authentication of web applications, however if your other web services and applications are protected
with {{book.project.name}}, it may be good to protect non-web admin services like SSH with {{book.project.name}} credentials too. It's possible to do it with {{book.project.name}}, it may be good to protect non-web admin services like SSH with {{book.project.name}} credentials too. It's possible to do it
@ -55,7 +55,7 @@ ssh -o PubkeyAuthentication=no -p 8101 admin@localhost
And login with password `password`. Note that your user needs to have realm role `admin` . The required roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` And login with password `password`. Note that your user needs to have realm role `admin` . The required roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg`
===== JMX authentication ====== JMX authentication
This may be needed in case if you really want to use jconsole or other external tool to perform remote connection to JMX through RMI. Otherwise it may This may be needed in case if you really want to use jconsole or other external tool to perform remote connection to JMX through RMI. Otherwise it may
be better to use just hawt.io/jolokia as jolokia agent is installed in hawt.io by default. be better to use just hawt.io/jolokia as jolokia agent is installed in hawt.io by default.
@ -83,6 +83,6 @@ may be still able to access MBeans remotely via HTTP (Hawtio). So make sure to p
really protect JMX mbeans. really protect JMX mbeans.
===== Secure Fuse admin console ====== Secure Fuse admin console
Fuse admin console is Hawt.io. See http://hawt.io/configuration/index.html[Hawt.io documentation] for more info about how to secure it with {{book.project.name}}. Fuse admin console is Hawt.io. See http://hawt.io/configuration/index.html[Hawt.io documentation] for more info about how to secure it with {{book.project.name}}.

2
topics/oidc/java/fuse/servlet-whiteboard.adoc
View file

@ -1,6 +1,6 @@
[[_fuse_adapter_servlet_whiteboard]] [[_fuse_adapter_servlet_whiteboard]]
==== Secure Servlet deployed as OSGI service ===== Secure Servlet deployed as OSGI service
This is useful for the case, when you have sevlet class inside your OSGI bundle project, which is not deployed as classic WAR. Fuse uses This is useful for the case, when you have sevlet class inside your OSGI bundle project, which is not deployed as classic WAR. Fuse uses
https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard[Pax Web Whiteboard Extender] for deploy such servlet as web application. https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard[Pax Web Whiteboard Extender] for deploy such servlet as web application.

2
topics/oidc/java/jaas.adoc
View file

@ -1,5 +1,5 @@
[[_jaas_adapter]] [[_jaas_adapter]]
=== JAAS plugin ==== JAAS plugin
It's generally not needed to use JAAS for most of the applications, especially if they are HTTP based, and you should most likely choose one of our other adapters. It's generally not needed to use JAAS for most of the applications, especially if they are HTTP based, and you should most likely choose one of our other adapters.
However, some applications and systems may still rely on pure legacy JAAS solution. However, some applications and systems may still rely on pure legacy JAAS solution.

2
topics/oidc/java/java-adapter-config.adoc
View file

@ -1,6 +1,6 @@
[[_java_adapter_config]] [[_java_adapter_config]]
=== Java Adapter Config ==== Java Adapter Config
Each Java adapter supported by {{book.project.name}} can be configured by a simple JSON file. Each Java adapter supported by {{book.project.name}} can be configured by a simple JSON file.
This is what one might look like: This is what one might look like:

2
topics/oidc/java/java-adapters.adoc
View file

@ -1,4 +1,4 @@
== Java Adapters === Java Adapters
{{book.project.name}} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform. {{book.project.name}} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.

10
topics/oidc/java/jboss-adapter.adoc
View file

@ -1,10 +1,10 @@
[[_jboss_adapter]] [[_jboss_adapter]]
{% if book.community %} {% if book.community %}
=== JBoss EAP/Wildfly Adapter ==== JBoss EAP/Wildfly Adapter
{% endif %} {% endif %}
{% if book.product %} {% if book.product %}
=== JBoss EAP Adapter ==== JBoss EAP Adapter
{% endif %} {% endif %}
To be able to secure WAR apps deployed on JBoss EAP {% if book.community %}, WildFly or JBoss AS{% endif %}, you must install and configure the To be able to secure WAR apps deployed on JBoss EAP {% if book.community %}, WildFly or JBoss AS{% endif %}, you must install and configure the
@ -16,7 +16,7 @@ Alternatively, you don't have to modify your WAR at all and you can secure it vi
Both methods are described in this section. Both methods are described in this section.
[[_jboss_adapter_installation]] [[_jboss_adapter_installation]]
==== Adapter Installation ===== Adapter Installation
Adapters are available as a separate archive and are also available as Maven artifacts. Adapters are available as a separate archive and are also available as Maven artifacts.
@ -169,7 +169,7 @@ public class CustomerService {
} }
---- ----
==== Required Per WAR Configuration ===== Required Per WAR Configuration
This section describes how to secure a WAR directly by adding config and editing files within your WAR package. This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
@ -231,7 +231,7 @@ Here's an example:
</web-app> </web-app>
---- ----
==== Securing WARs via Adapter Subsystem ===== Securing WARs via Adapter Subsystem
You do not have to modify your WAR to secure it with {{book.project.name}}. Instead you can externally secure it via the {{book.project.name}} Adapter Subsystem. You do not have to modify your WAR to secure it with {{book.project.name}}. Instead you can externally secure it via the {{book.project.name}} Adapter Subsystem.
While you don't have to specify KEYCLOAK as an `auth-method`, you still have to define the `security-constraints` in `web.xml`. While you don't have to specify KEYCLOAK as an `auth-method`, you still have to define the `security-constraints` in `web.xml`.

6
topics/oidc/java/jetty8-adapter.adoc
View file

@ -1,13 +1,13 @@
[[_jetty8_adapter]] [[_jetty8_adapter]]
=== Jetty 8.1.x Adapter ==== Jetty 8.1.x Adapter
Keycloak has a separate adapter for Jetty 8.1.x that you will have to install into your Jetty installation. Keycloak has a separate adapter for Jetty 8.1.x that you will have to install into your Jetty installation.
You then have to provide some extra configuration in each WAR you deploy to Jetty. You then have to provide some extra configuration in each WAR you deploy to Jetty.
Let's go over these steps. Let's go over these steps.
[[_jetty8_adapter_installation]] [[_jetty8_adapter_installation]]
==== Adapter Installation ===== Adapter Installation
Adapters are no longer included with the appliance or war distribution.Each adapter is a separate download on the Keycloak download site. Adapters are no longer included with the appliance or war distribution.Each adapter is a separate download on the Keycloak download site.
They are also available as a maven artifact. They are also available as a maven artifact.
@ -40,7 +40,7 @@ Edit start.ini and add keycloak to the options
OPTIONS=Server,jsp,jmx,resources,websocket,ext,plus,annotations,keycloak OPTIONS=Server,jsp,jmx,resources,websocket,ext,plus,annotations,keycloak
---- ----
==== Required Per WAR Configuration ===== Required Per WAR Configuration
Enabling Keycloak for your WARs is the same as the Jetty 9.x adapter. Enabling Keycloak for your WARs is the same as the Jetty 9.x adapter.
Our 8.1.x adapter supports both keycloak.json and the jboss-web.xml advanced configuration. Our 8.1.x adapter supports both keycloak.json and the jboss-web.xml advanced configuration.

6
topics/oidc/java/jetty9-adapter.adoc
View file

@ -1,13 +1,13 @@
[[_jetty9_adapter]] [[_jetty9_adapter]]
=== Jetty 9.x Adapters ==== Jetty 9.x Adapters
Keycloak has a separate adapter for Jetty 9.1.x and Jetty 9.2.x that you will have to install into your Jetty installation. Keycloak has a separate adapter for Jetty 9.1.x and Jetty 9.2.x that you will have to install into your Jetty installation.
You then have to provide some extra configuration in each WAR you deploy to Jetty. You then have to provide some extra configuration in each WAR you deploy to Jetty.
Let's go over these steps. Let's go over these steps.
[[_jetty9_adapter_installation]] [[_jetty9_adapter_installation]]
==== Adapter Installation ===== Adapter Installation
Adapters are no longer included with the appliance or war distribution.Each adapter is a separate download on the Keycloak download site. Adapters are no longer included with the appliance or war distribution.Each adapter is a separate download on the Keycloak download site.
They are also available as a maven artifact. They are also available as a maven artifact.
@ -34,7 +34,7 @@ $ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
---- ----
[[_jetty9_per_war]] [[_jetty9_per_war]]
==== Required Per WAR Configuration ===== Required Per WAR Configuration
This section describes how to secure a WAR directly by adding config and editing files within your WAR package. This section describes how to secure a WAR directly by adding config and editing files within your WAR package.

2
topics/oidc/java/logout.adoc
View file

@ -1,4 +1,4 @@
=== Logout ==== Logout
There are multiple ways you can logout from a web application. There are multiple ways you can logout from a web application.
For Java EE servlet containers, you can call HttpServletRequest.logout(). For any other browser application, you can redirect the browser to For Java EE servlet containers, you can call HttpServletRequest.logout(). For any other browser application, you can redirect the browser to

2
topics/oidc/java/multi-tenancy.adoc
View file

@ -1,5 +1,5 @@
=== Multi Tenancy ==== Multi Tenancy
Multi Tenancy, in our context, means that a single target application (WAR) can be secured with multiple {{book.project.name}} realms. The realms can be located Multi Tenancy, in our context, means that a single target application (WAR) can be secured with multiple {{book.project.name}} realms. The realms can be located
one the same {{book.project.name}} instance or on different instances. one the same {{book.project.name}} instance or on different instances.

2
topics/oidc/java/servlet-filter-adapter.adoc
View file

@ -1,5 +1,5 @@
[[_servlet_filter_adapter]] [[_servlet_filter_adapter]]
=== Java Servlet Filter Adapter ==== Java Servlet Filter Adapter
If you are deploying your Java Servlet application on a platform where there is no {{book.project.name}} adapter you opt to use the servlet filter adapter. If you are deploying your Java Servlet application on a platform where there is no {{book.project.name}} adapter you opt to use the servlet filter adapter.
This adapter works a bit differently than the other adapters. You do not define security constraints in web.xml. This adapter works a bit differently than the other adapters. You do not define security constraints in web.xml.

6
topics/oidc/java/spring-boot-adapter.adoc
View file

@ -1,11 +1,11 @@
[[_spring_boot_adapter]] [[_spring_boot_adapter]]
=== Spring Boot Adapter ==== Spring Boot Adapter
To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app. To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app.
You then have to provide some extra configuration via normal Spring Boot configuration (`application.properties`). Let's go over these steps. You then have to provide some extra configuration via normal Spring Boot configuration (`application.properties`). Let's go over these steps.
[[_spring_boot_adapter_installation]] [[_spring_boot_adapter_installation]]
==== Adapter Installation ===== Adapter Installation
The Keycloak Spring Boot adapter takes advantage of Spring Boot's autoconfiguration so all you need to do is add the Keycloak Spring Boot adapter JAR to your project. The Keycloak Spring Boot adapter takes advantage of Spring Boot's autoconfiguration so all you need to do is add the Keycloak Spring Boot adapter JAR to your project.
Depending on what container you are using with Spring Boot, you also need to add the appropriate Keycloak container adapter. Depending on what container you are using with Spring Boot, you also need to add the appropriate Keycloak container adapter.
@ -29,7 +29,7 @@ If you are using Maven, add the following to your pom.xml (using Tomcat as an ex
---- ----
[[_spring_boot_adapter_configuration]] [[_spring_boot_adapter_configuration]]
==== Required Spring Boot Adapter Configuration ===== Required Spring Boot Adapter Configuration
This section describes how to configure your Spring Boot app to use Keycloak. This section describes how to configure your Spring Boot app to use Keycloak.

18
topics/oidc/java/spring-security-adapter.adoc
View file

@ -1,5 +1,5 @@
[[_spring_security_adapter]] [[_spring_security_adapter]]
=== Spring Security Adapter ==== Spring Security Adapter
To secure an application with Spring Security and Keycloak, add this adapter as a dependency to your project. To secure an application with Spring Security and Keycloak, add this adapter as a dependency to your project.
You then have to provide some extra beans in your Spring Security configuration file and add the Keycloak security filter to your pipeline. You then have to provide some extra beans in your Spring Security configuration file and add the Keycloak security filter to your pipeline.
@ -7,7 +7,7 @@ You then have to provide some extra beans in your Spring Security configuration
Unlike the other Keycloak Adapters, you should not configure your security in web.xml. Unlike the other Keycloak Adapters, you should not configure your security in web.xml.
However, keycloak.json is still required. However, keycloak.json is still required.
==== Adapter Installation ===== Adapter Installation
Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle build. Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle build.
@ -23,11 +23,11 @@ Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle
</dependency> </dependency>
---- ----
==== Spring Security Configuration ===== Spring Security Configuration
The Keycloak Spring Security adapter takes advantage of Spring Security's flexible security configuration syntax. The Keycloak Spring Security adapter takes advantage of Spring Security's flexible security configuration syntax.
===== Java Configuration ====== Java Configuration
Keycloak provides a KeycloakWebSecurityConfigurerAdapter as a convenient base class for creating a http://docs.spring.io/spring-security/site/docs/4.0.x/apidocs/org/springframework/security/config/annotation/web/WebSecurityConfigurer.html[WebSecurityConfigurer] instance. Keycloak provides a KeycloakWebSecurityConfigurerAdapter as a convenient base class for creating a http://docs.spring.io/spring-security/site/docs/4.0.x/apidocs/org/springframework/security/config/annotation/web/WebSecurityConfigurer.html[WebSecurityConfigurer] instance.
The implementation allows customization by overriding methods. The implementation allows customization by overriding methods.
@ -78,7 +78,7 @@ You must provide a session authentication strategy bean which should be of type
Spring Security's `SessionFixationProtectionStrategy` is currently not supported because it changes the session identifier after login via Keycloak. Spring Security's `SessionFixationProtectionStrategy` is currently not supported because it changes the session identifier after login via Keycloak.
If the session identifier changes, universal log out will not work because Keycloak is unaware of the new session identifier. If the session identifier changes, universal log out will not work because Keycloak is unaware of the new session identifier.
===== XML Configuration ====== XML Configuration
While Spring Security's XML namespace simplifies configuration, customizing the configuration can be a bit verbose. While Spring Security's XML namespace simplifies configuration, customizing the configuration can be a bit verbose.
@ -148,13 +148,13 @@ While Spring Security's XML namespace simplifies configuration, customizing the
</beans> </beans>
---- ----
==== Multi Tenancy ===== Multi Tenancy
The Keycloak Spring Security adapter also supports multi tenancy. The Keycloak Spring Security adapter also supports multi tenancy.
Instead of injecting `AdapterDeploymentContextFactoryBean` with the path to `keycloak.json` you can inject an implementation of the `KeycloakConfigResolver` interface. Instead of injecting `AdapterDeploymentContextFactoryBean` with the path to `keycloak.json` you can inject an implementation of the `KeycloakConfigResolver` interface.
More details on how to implement the `KeycloakConfigResolver` can be found in <<fake/../multi-tenancy.adoc#_multi_tenancy,Multi Tenancy>>. More details on how to implement the `KeycloakConfigResolver` can be found in <<fake/../multi-tenancy.adoc#_multi_tenancy,Multi Tenancy>>.
==== Naming Security Roles ===== Naming Security Roles
Spring Security, when using role-based authentication, requires that role names start with `ROLE_`. Spring Security, when using role-based authentication, requires that role names start with `ROLE_`.
For example, an administrator role must be declared in Keycloak as `ROLE_ADMIN` or similar, not simply `ADMIN`. For example, an administrator role must be declared in Keycloak as `ROLE_ADMIN` or similar, not simply `ADMIN`.
@ -163,7 +163,7 @@ The class `org.keycloak.adapters.springsecurity.authentication.KeycloakAuthentic
Use, for example, `org.springframework.security.core.authority.mapping.SimpleAuthorityMapper` to insert the `ROLE_` prefix and convert the role name to upper case. Use, for example, `org.springframework.security.core.authority.mapping.SimpleAuthorityMapper` to insert the `ROLE_` prefix and convert the role name to upper case.
The class is part of Spring Security Core module. The class is part of Spring Security Core module.
==== Client to Client Support ===== Client to Client Support
To simplify communication between clients, Keycloak provides an extension of Spring's `RestTemplate` that handles bearer token authentication for you. To simplify communication between clients, Keycloak provides an extension of Spring's `RestTemplate` that handles bearer token authentication for you.
To enable this feature your security configuration must add the `KeycloakRestTemplate` bean. To enable this feature your security configuration must add the `KeycloakRestTemplate` bean.
@ -227,7 +227,7 @@ public class RemoteProductService implements ProductService {
} }
---- ----
==== Spring Boot Configuration ===== Spring Boot Configuration
Spring Boot attempts to eagerly register filter beans with the web application context. Spring Boot attempts to eagerly register filter beans with the web application context.
Therefore, when running the Keycloak Spring Security adapter in a Spring Boot environment, it may be necessary to add two ``FilterRegistrationBean``s to your security configuration to prevent the Keycloak filters from being registered twice. Therefore, when running the Keycloak Spring Security adapter in a Spring Boot environment, it may be necessary to add two ``FilterRegistrationBean``s to your security configuration to prevent the Keycloak filters from being registered twice.

6
topics/oidc/java/tomcat-adapter.adoc
View file

@ -1,13 +1,13 @@
[[_tomcat_adapter]] [[_tomcat_adapter]]
=== Tomcat 6, 7 and 8 Adapters ==== Tomcat 6, 7 and 8 Adapters
To be able to secure WAR apps deployed on Tomcat 6, 7 and 8 you must install the Keycloak Tomcat 6, 7 or 8 adapter into your Tomcat installation. To be able to secure WAR apps deployed on Tomcat 6, 7 and 8 you must install the Keycloak Tomcat 6, 7 or 8 adapter into your Tomcat installation.
You then have to provide some extra configuration in each WAR you deploy to Tomcat. You then have to provide some extra configuration in each WAR you deploy to Tomcat.
Let's go over these steps. Let's go over these steps.
[[_tomcat_adapter_installation]] [[_tomcat_adapter_installation]]
==== Adapter Installation ===== Adapter Installation
Adapters are no longer included with the appliance or war distribution. Adapters are no longer included with the appliance or war distribution.
Each adapter is a separate download on the Keycloak download site. Each adapter is a separate download on the Keycloak download site.
@ -28,7 +28,7 @@ $ unzip keycloak-tomcat7-adapter-dist.zip
$ unzip keycloak-tomcat8-adapter-dist.zip $ unzip keycloak-tomcat8-adapter-dist.zip
---- ----
==== Required Per WAR Configuration ===== Required Per WAR Configuration
This section describes how to secure a WAR directly by adding config and editing files within your WAR package. This section describes how to secure a WAR directly by adding config and editing files within your WAR package.

48
topics/oidc/javascript-adapter.adoc
View file

@ -1,5 +1,5 @@
[[_javascript_adapter]] [[_javascript_adapter]]
== Javascript Adapter === Javascript Adapter
{{book.project.name}} comes with a client-side JavaScript library that can be used to secure HTML5/JavaScript applications. The JavaScript adapter has built-in {{book.project.name}} comes with a client-side JavaScript library that can be used to secure HTML5/JavaScript applications. The JavaScript adapter has built-in
support for Cordova applications. support for Cordova applications.
@ -109,7 +109,7 @@ keycloak.updateToken(30).success(function() {
); );
---- ----
== Session status iframe ==== Session status iframe
By default, the JavaScript adapter creates a hidden iframe that is used to detect if a Single-Sign Out has occurred. By default, the JavaScript adapter creates a hidden iframe that is used to detect if a Single-Sign Out has occurred.
This does not require any network traffic, instead the status is retrieved by looking at a special status cookie. This does not require any network traffic, instead the status is retrieved by looking at a special status cookie.
@ -119,7 +119,7 @@ You should not rely on looking at this cookie directly. It's format can change a
your application. your application.
[[_javascript_implicit_flow]] [[_javascript_implicit_flow]]
== Implicit and Hybrid Flow ==== Implicit and Hybrid Flow
By default, the JavaScript adapter uses the http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code] flow. By default, the JavaScript adapter uses the http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code] flow.
With this flow the {{book.project.name}} server returns a authorization code, not a authentication token, to the application. The JavaScript adapter exchanges With this flow the {{book.project.name}} server returns a authorization code, not a authentication token, to the application. The JavaScript adapter exchanges
@ -160,7 +160,7 @@ For the Hybrid flow, you need to pass the parameter `flow` with value `hybrid` t
keycloak.init({ flow: 'hybrid' }) keycloak.init({ flow: 'hybrid' })
---- ----
== Older browsers ==== Older browsers
The JavaScript adapter depends on Base64 (window.btoa and window.atob) and HTML5 History API. The JavaScript adapter depends on Base64 (window.btoa and window.atob) and HTML5 History API.
If you need to support browsers that don't have these available (for example IE9) you need to add polyfillers. If you need to support browsers that don't have these available (for example IE9) you need to add polyfillers.
@ -170,9 +170,9 @@ Example polyfill libraries:
* https://github.com/davidchambers/Base64.js * https://github.com/davidchambers/Base64.js
* https://github.com/devote/HTML5-History-API * https://github.com/devote/HTML5-History-API
== JavaScript Adapter reference ==== JavaScript Adapter reference
=== Constructor ===== Constructor
[source] [source]
---- ----
@ -182,7 +182,7 @@ new Keycloak('http://localhost/keycloak.json');
new Keycloak({ url: 'http://localhost/auth', realm: 'myrealm', clientId: 'myApp' }); new Keycloak({ url: 'http://localhost/auth', realm: 'myrealm', clientId: 'myApp' });
---- ----
=== Properties ===== Properties
authenticated:: authenticated::
Is `true` if the user is authenticated, `false` otherwise. Is `true` if the user is authenticated, `false` otherwise.
@ -227,9 +227,9 @@ flow::
responseType:: responseType::
Response type sent to {{book.project.name}} with login requests. This is determined based on the flow value used during initialization, but can be overridden by setting this value. Response type sent to {{book.project.name}} with login requests. This is determined based on the flow value used during initialization, but can be overridden by setting this value.
=== Methods ===== Methods
==== init(options) ====== init(options)
Called to initialize the adapter. Called to initialize the adapter.
@ -247,7 +247,7 @@ Options is an Object, where:
Returns promise to set functions to be invoked on success or error. Returns promise to set functions to be invoked on success or error.
==== login(options) ====== login(options)
Redirects to login form on (options is an optional object with redirectUri and/or prompt fields). Redirects to login form on (options is an optional object with redirectUri and/or prompt fields).
@ -259,7 +259,7 @@ Options is an Object, where:
* action - If value is 'register' then user is redirected to registration page, otherwise to login page. * action - If value is 'register' then user is redirected to registration page, otherwise to login page.
* locale - Specifies the desired locale for the UI. * locale - Specifies the desired locale for the UI.
==== createLoginUrl(options) ====== createLoginUrl(options)
Returns the URL to login form on (options is an optional object with redirectUri and/or prompt fields). Returns the URL to login form on (options is an optional object with redirectUri and/or prompt fields).
@ -268,7 +268,7 @@ Options is an Object, where:
* redirectUri - Specifies the uri to redirect to after login. * redirectUri - Specifies the uri to redirect to after login.
* prompt - Can be set to 'none' to check if the user is logged in already (if not logged in, a login form is not displayed). * prompt - Can be set to 'none' to check if the user is logged in already (if not logged in, a login form is not displayed).
==== logout(options) ====== logout(options)
Redirects to logout. Redirects to logout.
@ -276,7 +276,7 @@ Options is an Object, where:
* redirectUri - Specifies the uri to redirect to after logout. * redirectUri - Specifies the uri to redirect to after logout.
==== createLogoutUrl(options) ====== createLogoutUrl(options)
Returns the URL to logout the user. Returns the URL to logout the user.
@ -284,45 +284,45 @@ Options is an Object, where:
* redirectUri - Specifies the uri to redirect to after logout. * redirectUri - Specifies the uri to redirect to after logout.
==== register(options) ====== register(options)
Redirects to registration form. Shortcut for login with option action = 'register' Redirects to registration form. Shortcut for login with option action = 'register'
Options are same as login method but 'action' is set to 'register' Options are same as login method but 'action' is set to 'register'
==== createRegisterUrl(options) ====== createRegisterUrl(options)
Returns the url to registration page. Shortcut for createLoginUrl with option action = 'register' Returns the url to registration page. Shortcut for createLoginUrl with option action = 'register'
Options are same as createLoginUrl method but 'action' is set to 'register' Options are same as createLoginUrl method but 'action' is set to 'register'
==== accountManagement() ====== accountManagement()
Redirects to the Account Management Console. Redirects to the Account Management Console.
==== createAccountUrl() ====== createAccountUrl()
Returns the URL to the Account Management Console. Returns the URL to the Account Management Console.
==== hasRealmRole(role) ====== hasRealmRole(role)
Returns true if the token has the given realm role. Returns true if the token has the given realm role.
==== hasResourceRole(role, resource) ====== hasResourceRole(role, resource)
Returns true if the token has the given role for the resource (resource is optional, if not specified clientId is used). Returns true if the token has the given role for the resource (resource is optional, if not specified clientId is used).
==== loadUserProfile() ====== loadUserProfile()
Loads the users profile. Loads the users profile.
Returns promise to set functions to be invoked on success or error. Returns promise to set functions to be invoked on success or error.
==== isTokenExpired(minValidity) ====== isTokenExpired(minValidity)
Returns true if the token has less than minValidity seconds left before it expires (minValidity is optional, if not specified 0 is used). Returns true if the token has less than minValidity seconds left before it expires (minValidity is optional, if not specified 0 is used).
==== updateToken(minValidity) ====== updateToken(minValidity)
If the token expires within minValidity seconds (minValidity is optional, if not specified 0 is used) the token is refreshed. If the token expires within minValidity seconds (minValidity is optional, if not specified 0 is used) the token is refreshed.
If the session status iframe is enabled, the session status is also checked. If the session status iframe is enabled, the session status is also checked.
@ -343,14 +343,14 @@ keycloak.updateToken(5).success(function(refreshed) {
}); });
---- ----
==== clearToken() ====== clearToken()
Clear authentication state, including tokens. Clear authentication state, including tokens.
This can be useful if application has detected the session was expired, for example if updating token fails. This can be useful if application has detected the session was expired, for example if updating token fails.
Invoking this results in onAuthLogout callback listener being invoked. Invoking this results in onAuthLogout callback listener being invoked.
=== Callback Events ===== Callback Events
The adapter supports setting callback listeners for certain events. The adapter supports setting callback listeners for certain events.

2
topics/oidc/mod-auth-openidc.adoc
View file

@ -1,5 +1,5 @@
[[_mod_auth_openidc]] [[_mod_auth_openidc]]
=== mod_auth_openidc Apache HTTPD Module ==== mod_auth_openidc Apache HTTPD Module
The https://github.com/pingidentity/mod_auth_openidc[mod_auth_openidc] is an Apache HTTP plugin for OpenID Connect. If your language/environment supports using Apache HTTPD The https://github.com/pingidentity/mod_auth_openidc[mod_auth_openidc] is an Apache HTTP plugin for OpenID Connect. If your language/environment supports using Apache HTTPD
as a proxy, then you can use _mod_auth_openidc_ to secure your web application with OpenID Connect. Configuration of this module as a proxy, then you can use _mod_auth_openidc_ to secure your web application with OpenID Connect. Configuration of this module

32
topics/oidc/oidc-generic.adoc
View file

@ -1,11 +1,11 @@
== Other OpenID Connect libraries === Other OpenID Connect libraries
{{book.project.name}} can be secured by supplied adapters that usually are easier to use and provide better integration with {{book.project.name}}. However, {{book.project.name}} can be secured by supplied adapters that usually are easier to use and provide better integration with {{book.project.name}}. However,
if there is no adapter available for your programming language, framework or platform you may opt to use a generic OpenID Connect Resource Provider (RP) library if there is no adapter available for your programming language, framework or platform you may opt to use a generic OpenID Connect Resource Provider (RP) library
instead. This chapter describes details specific to {{book.project.name}} and doesn't go into low-level details of the protocols. For more details refer to the instead. This chapter describes details specific to {{book.project.name}} and doesn't go into low-level details of the protocols. For more details refer to the
http://openid.net/connect/[OpenID Connect specifications] and https://tools.ietf.org/html/rfc6749[OAuth2 specification]. http://openid.net/connect/[OpenID Connect specifications] and https://tools.ietf.org/html/rfc6749[OAuth2 specification].
=== Endpoints ==== Endpoints
The most important endpoint to know is the `well-known` configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID The most important endpoint to know is the `well-known` configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID
Connect implementation in {{book.project.name}}. The endpoint is: Connect implementation in {{book.project.name}}. The endpoint is:
@ -20,7 +20,7 @@ http://localhost:8080/auth/realms/master/.well-known/openid-configuration
Some RP libraries will retrieve all required endpoints from this endpoint, but for others you may need to list the endpoints individually. Some RP libraries will retrieve all required endpoints from this endpoint, but for others you may need to list the endpoints individually.
==== Authorization Endpoint ===== Authorization Endpoint
.... ....
/realms/master/protocol/openid-connect/auth /realms/master/protocol/openid-connect/auth
.... ....
@ -29,7 +29,7 @@ Performs authentication of the end-user. This is done by redirecting user agent
For more details see http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] section in OpenID Connect specification. For more details see http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] section in OpenID Connect specification.
==== Token Endpoint ===== Token Endpoint
.... ....
/realms/master/protocol/openid-connect/token /realms/master/protocol/openid-connect/token
.... ....
@ -39,7 +39,7 @@ The token endpoint is also used to obtain new access tokens when they expire.
For more details see http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] section in OpenID Connect specification. For more details see http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] section in OpenID Connect specification.
==== Userinfo Endpoint ===== Userinfo Endpoint
.... ....
/realms/master/protocol/openid-connect/userinfo /realms/master/protocol/openid-connect/userinfo
.... ....
@ -48,7 +48,7 @@ Returns standard claims about the authenticated user. Protected by a bearer toke
For more details see http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[Userinfo Endpoint] section in OpenID Connect specification. For more details see http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[Userinfo Endpoint] section in OpenID Connect specification.
==== Logout Endpoint ===== Logout Endpoint
.... ....
/realms/master/protocol/openid-connect/logout /realms/master/protocol/openid-connect/logout
.... ....
@ -60,7 +60,7 @@ User agent can be redirected to the endpoint in which case the active user sessi
The endpoint can also be invoked directly by the application. To invoke this endpoint directly the refresh token needs to be included as well as credentials The endpoint can also be invoked directly by the application. To invoke this endpoint directly the refresh token needs to be included as well as credentials
required to authenticate the client. required to authenticate the client.
==== Certificate Endpoint ===== Certificate Endpoint
.... ....
/realms/master/protocol/openid-connect/certs /realms/master/protocol/openid-connect/certs
.... ....
@ -70,7 +70,7 @@ the server.
For more details see https://tools.ietf.org/html/rfc7517[JSON Web Key specification]. For more details see https://tools.ietf.org/html/rfc7517[JSON Web Key specification].
==== Introspection Endpoint ===== Introspection Endpoint
.... ....
/realms/master/protocol/openid-connect/token/introspect /realms/master/protocol/openid-connect/token/introspect
.... ....
@ -79,7 +79,7 @@ Used to retrieve the active state of a token. Protected by a bearer token and ca
For more details see https://tools.ietf.org/html/rfc7662[OAuth 2.0 Token Introspection specification]. For more details see https://tools.ietf.org/html/rfc7662[OAuth 2.0 Token Introspection specification].
==== Dynamic Client Registration Endpoint ===== Dynamic Client Registration Endpoint
.... ....
/realms/master/clients-registrations/openid-connect /realms/master/clients-registrations/openid-connect
.... ....
@ -90,9 +90,9 @@ For more details see <<fake/../../client-registration.adoc#_client_registration,
https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration specification]. https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration specification].
=== Flows ==== Flows
==== Authorization Code ===== Authorization Code
The Authorization Code flow redirects the user agent to {{book.project.name}}. Once the user has successfully authenticated with {{book.project.name}} an The Authorization Code flow redirects the user agent to {{book.project.name}}. Once the user has successfully authenticated with {{book.project.name}} an
Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code to along with its Authorization Code is created and the user agent is redirected back to the application. The application then uses the authorization code to along with its
@ -103,7 +103,7 @@ a user agent.
For more details refer to the http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow] in the OpenID Connect specification. For more details refer to the http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow] in the OpenID Connect specification.
==== Implicit ===== Implicit
The Implicit flow redirects works similarly to the Authorization Code flow, but instead of returning a Authorization Code the Access Token and ID Token is The Implicit flow redirects works similarly to the Authorization Code flow, but instead of returning a Authorization Code the Access Token and ID Token is
returned. This reduces the need for the extra invocation to exchange the Authorization Code for an Access Token. However, it does not include a Refresh returned. This reduces the need for the extra invocation to exchange the Authorization Code for an Access Token. However, it does not include a Refresh
@ -119,7 +119,7 @@ browser history. This is somewhat mitigated by using short expiration for Access
For more details refer to the http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[Implicit Flow] in the OpenID Connect specification. For more details refer to the http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[Implicit Flow] in the OpenID Connect specification.
[[_resource_owner_password_credentials_flow]] [[_resource_owner_password_credentials_flow]]
==== Resource Owner Password Credentials ===== Resource Owner Password Credentials
Resource Owner Password Credentials, referred to as Direct Grant in {{book.project.name}}, allows exchanging user credentials for tokens. It's not recommended Resource Owner Password Credentials, referred to as Direct Grant in {{book.project.name}}, allows exchanging user credentials for tokens. It's not recommended
to use this flow unless you absolutely need to. Examples where this could be useful are legacy applications and command-line interfaces. to use this flow unless you absolutely need to. Examples where this could be useful are legacy applications and command-line interfaces.
@ -139,7 +139,7 @@ This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 spec
For more details refer to the https://tools.ietf.org/html/rfc6749#section-4.3[Resource Owner Password Credentials Grant] chapter in the OAuth 2.0 specification. For more details refer to the https://tools.ietf.org/html/rfc6749#section-4.3[Resource Owner Password Credentials Grant] chapter in the OAuth 2.0 specification.
===== Example using CURL ====== Example using CURL
The following example shows how to obtain an access token for a user in the realm `master` with username `user` and password `password`. The example is using The following example shows how to obtain an access token for a user in the realm `master` with username `user` and password `password`. The example is using
the confidential client `myclient`: the confidential client `myclient`:
@ -155,7 +155,7 @@ curl \
"http://localhost:8080/auth/realms/master/protocol/openid-connect/token" "http://localhost:8080/auth/realms/master/protocol/openid-connect/token"
---- ----
==== Client Credentials ===== Client Credentials
Client Credentials is used when clients (applications and services) wants to obtain access on behalf of themselves rather than on behalf of a user. This can Client Credentials is used when clients (applications and services) wants to obtain access on behalf of themselves rather than on behalf of a user. This can
for example be useful for background services that applies changes to the system in general rather than for a specific user. for example be useful for background services that applies changes to the system in general rather than for a specific user.
@ -166,7 +166,7 @@ This flow is not included in OpenID Connect, but is a part of the OAuth 2.0 spec
For more details refer to the https://tools.ietf.org/html/rfc6749#section-4.4[Client Credentials Grant] chapter in the OAuth 2.0 specification. For more details refer to the https://tools.ietf.org/html/rfc6749#section-4.4[Client Credentials Grant] chapter in the OAuth 2.0 specification.
=== Redirect URIs ==== Redirect URIs
When using the redirect based flows it's important to use valid redirect uris for your clients. The redirect uris should be as specific as possible. This When using the redirect based flows it's important to use valid redirect uris for your clients. The redirect uris should be as specific as possible. This
especially applies to client-side (public clients) applications. Failing to do so could result in: especially applies to client-side (public clients) applications. Failing to do so could result in: