Fix headers in oidc chapter
This commit is contained in:
Stian Thorgersen
parent
060ccb64ad
commit
fba771b1e3
25 changed files with 92 additions and 92 deletions
|
|
@ -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
|
||||
details from the token (such as user profile information) or you want to invoke a RESTful service that is protected by {{book.project.name}}.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_adapter_error_handling]]
|
||||
=== Error Handling
|
||||
==== Error Handling
|
||||
|
||||
{{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()`.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[_applicationclustering]]
|
||||
=== Application Clustering
|
||||
==== Application Clustering
|
||||
|
||||
{% if book.community %}
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
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.
|
||||
|
||||
[[_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.
|
||||
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.
|
||||
|
||||
[[_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
|
||||
request. This may have a performance impact as your application will send more requests to the {{book.project.name}} server.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_fuse_adapter]]
|
||||
=== JBoss Fuse Adapter
|
||||
==== JBoss Fuse Adapter
|
||||
|
||||
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 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
|
||||
according to application type. The details are described in individual sub-chapters.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_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
|
||||
proper security constraints injected. You can add file `OSGI-INF/blueprint/blueprint.xml` into your camel application with the configuration similar to below.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_fuse_adapter_classic_war]]
|
||||
==== Secure Classic WAR application
|
||||
===== Secure Classic WAR application
|
||||
|
||||
The needed steps to secure your WAR are:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_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
|
||||
http://localhost:8181/cxf context. Securing such endpoints is quite tricky. The approach, which {{book.project.name}} is currently using,
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
|
||||
[[_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
|
||||
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`
|
||||
|
||||
|
||||
===== 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
|
||||
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.
|
||||
|
||||
|
||||
===== 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}}.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_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
|
||||
https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard[Pax Web Whiteboard Extender] for deploy such servlet as web application.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[_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.
|
||||
However, some applications and systems may still rely on pure legacy JAAS solution.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
|
||||
[[_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.
|
||||
This is what one might look like:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
|
||||
[[_jboss_adapter]]
|
||||
{% if book.community %}
|
||||
=== JBoss EAP/Wildfly Adapter
|
||||
==== JBoss EAP/Wildfly Adapter
|
||||
{% endif %}
|
||||
{% if book.product %}
|
||||
=== JBoss EAP Adapter
|
||||
==== JBoss EAP Adapter
|
||||
{% 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
|
||||
|
|
@ -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.
|
||||
|
||||
[[_jboss_adapter_installation]]
|
||||
==== Adapter Installation
|
||||
===== Adapter Installation
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -231,7 +231,7 @@ Here's an example:
|
|||
</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.
|
||||
While you don't have to specify KEYCLOAK as an `auth-method`, you still have to define the `security-constraints` in `web.xml`.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
|
||||
[[_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.
|
||||
You then have to provide some extra configuration in each WAR you deploy to Jetty.
|
||||
Let's go over these steps.
|
||||
|
||||
[[_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.
|
||||
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
|
||||
----
|
||||
|
||||
==== Required Per WAR Configuration
|
||||
===== Required Per WAR Configuration
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
|
||||
[[_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.
|
||||
You then have to provide some extra configuration in each WAR you deploy to Jetty.
|
||||
Let's go over these steps.
|
||||
|
||||
[[_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.
|
||||
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]]
|
||||
==== 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
=== Logout
|
||||
==== Logout
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
one the same {{book.project.name}} instance or on different instances.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[_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.
|
||||
This adapter works a bit differently than the other adapters. You do not define security constraints in web.xml.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
[[_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.
|
||||
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]]
|
||||
==== 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.
|
||||
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]]
|
||||
==== Required Spring Boot Adapter Configuration
|
||||
===== Required Spring Boot Adapter Configuration
|
||||
|
||||
This section describes how to configure your Spring Boot app to use Keycloak.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[_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.
|
||||
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.
|
||||
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.
|
||||
|
||||
|
|
@ -23,11 +23,11 @@ Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle
|
|||
</dependency>
|
||||
----
|
||||
|
||||
==== Spring Security Configuration
|
||||
===== Spring Security Configuration
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
|
|
@ -148,13 +148,13 @@ While Spring Security's XML namespace simplifies configuration, customizing the
|
|||
</beans>
|
||||
----
|
||||
|
||||
==== Multi Tenancy
|
||||
===== 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.
|
||||
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_`.
|
||||
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.
|
||||
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 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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
|
||||
[[_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.
|
||||
You then have to provide some extra configuration in each WAR you deploy to Tomcat.
|
||||
Let's go over these steps.
|
||||
|
||||
[[_tomcat_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.
|
||||
|
|
@ -28,7 +28,7 @@ $ unzip keycloak-tomcat7-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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[_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
|
||||
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.
|
||||
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.
|
||||
|
||||
[[_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.
|
||||
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' })
|
||||
----
|
||||
|
||||
== Older browsers
|
||||
==== Older browsers
|
||||
|
||||
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.
|
||||
|
|
@ -170,9 +170,9 @@ Example polyfill libraries:
|
|||
* https://github.com/davidchambers/Base64.js
|
||||
* https://github.com/devote/HTML5-History-API
|
||||
|
||||
== JavaScript Adapter reference
|
||||
==== JavaScript Adapter reference
|
||||
|
||||
=== Constructor
|
||||
===== Constructor
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
@ -182,7 +182,7 @@ new Keycloak('http://localhost/keycloak.json');
|
|||
new Keycloak({ url: 'http://localhost/auth', realm: 'myrealm', clientId: 'myApp' });
|
||||
----
|
||||
|
||||
=== Properties
|
||||
===== Properties
|
||||
|
||||
authenticated::
|
||||
Is `true` if the user is authenticated, `false` otherwise.
|
||||
|
|
@ -227,9 +227,9 @@ flow::
|
|||
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.
|
||||
|
||||
=== Methods
|
||||
===== Methods
|
||||
|
||||
==== init(options)
|
||||
====== init(options)
|
||||
|
||||
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.
|
||||
|
||||
==== login(options)
|
||||
====== login(options)
|
||||
|
||||
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.
|
||||
* 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).
|
||||
|
||||
|
|
@ -268,7 +268,7 @@ Options is an Object, where:
|
|||
* 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).
|
||||
|
||||
==== logout(options)
|
||||
====== logout(options)
|
||||
|
||||
Redirects to logout.
|
||||
|
||||
|
|
@ -276,7 +276,7 @@ Options is an Object, where:
|
|||
|
||||
* redirectUri - Specifies the uri to redirect to after logout.
|
||||
|
||||
==== createLogoutUrl(options)
|
||||
====== createLogoutUrl(options)
|
||||
|
||||
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.
|
||||
|
||||
==== register(options)
|
||||
====== register(options)
|
||||
|
||||
Redirects to registration form. Shortcut for login with option action = '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'
|
||||
|
||||
Options are same as createLoginUrl method but 'action' is set to 'register'
|
||||
|
||||
==== accountManagement()
|
||||
====== accountManagement()
|
||||
|
||||
Redirects to the Account Management Console.
|
||||
|
||||
==== createAccountUrl()
|
||||
====== createAccountUrl()
|
||||
|
||||
Returns the URL to the Account Management Console.
|
||||
|
||||
==== hasRealmRole(role)
|
||||
====== hasRealmRole(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).
|
||||
|
||||
==== loadUserProfile()
|
||||
====== loadUserProfile()
|
||||
|
||||
Loads the users profile.
|
||||
|
||||
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).
|
||||
|
||||
==== 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 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.
|
||||
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.
|
||||
|
||||
=== Callback Events
|
||||
===== Callback Events
|
||||
|
||||
The adapter supports setting callback listeners for certain events.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[_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
|
||||
as a proxy, then you can use _mod_auth_openidc_ to secure your web application with OpenID Connect. Configuration of this module
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
==== Authorization Endpoint
|
||||
===== Authorization Endpoint
|
||||
....
|
||||
/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.
|
||||
|
||||
==== Token Endpoint
|
||||
===== Token Endpoint
|
||||
....
|
||||
/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.
|
||||
|
||||
==== Userinfo Endpoint
|
||||
===== Userinfo Endpoint
|
||||
....
|
||||
/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.
|
||||
|
||||
==== Logout Endpoint
|
||||
===== Logout Endpoint
|
||||
....
|
||||
/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
|
||||
required to authenticate the client.
|
||||
|
||||
==== Certificate Endpoint
|
||||
===== Certificate Endpoint
|
||||
....
|
||||
/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].
|
||||
|
||||
==== Introspection Endpoint
|
||||
===== Introspection Endpoint
|
||||
....
|
||||
/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].
|
||||
|
||||
==== Dynamic Client Registration Endpoint
|
||||
===== Dynamic Client Registration Endpoint
|
||||
....
|
||||
/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].
|
||||
|
||||
|
||||
=== 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
|
||||
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.
|
||||
|
||||
==== 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
|
||||
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.
|
||||
|
||||
[[_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
|
||||
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.
|
||||
|
||||
===== 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 confidential client `myclient`:
|
||||
|
|
@ -155,7 +155,7 @@ curl \
|
|||
"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
|
||||
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.
|
||||
|
||||
=== 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
|
||||
especially applies to client-side (public clients) applications. Failing to do so could result in:
|
||||
|
|
|
|||
Loading…
Reference in a new issue