diff --git a/README.adoc b/README.adoc index 08ecb3da6d..9701180643 100755 --- a/README.adoc +++ b/README.adoc @@ -1,10 +1,9 @@ -{{book.title}} -=========================================== += Securing Applications and Services Guide image:images/keycloak_logo.png[alt="Keycloak"] -*Keycloak* _Documentation_ for {{book.project.version}} +{{book.project.name}} {{book.project.version}} http://www.keycloak.org diff --git a/book-product.json b/book-product.json new file mode 100755 index 0000000000..bde16b05f8 --- /dev/null +++ b/book-product.json @@ -0,0 +1,25 @@ +{ + "gitbook": "2.x.x", + "structure": { + "readme": "README.adoc" + }, + "plugins": [ + "toggle-chapters", + "ungrey", + "splitter" + ], + "variables": { + "title": "Securing Applications and Services Guide", + "project": { + "name": "Red Hat Single Sign-On", + "version": "7.0.0" + }, + "community": false, + "product": true, + "images": "rhsso-images", + "adminguide": { + "name": "Server Administration Guide", + "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.0/server-administration-guide/" + } + } +} diff --git a/book.json b/book.json index 39fcf1969b..d3dcf33ef5 100755 --- a/book.json +++ b/book.json @@ -10,30 +10,16 @@ ], "variables": { "title": "Securing Applications and Services Guide", + "project": { + "name": "Keycloak", + "version": "1.9.7.Final" + }, "community": true, "product": false, "images": "keycloak-images", - "appserver": { - "name": "Wildfly", - "version": "10" - }, "adminguide": { - "name": "Keycloak Administration Guide", + "name": "Server Administration Guide", "link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/" - }, - "web": { - "docs": { - "name": "keycloak.org/docs", - "link": "http://keycloak.org/docs" - }, - "downloads": { - "name": "keycloak.org/downloads", - "link": "http://keycloak.org/downloads" - } - }, - "project": { - "name": "Keycloak", - "version": "1.9.5.Final" } } } diff --git a/build.sh b/build.sh index 4befdf8200..fc1e19f7fb 100755 --- a/build.sh +++ b/build.sh @@ -5,5 +5,3 @@ cd $(readlink -f `dirname $0`) python gitlab-conversion.py cd target asciidoctor master.adoc - -xdg-open master.html diff --git a/gitlab-conversion.py b/gitlab-conversion.py index 630665f150..9144f04d72 100755 --- a/gitlab-conversion.py +++ b/gitlab-conversion.py @@ -42,6 +42,9 @@ if os.path.isdir('keycloak-images'): if os.path.isdir('rhsso-images'): shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) +shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini')); +shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml')); + tmp = os.path.join(targetdir, 'topics') if not os.path.exists(tmp): os.makedirs(tmp) @@ -67,8 +70,8 @@ input = re.sub(r"[ ]*\.+\s*link:(.*)\[(.*)\]", "include::\g<1>[]", input) input = applyTransformation(input) output.write(input) -# parse book.json file and create document attributes -with open('book.json') as data_file: +# parse book-product.json file and create document attributes +with open('book-product.json') as data_file: data = json.load(data_file) variables = data['variables'] diff --git a/topics/oidc/java/adapter-context.adoc b/topics/oidc/java/adapter-context.adoc old mode 100755 new mode 100644 index 41319b0c76..92f7c8b834 --- a/topics/oidc/java/adapter-context.adoc +++ b/topics/oidc/java/adapter-context.adoc @@ -1,7 +1,7 @@ -=== 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.title}}. +details from the token (such as user profile information) or you want to invoke a RESTful service that is protected by {{book.project.name}}. In servlet environments it is available in secured invocations as an attribute in HttpServletRequest: [source,java] @@ -17,3 +17,4 @@ Or, it is available in secure and insecure requests in the HttpSession: httpServletRequest.getSession() .getAttribute(KeycloakSecurityContext.class.getName()); ---- + diff --git a/topics/oidc/java/adapter_error_handling.adoc b/topics/oidc/java/adapter_error_handling.adoc old mode 100755 new mode 100644 index 6e6beadfa9..594384b322 --- a/topics/oidc/java/adapter_error_handling.adoc +++ b/topics/oidc/java/adapter_error_handling.adoc @@ -1,11 +1,11 @@ [[_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.title}} will call `HttpServletResponse.sendError()`. +When an error is encountered in authentication, {{book.project.name}} will call `HttpServletResponse.sendError()`. You can set up an error-page within your `web.xml` file to handle the error however you want. -{{book.project.title}} may throw 400, 401, 403, and 500 errors. +{{book.project.name}} may throw 400, 401, 403, and 500 errors. [source,xml] ---- @@ -16,7 +16,7 @@ You can set up an error-page within your `web.xml` file to handle the error howe ---- {{book.project.name}} also sets a `HttpServletRequest` attribute that you can retrieve. -The attribute name is `org.keycloak.adapters.spi.AuthenticationError`, which should be casted to to `org.keycloak.adapters.OIDCAuthenticationError`. +The attribute name is `org.keycloak.adapters.spi.AuthenticationError`, which should be casted to `org.keycloak.adapters.OIDCAuthenticationError`. For example: @@ -31,4 +31,5 @@ OIDCAuthenticationError error = (OIDCAuthenticationError) httpServletRequest Reason reason = error.getReason(); System.out.println(reason.name()); ----- \ No newline at end of file +---- + diff --git a/topics/oidc/java/application-clustering.adoc b/topics/oidc/java/application-clustering.adoc index 50a8d591bb..798d7347e8 100644 --- a/topics/oidc/java/application-clustering.adoc +++ b/topics/oidc/java/application-clustering.adoc @@ -1,9 +1,14 @@ [[_applicationclustering]] -=== Application Clustering +==== Application Clustering -This chapter is related to supporting clustered applications deployed to JBoss EAP{% if book.community %}, WildFly and JBoss AS{% endif %}. +{% if book.community %} +This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS. +{% endif %} +{% if book.product %} +This chapter is related to supporting clustered applications deployed to JBoss EAP. +{% endif %} -There are several options depending on if your application is: +There are a few options available depending on whether your application is: * Stateless or stateful * Distributable (replicated http session) or non-distributable @@ -13,7 +18,7 @@ There are several options depending on if 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. @@ -35,19 +40,19 @@ 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. With relative URIs the URI is resolved as relative to the URL of the URL used to access {{book.project.name}}. -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`. +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 application 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. For example the way backchannel logout works is: @@ -55,18 +60,15 @@ For example the way backchannel logout works is: . User sends logout request from one application . The application sends logout request to {{book.project.name}} . The {{book.project.name}} server invalidates the user session -. The {{book.project.name}} server then sends a backchannel request to application with a admin url that are associated with the session +. The {{book.project.name}} server then sends a backchannel request to application with an admin url that are associated with the session . When an application receives the logout request it invalidates the corresponding HTTP session -Some examples of possible values of admin URL are: - -http://${application.session.host}:8080/myapp:: - {{book.project.name}} tracks hosts associated with the HTTP Session and will send session invalidation message to the associated node. +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 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. For example to push a new not before policy to the application or to logout all users from the application. @@ -96,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..53057c9282 100755 --- a/topics/oidc/java/fuse-adapter.adoc +++ b/topics/oidc/java/fuse-adapter.adoc @@ -1,12 +1,14 @@ [[_fuse_adapter]] -=== JBoss Fuse Adapter +==== JBoss Fuse Adapter NOTE: JBoss Fuse is a Technology Preview feature and is not fully supported Currently {{book.project.name}} supports securing your web applications running inside http://www.jboss.org/products/fuse/overview/[JBoss Fuse] . +{% if book.community %} It leverages <> as both JBoss Fuse 6.2 are bundled with http://eclipse.org/jetty/[Jetty 8.1 server] under the covers and Jetty is used for running various kinds of web applications. +{% endif %} What is supported for Fuse is: @@ -17,7 +19,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 b79229de6c..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. @@ -78,7 +78,8 @@ The roles, security constraint mappings and {{book.project.name}} adapter config * The `Import-Package` in `META-INF/MANIFEST.MF` needs to contain those imports: -[source] + +[source, subs="attributes"] ---- javax.servlet;version="[3,4)", javax.servlet.http;version="[3,4)", diff --git a/topics/oidc/java/fuse/classic-war.adoc b/topics/oidc/java/fuse/classic-war.adoc index 7ff0bfc98e..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: @@ -70,7 +70,7 @@ recommended to use `maven-bundle-plugin` in your project to properly generate OS Note that "*" resolution for package doesn't import `org.keycloak.adapters.jetty` package as it's not used by application or Blueprint or Spring descriptor, but it's used just in `jetty-web.xml` file. So list of the packages to import may look like this: -[source] +[source, subs="attributes"] ---- org.keycloak.adapters.jetty;version="{{book.project.version}}", org.keycloak.adapters;version="{{book.project.version}}", diff --git a/topics/oidc/java/fuse/cxf-builtin.adoc b/topics/oidc/java/fuse/cxf-builtin.adoc index ff4211a8c5..8fb2c01501 100644 --- a/topics/oidc/java/fuse/cxf-builtin.adoc +++ b/topics/oidc/java/fuse/cxf-builtin.adoc @@ -1,9 +1,9 @@ [[_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, +$$http://localhost:8181/cxf$$ context. Securing such endpoints is quite tricky. The approach, which {{book.project.name}} is currently using, is providing ServletReregistrationService, which undeploys builtin servlet at startup, so you are able to re-deploy it again on context secured by {{book.project.name}}. This is how configuration file `OSGI-INF/blueprint/blueprint.xml` inside your application may look like. Note it adds JAX-RS `customerservice` endpoint, which is endpoint specific to your application, but more importantly, it secures whole `/cxf` context. @@ -83,7 +83,8 @@ control over security for each application individually. * The `Import-Package` in `META-INF/MANIFEST.MF` needs to contain those imports: -[source] + +[source, subs="attributes"] ---- META-INF.cxf;version="[2.7,3.2)", META-INF.cxf.osgi;version="[2.7,3.2)";resolution:=optional, diff --git a/topics/oidc/java/fuse/cxf-separate.adoc b/topics/oidc/java/fuse/cxf-separate.adoc index 86e12b76a1..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. @@ -95,7 +95,8 @@ injected `KeycloakJettyAuthenticator` inside. The configuration may look like th * The `Import-Package` in `META-INF/MANIFEST.MF` needs to contain those imports: -[source] + +[source, subs="attributes"] ---- META-INF.cxf;version="[2.7,3.2)", META-INF.cxf.osgi;version="[2.7,3.2)";resolution:=optional, diff --git a/topics/oidc/java/fuse/fuse-admin.adoc b/topics/oidc/java/fuse/fuse-admin.adoc index 33223d587a..48410203c4 100644 --- a/topics/oidc/java/fuse/fuse-admin.adoc +++ b/topics/oidc/java/fuse/fuse-admin.adoc @@ -1,13 +1,13 @@ [[_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 by using JAAS login module, which allows to remotely connect to {{book.project.name}} and verify credentials based on -<> . +<>. Example steps for enable SSH authentication: @@ -40,10 +40,11 @@ This file contains configuration of the client application, which is used by JAA * Start Fuse and install `keycloak` JAAS realm into Fuse. This could be done easily by installing `keycloak-jaas` feature, which has JAAS realm predefined (you are able to override it by using your own `keycloak` JAAS realm with higher ranking). Use those commands in Fuse terminal: -``` +[source, subs="attributes"] +---- features:addurl mvn:org.keycloak/keycloak-osgi-features/{{book.project.version}}/xml/features features:install keycloak-jaas -``` +---- * Now let's type this from your terminal to login via SSH as `admin` user: @@ -51,10 +52,10 @@ features:install keycloak-jaas 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 be better to use just hawt.io/jolokia as jolokia agent is installed in hawt.io by default. @@ -82,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 37c0893803..cf7e122784 100644 --- a/topics/oidc/java/fuse/servlet-whiteboard.adoc +++ b/topics/oidc/java/fuse/servlet-whiteboard.adoc @@ -1,13 +1,13 @@ [[_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. The needed steps to secure your servlet with {{book.project.name}} are: -* Keycloak provides PaxWebIntegrationService, which allows to inject jetty-web.xml and configure security constraints for your application. +* {{book.project.name}} provides PaxWebIntegrationService, which allows to inject jetty-web.xml and configure security constraints for your application. You need to declare such service in `OSGI-INF/blueprint/blueprint.xml` inside your application. Note that your servlet needs to depend on it. The example configuration can look like this: [source,xml] @@ -65,7 +65,8 @@ The needed steps to secure your servlet with {{book.project.name}} are: Note you don't need `web.xml` as the security-constrains are declared in blueprint configuration file. * The `Import-Package` in `META-INF/MANIFEST.MF` needs to contain at least those imports: -[source] + +[source, subs="attributes"] ---- org.keycloak.adapters.jetty;version="{{book.project.version}}", org.keycloak.adapters;version="{{book.project.version}}", diff --git a/topics/oidc/java/jaas.adoc b/topics/oidc/java/jaas.adoc old mode 100755 new mode 100644 index fec56b196f..19e21dd118 --- a/topics/oidc/java/jaas.adoc +++ b/topics/oidc/java/jaas.adoc @@ -1,21 +1,21 @@ [[_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. -{{book.project.title}} provides two login modules to help in these situations. +{{book.project.name}} provides two login modules to help in these situations. The provided login modules are: org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule:: - This login module allows to authenticate with username/password from {{book.project.title}}. + This login module allows to authenticate with username/password from {{book.project.name}}. It's using <> flow to validate if the provided - username/password is valid. It's useful for non-web based systems, which need to rely on JAAS and want to use Keycloak, but can't use the standard browser + username/password is valid. It's useful for non-web based systems, which need to rely on JAAS and want to use {{book.project.name}}, but can't use the standard browser based flows due to their non-web nature. Example of such application could be messaging or SSH. org.keycloak.adapters.jaas.BearerTokenLoginModule:: - This login module allows to authenticate with {{book.project.title}} access token passed to it through CallbackHandler as password. - It may be useful for example in case, when you have {{book.project.title}} access token from standard based authentication flow and your web application then + This login module allows to authenticate with {{book.project.name}} access token passed to it through CallbackHandler as password. + It may be useful for example in case, when you have {{book.project.name}} access token from standard based authentication flow and your web application then needs to talk to external non-web based system, which rely on JAAS. For example a messaging system. Both modules use the following configuration properties: @@ -27,4 +27,5 @@ keycloak-config-file:: `role-principal-class`:: Configure alternative class for Role principals attached to JAAS Subject. - Default value is `org.keycloak.adapters.jaas.RolePrincipal`. Note: The class is required to have a constructor with a single `String` argument. \ No newline at end of file + Default value is `org.keycloak.adapters.jaas.RolePrincipal`. Note: The class is required to have a constructor with a single `String` argument. + diff --git a/topics/oidc/java/java-adapter-config.adoc b/topics/oidc/java/java-adapter-config.adoc index 03000d5a58..6e700e0ed6 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: @@ -52,10 +52,10 @@ resource:: realm-public-key:: PEM format of the realm public key. You can obtain this from the administration console. - This is OPTION._ + This is _OPTIONAL_. If not set the adapter will download this from {{book.project.name}}. auth-server-url:: - The base URL of the {{book.project.name}} server. All other {{book.project.name}} pages and REST service endpoints are derived from this. It is usually of the form `https://host:port/auth`. + The base URL of the {{book.project.name}} server. All other {{book.project.name}} pages and REST service endpoints are derived from this. It is usually of the form `$$https://host:port/auth$$`. This is _REQUIRED._ ssl-required:: @@ -143,8 +143,8 @@ truststore:: Client making HTTPS requests need a way to verify the host of the server they are talking to. This is what the trustore does. The keystore contains one or more trusted host certificates or certificate authorities. - You can create this truststore by extracting the public certificate of the {{book.project.name}} server's SSL keystore. - This is _OPTIONAL_ if `ssl-required` is `none` or `disable-trust-manager` is `true`. + You can create this truststore by extracting the public certificate of the {{book.project.name}} server's SSL keystore. + This is _REQUIRED_ unless `ssl-required` is `none` or `disable-trust-manager` is `true`. truststore-password:: Password for the truststore keystore. diff --git a/topics/oidc/java/java-adapters.adoc b/topics/oidc/java/java-adapters.adoc index 4aea42c559..697c559fad 100644 --- a/topics/oidc/java/java-adapters.adoc +++ b/topics/oidc/java/java-adapters.adoc @@ -1,6 +1,5 @@ -== 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. -All Java adapters share a set of common configuration options described in the <> chapter. There are also -a few more chapters that are relevant to all Java adapters. \ No newline at end of file +All Java adapters share a set of common configuration options described in the <> chapter. \ No newline at end of file diff --git a/topics/oidc/java/jboss-adapter.adoc b/topics/oidc/java/jboss-adapter.adoc old mode 100755 new mode 100644 index d7c83276d0..e9036004d0 --- a/topics/oidc/java/jboss-adapter.adoc +++ b/topics/oidc/java/jboss-adapter.adoc @@ -1,14 +1,20 @@ [[_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 +{% if book.community %} +To be able to secure WAR apps deployed on JBoss EAP, WildFly or JBoss AS, you must install and configure the {{book.project.name}} adapter subsystem. You then have two options to secure your WARs. +{% endif %} +{% if book.product %} +To be able to secure WAR apps deployed on JBoss EAP, you must install and configure the +{{book.project.name}} adapter subsystem. You then have two options to secure your WARs. +{% endif %} You can provide an adapter config file in your WAR and change the auth-method to KEYCLOAK within web.xml. @@ -16,14 +22,14 @@ 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. {% if book.community %} Install on Wildfly 9 or 10: -[source,bash] +[source, subs="attributes"] ---- $ cd $WILDFLY_HOME $ unzip keycloak-wildfly-adapter-dist-{{book.project.version}}.zip @@ -31,7 +37,7 @@ $ unzip keycloak-wildfly-adapter-dist-{{book.project.version}}.zip Install on Wildfly 8: -[source,bash] +[source, subs="attributes"] ---- $ cd $WILDFLY_HOME $ unzip keycloak-wf8-adapter-dist-{{book.project.version}}.zip @@ -39,7 +45,7 @@ $ unzip keycloak-wf8-adapter-dist-{{book.project.version}}.zip Install on JBoss EAP 7: -[source] +[source, subs="attributes"] ---- $ cd $EAP_HOME $ unzip keycloak-eap7-adapter-dist-{{book.project.version}}.zip @@ -47,7 +53,7 @@ $ unzip keycloak-eap7-adapter-dist-{{book.project.version}}.zip Install on JBoss EAP 6: -[source] +[source, subs="attributes"] ---- $ cd $EAP_HOME $ unzip keycloak-eap6-adapter-dist-{{book.project.version}}.zip @@ -55,7 +61,7 @@ $ unzip keycloak-eap6-adapter-dist-{{book.project.version}}.zip Install on JBoss AS 7.1: -[source] +[source, subs="attributes"] ---- $ cd $JBOSS_HOME $ unzip keycloak-as7-adapter-dist-{{book.project.version}}.zip @@ -65,18 +71,18 @@ $ unzip keycloak-as7-adapter-dist-{{book.project.version}}.zip {% if book.product %} Install on JBoss EAP 7: -[source] +[source, subs="attributes"] ---- $ cd $EAP_HOME -$ unzip RH-SSO-{{book.project.version}}-eap7-adapter.zip +$ unzip rh-sso-{{book.project.version}}-eap7-adapter.zip ---- Install on JBoss EAP 6: -[source] +[source, subs="attributes"] ---- $ cd $EAP_HOME -$ unzip RH-SSO-{{book.project.version}}-eap6-adapter.zip +$ unzip rh-sso-{{book.project.version}}-eap6-adapter.zip ---- {% endif %} @@ -94,12 +100,18 @@ $ ./bin/jboss-cli.sh -c --file=adapter-install.cli The script will add the required configuration to the server configuration file. -For JBoss EAP 7 {% if book.community %} and WildFly 9+{% endif %} there is also an offline CLI script that can be used to install the adapter while the server +{% if book.community %} +For JBoss EAP 7 and WildFly 9+ there is also an offline CLI script that can be used to install the adapter while the server is not running: +{% endif %} +{% if book.product %} +For JBoss EAP 7 there is also an offline CLI script that can be used to install the adapter while the server +is not running: +{% endif %} [source] ---- -$ ./bin/jboss-cli.sh -c --file=adapter-install-offline.cli +$ ./bin/jboss-cli.sh --file=adapter-install-offline.cli ---- If you are planning to add it manually you need to add the extension and subsystem definition to the server configuration: @@ -169,7 +181,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,12 +243,12 @@ Here's an example: ---- -==== Securing WARs via Keycloak Subsystem +===== Securing WARs via Adapter Subsystem -You do not have to modify your WAR to secure it with {{book.project.title}}. Instead you can externally secure it via the {{book.project.title}} 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`. You do not, however, have to create a `WEB-INF/keycloak.json` file. -This metadata is instead defined within server configuration (i.e. `standalone.xml`) in the {{book.project.title}} subsystem definition. +This metadata is instead defined within server configuration (i.e. `standalone.xml`) in the {{book.project.name}} subsystem definition. [source,xml] ---- @@ -259,17 +271,14 @@ This metadata is instead defined within server configuration (i.e. `standalone.x ---- The `secure-deployment` `name` attribute identifies the WAR you want to secure. -Its value is the `module-name` defined in `web.xml` with `.war` appended. - -The rest of the configuration corresponds pretty much one to one with the `keycloak.json` configuration options defined in <>. +Its value is the `module-name` defined in `web.xml` with `.war` appended. The rest of the configuration corresponds pretty much one to one with the `keycloak.json` configuration options defined in <>. The exception is the `credential` element. -To make it easier for you, you can go to the {{book.project.title}} Administration Console and go to the Application/Installation tab of the application this WAR is aligned with. +To make it easier for you, you can go to the {{book.project.name}} Administration Console and go to the Client/Installation tab of the application this WAR is aligned with. It provides an example XML file you can cut and paste. -There is an additional convenience format for this XML if you have multiple WARs you are deployment that are secured by the same domain. -This format allows you to define common configuration items in one place under the `realm` element. +If you have multiple deployments secured by the same realm you can share the realm configuration in a separate element. For example: [source,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..ee285201ab 100755 --- a/topics/oidc/java/logout.adoc +++ b/topics/oidc/java/logout.adoc @@ -1,5 +1,5 @@ -=== 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 -`http://auth-server/auth/realms/{realm-name}/tokens/logout?redirect_uri=encodedRedirectUri`. This will log you out if you have a SSO session with your browser. \ No newline at end of file +`$$http://auth-server/auth/realms/{realm-name}/tokens/logout?redirect_uri=encodedRedirectUri$$`. This will log you out if you have a SSO session with your browser. \ No newline at end of file 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 old mode 100755 new mode 100644 index 69c52a1daf..2ddd90f00a --- a/topics/oidc/java/servlet-filter-adapter.adoc +++ b/topics/oidc/java/servlet-filter-adapter.adoc @@ -1,9 +1,9 @@ [[_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.title}} adapter you opt to use the 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. -Instead you define a filter mapping using the {{book.project.title}} servlet filter adapter to secure the url patterns you want to secure. +Instead you define a filter mapping using the {{book.project.name}} servlet filter adapter to secure the url patterns you want to secure. WARNING: Backchannel logout works a bit differently than the standard adapters. Instead of invalidating the HTTP session it marks the session id as logged out. @@ -31,22 +31,22 @@ There's no way standard way to invalidate an HTTP session based on a session id. ---- In the snippet above there are two url-patterns. - _/protected/*_ are the files we want protected, while the _/keycloak/*_ url-pattern handles callbacks from the {{book.project.title}} server. + _/protected/*_ are the files we want protected, while the _/keycloak/*_ url-pattern handles callbacks from the {{book.project.name}} server. -Note that you should configure your client in the {{book.project.title}} Admin Console with an Admin URL that points to a secured section covered by the filter's url-pattern. +Note that you should configure your client in the {{book.project.name}} Admin Console with an Admin URL that points to a secured section covered by the filter's url-pattern. The Admin URL will make callbacks to the Admin URL to do things like backchannel logout. So, the Admin URL in this example should be `http[s]://hostname/{context-root}/keycloak`. -The {{book.project.title}} filter has the same configuration parameters as the other adapters except you must define them as filter init params instead of context params. +The {{book.project.name}} filter has the same configuration parameters as the other adapters except you must define them as filter init params instead of context params. To use this filter, include this maven artifact in your WAR poms: -[source,xml] +[source,xml, subs="attributes"] ---- - - org.keycloak - keycloak-servlet-filter-adapter - &project.version; - +<dependency> + <groupId>org.keycloak</groupId> + <artifactId>keycloak-servlet-filter-adapter</artifactId> + <version>{{book.project.version}}</version> +</dependency> ---- 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 8653cbadd6..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. @@ -239,15 +239,15 @@ Options is an Object, where: * token - Set an initial value for the token. * refreshToken - Set an initial value for the refresh token. * idToken - Set an initial value for the id token (only together with token or refreshToken). -* timeSkew - Set an initial value for skew between local time and Keycloak server in seconds (only together with token or refreshToken). +* timeSkew - Set an initial value for skew between local time and {{book.project.name}} server in seconds (only together with token or refreshToken). * checkLoginIframe - Set to enable/disable monitoring login state (default is true). * checkLoginIframeInterval - Set the interval to check login state (default is 5 seconds). -* responseMode - Set the OpenID Connect response mode send to Keycloak server at login request. Valid values are query or fragment . Default value is fragment, which means that after successful authentication will Keycloak redirect to javascript application with OpenID Connect parameters added in URL fragment. This is generally safer and recommended over query. +* responseMode - Set the OpenID Connect response mode send to {{book.project.name}} server at login request. Valid values are query or fragment . Default value is fragment, which means that after successful authentication will {{book.project.name}} redirect to javascript application with OpenID Connect parameters added in URL fragment. This is generally safer and recommended over query. * flow - Set the OpenID Connect flow. Valid values are standard, implicit or hybrid. 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 46fc8c2397..d4c589bb22 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: @@ -16,11 +16,11 @@ Connect implementation in {{book.project.name}}. The endpoint is: To get the full URL add the base URL for {{book.project.name}} and replace `REALM-NAME` with the name of your realm. For example: -http://localhost:8080/auth/realms/master/.well-known/openid-configuration +$$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 <