diff --git a/topics/oidc/java/adapter-context.adoc b/topics/oidc/java/adapter-context.adoc index eaa2835338..92f7c8b834 100644 --- a/topics/oidc/java/adapter-context.adoc +++ b/topics/oidc/java/adapter-context.adoc @@ -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}}. diff --git a/topics/oidc/java/adapter_error_handling.adoc b/topics/oidc/java/adapter_error_handling.adoc index 04a7ca115d..594384b322 100644 --- a/topics/oidc/java/adapter_error_handling.adoc +++ b/topics/oidc/java/adapter_error_handling.adoc @@ -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()`. diff --git a/topics/oidc/java/application-clustering.adoc b/topics/oidc/java/application-clustering.adoc index 515d68e14f..4f43429c68 100644 --- a/topics/oidc/java/application-clustering.adoc +++ b/topics/oidc/java/application-clustering.adoc @@ -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. diff --git a/topics/oidc/java/fuse-adapter.adoc b/topics/oidc/java/fuse-adapter.adoc index f00dcefb33..b8e8ca6a4b 100755 --- a/topics/oidc/java/fuse-adapter.adoc +++ b/topics/oidc/java/fuse-adapter.adoc @@ -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. diff --git a/topics/oidc/java/fuse/camel.adoc b/topics/oidc/java/fuse/camel.adoc index 092f1deef0..c9de37ab4c 100644 --- a/topics/oidc/java/fuse/camel.adoc +++ b/topics/oidc/java/fuse/camel.adoc @@ -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. diff --git a/topics/oidc/java/fuse/classic-war.adoc b/topics/oidc/java/fuse/classic-war.adoc index 29f72a02d5..980c791425 100644 --- a/topics/oidc/java/fuse/classic-war.adoc +++ b/topics/oidc/java/fuse/classic-war.adoc @@ -1,6 +1,6 @@ [[_fuse_adapter_classic_war]] -==== Secure Classic WAR application +===== Secure Classic WAR application The needed steps to secure your WAR are: diff --git a/topics/oidc/java/fuse/cxf-builtin.adoc b/topics/oidc/java/fuse/cxf-builtin.adoc index 3ad7164805..99a7f1761e 100644 --- a/topics/oidc/java/fuse/cxf-builtin.adoc +++ b/topics/oidc/java/fuse/cxf-builtin.adoc @@ -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, diff --git a/topics/oidc/java/fuse/cxf-separate.adoc b/topics/oidc/java/fuse/cxf-separate.adoc index b2d84e97a0..925bec9c77 100644 --- a/topics/oidc/java/fuse/cxf-separate.adoc +++ b/topics/oidc/java/fuse/cxf-separate.adoc @@ -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. diff --git a/topics/oidc/java/fuse/fuse-admin.adoc b/topics/oidc/java/fuse/fuse-admin.adoc index 78b7c9983d..48410203c4 100644 --- a/topics/oidc/java/fuse/fuse-admin.adoc +++ b/topics/oidc/java/fuse/fuse-admin.adoc @@ -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}}. \ No newline at end of file diff --git a/topics/oidc/java/fuse/servlet-whiteboard.adoc b/topics/oidc/java/fuse/servlet-whiteboard.adoc index 8452f73105..cf7e122784 100644 --- a/topics/oidc/java/fuse/servlet-whiteboard.adoc +++ b/topics/oidc/java/fuse/servlet-whiteboard.adoc @@ -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. diff --git a/topics/oidc/java/jaas.adoc b/topics/oidc/java/jaas.adoc index d95e5ccfbb..19e21dd118 100644 --- a/topics/oidc/java/jaas.adoc +++ b/topics/oidc/java/jaas.adoc @@ -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. diff --git a/topics/oidc/java/java-adapter-config.adoc b/topics/oidc/java/java-adapter-config.adoc index 03000d5a58..d30347cf66 100644 --- a/topics/oidc/java/java-adapter-config.adoc +++ b/topics/oidc/java/java-adapter-config.adoc @@ -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: diff --git a/topics/oidc/java/java-adapters.adoc b/topics/oidc/java/java-adapters.adoc index 4aea42c559..091505c8a4 100644 --- a/topics/oidc/java/java-adapters.adoc +++ b/topics/oidc/java/java-adapters.adoc @@ -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. diff --git a/topics/oidc/java/jboss-adapter.adoc b/topics/oidc/java/jboss-adapter.adoc index 0d8e5577bd..a8284859fb 100644 --- a/topics/oidc/java/jboss-adapter.adoc +++ b/topics/oidc/java/jboss-adapter.adoc @@ -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: ---- -==== 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`. diff --git a/topics/oidc/java/jetty8-adapter.adoc b/topics/oidc/java/jetty8-adapter.adoc index 1c18438e2f..9aacb75473 100755 --- a/topics/oidc/java/jetty8-adapter.adoc +++ b/topics/oidc/java/jetty8-adapter.adoc @@ -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. diff --git a/topics/oidc/java/jetty9-adapter.adoc b/topics/oidc/java/jetty9-adapter.adoc index bcad9713c5..70946313a6 100755 --- a/topics/oidc/java/jetty9-adapter.adoc +++ b/topics/oidc/java/jetty9-adapter.adoc @@ -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. diff --git a/topics/oidc/java/logout.adoc b/topics/oidc/java/logout.adoc index b56c9b4c90..5ab7487c24 100755 --- a/topics/oidc/java/logout.adoc +++ b/topics/oidc/java/logout.adoc @@ -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 diff --git a/topics/oidc/java/multi-tenancy.adoc b/topics/oidc/java/multi-tenancy.adoc index 5992d2578f..120218e5b0 100755 --- a/topics/oidc/java/multi-tenancy.adoc +++ b/topics/oidc/java/multi-tenancy.adoc @@ -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. diff --git a/topics/oidc/java/servlet-filter-adapter.adoc b/topics/oidc/java/servlet-filter-adapter.adoc index d23023b867..2ddd90f00a 100644 --- a/topics/oidc/java/servlet-filter-adapter.adoc +++ b/topics/oidc/java/servlet-filter-adapter.adoc @@ -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. diff --git a/topics/oidc/java/spring-boot-adapter.adoc b/topics/oidc/java/spring-boot-adapter.adoc index 87f59a036d..508f52cee1 100755 --- a/topics/oidc/java/spring-boot-adapter.adoc +++ b/topics/oidc/java/spring-boot-adapter.adoc @@ -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. diff --git a/topics/oidc/java/spring-security-adapter.adoc b/topics/oidc/java/spring-security-adapter.adoc index d0a895caca..5c8c34db13 100755 --- a/topics/oidc/java/spring-security-adapter.adoc +++ b/topics/oidc/java/spring-security-adapter.adoc @@ -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 ---- -==== 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 ---- -==== 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 <>. -==== 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. diff --git a/topics/oidc/java/tomcat-adapter.adoc b/topics/oidc/java/tomcat-adapter.adoc index 096dcc3824..4d646ca7be 100755 --- a/topics/oidc/java/tomcat-adapter.adoc +++ b/topics/oidc/java/tomcat-adapter.adoc @@ -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. diff --git a/topics/oidc/javascript-adapter.adoc b/topics/oidc/javascript-adapter.adoc index 206d1cd138..cd8665d6aa 100755 --- a/topics/oidc/javascript-adapter.adoc +++ b/topics/oidc/javascript-adapter.adoc @@ -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. diff --git a/topics/oidc/mod-auth-openidc.adoc b/topics/oidc/mod-auth-openidc.adoc index 25e03be59a..f80d67b0e5 100644 --- a/topics/oidc/mod-auth-openidc.adoc +++ b/topics/oidc/mod-auth-openidc.adoc @@ -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 diff --git a/topics/oidc/oidc-generic.adoc b/topics/oidc/oidc-generic.adoc index b16fb3783f..b1fb818162 100644 --- a/topics/oidc/oidc-generic.adoc +++ b/topics/oidc/oidc-generic.adoc @@ -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 <