From 294312dc81c19c57c3170665bdbc70a13e9f98b8 Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Wed, 1 Jun 2016 13:02:44 +0200 Subject: [PATCH] Re-structuring --- .gitignore | 3 + README.adoc | 6 +- SUMMARY.adoc | 66 +++++++---- book.json | 39 +++++++ build.sh | 9 ++ gitlab-conversion.py | 107 ++++++++++++++++++ topics/{ => oidc/java}/adapter-context.adoc | 8 +- .../java}/adapter_error_handling.adoc | 2 +- topics/{ => oidc/java}/fuse-adapter.adoc | 2 +- topics/{ => oidc/java}/jaas.adoc | 2 +- .../java/java-adapter-config.adoc} | 83 ++++++-------- topics/oidc/java/java-adapters.adoc | 1 + topics/{ => oidc/java}/jboss-adapter.adoc | 8 +- topics/{ => oidc/java}/jetty8-adapter.adoc | 6 +- topics/{ => oidc/java}/jetty9-adapter.adoc | 6 +- topics/{ => oidc/java}/logout.adoc | 2 +- topics/{ => oidc/java}/multi-tenancy.adoc | 2 +- .../java}/servlet-filter-adapter.adoc | 2 +- .../{ => oidc/java}/spring-boot-adapter.adoc | 6 +- .../java}/spring-security-adapter.adoc | 18 +-- topics/{ => oidc/java}/tomcat-adapter.adoc | 6 +- topics/{ => oidc}/javascript-adapter.adoc | 2 +- .../oidc-generic.adoc} | 39 +++++-- topics/oidc/oidc-overview.adoc | 8 ++ topics/overview/overview.adoc | 0 topics/overview/supported-protocols.adoc | 0 topics/overview/what-are-client-adapters.adoc | 0 topics/preface.adoc | 2 +- topics/saml/saml-overview.adoc | 1 + 29 files changed, 317 insertions(+), 119 deletions(-) create mode 100755 book.json create mode 100755 build.sh create mode 100755 gitlab-conversion.py rename topics/{ => oidc/java}/adapter-context.adoc (85%) rename topics/{ => oidc/java}/adapter_error_handling.adoc (98%) rename topics/{ => oidc/java}/fuse-adapter.adoc (97%) rename topics/{ => oidc/java}/jaas.adoc (99%) rename topics/{oidc.adoc => oidc/java/java-adapter-config.adoc} (81%) mode change 100755 => 100644 create mode 100644 topics/oidc/java/java-adapters.adoc rename topics/{ => oidc/java}/jboss-adapter.adoc (98%) rename topics/{ => oidc/java}/jetty8-adapter.adoc (94%) rename topics/{ => oidc/java}/jetty9-adapter.adoc (98%) rename topics/{ => oidc/java}/logout.adoc (97%) rename topics/{ => oidc/java}/multi-tenancy.adoc (98%) rename topics/{ => oidc/java}/servlet-filter-adapter.adoc (98%) rename topics/{ => oidc/java}/spring-boot-adapter.adoc (96%) rename topics/{ => oidc/java}/spring-security-adapter.adoc (97%) rename topics/{ => oidc/java}/tomcat-adapter.adoc (96%) rename topics/{ => oidc}/javascript-adapter.adoc (99%) rename topics/{installed-applications.adoc => oidc/oidc-generic.adoc} (65%) mode change 100755 => 100644 create mode 100644 topics/oidc/oidc-overview.adoc create mode 100644 topics/overview/overview.adoc create mode 100644 topics/overview/supported-protocols.adoc create mode 100644 topics/overview/what-are-client-adapters.adoc create mode 100644 topics/saml/saml-overview.adoc diff --git a/.gitignore b/.gitignore index 44612eb8b4..39e1f9943f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +_book +node_modules + # Intellij ################### .idea diff --git a/README.adoc b/README.adoc index b1550581b0..08ecb3da6d 100755 --- a/README.adoc +++ b/README.adoc @@ -1,10 +1,10 @@ -Securing Client Applications Guide -====================== +{{book.title}} +=========================================== image:images/keycloak_logo.png[alt="Keycloak"] -*Keycloak* _Documentation_ for {{book.versions.swarm}} +*Keycloak* _Documentation_ for {{book.project.version}} http://www.keycloak.org diff --git a/SUMMARY.adoc b/SUMMARY.adoc index 20e507cbb0..1cc0a7c026 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -1,25 +1,49 @@ -== Securing Client Applications Guide - -//. link:topics/templates/document-attributes.adoc[] -:imagesdir: images += {{book.title}} . link:topics/preface.adoc[Preface] - . link:topics/Overview.adoc[Overview] - . link:topics/oidc.adoc[OpenID Connect Client Adapters] - .. link:topics/jboss-adapter.adoc[JBoss/Wildfly Adapter] - .. link:topics/tomcat-adapter.adoc[Tomcat 6, 7 and 8 Adapters] - .. link:topics/jetty9-adapter.adoc[Jetty 9.x Adapters] - .. link:topics/jetty8-adapter.adoc[Jetty 8.1.x Adapter] - .. link:topics/servlet-filter-adapter.adoc[Java Servlet Filter Adapter] - .. link:topics/fuse-adapter.adoc[JBoss Fuse and Apache Karaf Adapter] - .. link:topics/javascript-adapter.adoc[Javascript Adapter] - .. link:topics/spring-boot-adapter.adoc[Spring Boot Adapter] - .. link:topics/spring-security-adapter.adoc[Spring Security Adapter] - .. link:topics/installed-applications.adoc[Installed Applications] - .. link:topics/logout.adoc[Logout] - .. link:topics/adapter_error_handling.adoc[Error Handling] - .. link:topics/multi-tenancy.adoc[ Multi Tenancy] - .. link:topics/jaas.adoc[JAAS plugin] - . link:topics/saml.adoc[SAML Client Adapters] + . link:topics/overview/overview.adoc[Overview] + .. link:topics/overview/what-are-client-adapters.adoc[What are Client Adapters?] + .. link:topics/overview/supported-protocols.adoc[Supported Protocols] + + . link:topics/oidc/oidc-overview.adoc[OpenID Connect] + + .. link:topics/oidc/java/java-adapters.adoc[Java Adapters] + ... link:topics/oidc/java/java-adapter-config.adoc[Java Adapters Config] + ... link:topics/oidc/java/jboss-adapter.adoc[JBoss EAP/Wildfly Adapter] + ... link:topics/oidc/java/fuse-adapter.adoc[JBoss Fuse and Apache Karaf Adapter] + {% if book.community %} + ... link:topics/oidc/java/tomcat-adapter.adoc[Tomcat 6, 7 and 8 Adapters] + ... link:topics/oidc/java/jetty9-adapter.adoc[Jetty 9.x Adapters] + ... link:topics/oidc/java/jetty8-adapter.adoc[Jetty 8.1.x Adapter] + ... link:topics/oidc/java/spring-boot-adapter.adoc[Spring Boot Adapter] + ... link:topics/oidc/java/spring-security-adapter.adoc[Spring Security Adapter] + {% endif %} + ... link:topics/oidc/java/servlet-filter-adapter.adoc[Java Servlet Filter Adapter] + ... link:topics/oidc/java/jaas.adoc[JAAS plugin] + ... link:topics/oidc/java/adapter-context.adoc[Keycloak Security Context] + ... link:topics/oidc/java/adapter_error_handling.adoc[Error Handling] + ... link:topics/oidc/java/logout.adoc[Logout] + ... link:topics/oidc/java/multi-tenancy.adoc[Multi Tenancy] + + .. link:topics/oidc/javascript-adapter.adoc[JavaScript Adapter] + + .. link:topics/oidc/oidc-generic.adoc[Other OpenID Connect libraries] + + . link:topics/saml/saml-overview.adoc[SAML] + + +// . link:topics/oidc.adoc[OpenID Connect Client Adapters] + +// +// +//{% if book.community %} +// +// +//{% endif %} +// .. link:topics/installed-applications.adoc[Installed Applications] +// +// +// +// . link:topics/saml.adoc[SAML Client Adapters] diff --git a/book.json b/book.json new file mode 100755 index 0000000000..d186d09b8c --- /dev/null +++ b/book.json @@ -0,0 +1,39 @@ +{ + "gitbook": "2.x.x", + "structure": { + "readme": "README.adoc" + }, + "plugins": [ + "toggle-chapters", + "ungrey", + "splitter" + ], + "variables": { + "title": "Keycloak Securing Client Applications Guide", + "community": true, + "product": false, + "images": "keycloak-images", + "appserver": { + "name": "Wildfly", + "version": "10" + }, + "adminguide": { + "name": "Keycloak 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 new file mode 100755 index 0000000000..4befdf8200 --- /dev/null +++ b/build.sh @@ -0,0 +1,9 @@ +#!/bin/bash + +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 new file mode 100755 index 0000000000..a69a7382ab --- /dev/null +++ b/gitlab-conversion.py @@ -0,0 +1,107 @@ +import sys, os, re, json, shutil, errno + +def transform(root, f, targetdir): + full = os.path.join(root, f) + input = open(full, 'r').read() + dir = os.path.join(targetdir, root) + if not os.path.exists(dir): + os.makedirs(dir) + output = open(os.path.join(dir, f), 'w') + input = applyTransformation(input) + output.write(input) + + +def applyTransformation(input): + for variable in re.findall(r"\{\{(.*?)\}\}", input): + tmp = variable.replace('.', '_') + input = input.replace(variable, tmp) + input = input.replace('{{', '{').replace('}}', '}') + input = re.sub(r"<}==true]\g<2>endif::[]", input) + input = re.sub(r"image:(\.\./)*", "image:", input) + input = re.sub(r"image::(\.\./)*", "image::", input) + return input + + +indir = 'topics' +targetdir = 'target' +if len(sys.argv) > 1: + targetdir = sys.argv[1] + +shutil.rmtree(os.path.join(targetdir, 'images'), ignore_errors=True) +shutil.rmtree(os.path.join(targetdir, 'keycloak-images'), ignore_errors=True) +shutil.rmtree(os.path.join(targetdir, 'rhsso-images'), ignore_errors=True) +shutil.copytree('images',os.path.join(targetdir, 'images')) +#shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images')) +#shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images')) + +tmp = os.path.join(targetdir, 'topics') +if not os.path.exists(tmp): + os.makedirs(tmp) + +# transform files +for root, dirs, filenames in os.walk(indir): + for f in filenames: + transform(root,f,targetdir) + +# Create master.doc includes +input = open('SUMMARY.adoc', 'r').read() +output = open(os.path.join(targetdir, 'master.adoc'), 'w') + +output.write(""" +:toc: +:toclevels: 3 +:numbered: + +include::document-attributes.adoc[] +""") + +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: + data = json.load(data_file) + +variables = data['variables'] + +def makeAttributes(variables, variable, list): + for i in variables.keys(): + if variable is None: + tmp = i + else: + tmp = variable + '_' + i + if isinstance(variables[i],dict): + makeAttributes(variables[i], tmp, list) + elif isinstance(variables[i],bool): + boolval = 'false' + if variables[i]: + boolval = 'true' + list.append({tmp: boolval}) + else: + list.append({tmp: str(variables[i])}) + + +attributeList = [] +makeAttributes(variables, None, attributeList) + +output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w') +for attribute in attributeList: + for k in attribute.keys(): + output.write(':book_' + k + ": " + attribute[k] + "\n") + +print "Transformation complete!" + + + + + + + + + diff --git a/topics/adapter-context.adoc b/topics/oidc/java/adapter-context.adoc similarity index 85% rename from topics/adapter-context.adoc rename to topics/oidc/java/adapter-context.adoc index ba99e8f2bf..9ac083172f 100755 --- a/topics/adapter-context.adoc +++ b/topics/oidc/java/adapter-context.adoc @@ -1,10 +1,4 @@ -= KeycloakSecurityContext -:doctype: book -:sectnums: -:toc: left -:icons: font -:experimental: -:sourcedir: . +=== Keycloak Security Context The `KeycloakSecurityContext` interface is available if you need to look at the access token directly. This context is also useful if you need to get the encoded access token so you can make additional REST invocations. diff --git a/topics/adapter_error_handling.adoc b/topics/oidc/java/adapter_error_handling.adoc similarity index 98% rename from topics/adapter_error_handling.adoc rename to topics/oidc/java/adapter_error_handling.adoc index 82c246b5f5..bf300cd7ca 100755 --- a/topics/adapter_error_handling.adoc +++ b/topics/oidc/java/adapter_error_handling.adoc @@ -1,6 +1,6 @@ [[_adapter_error_handling]] -= Error Handling +=== Error Handling Keycloak has some error handling facilities for servlet based client adapters. When an error is encountered in authentication, keycloak will call `HttpServletResponse.sendError()`. diff --git a/topics/fuse-adapter.adoc b/topics/oidc/java/fuse-adapter.adoc similarity index 97% rename from topics/fuse-adapter.adoc rename to topics/oidc/java/fuse-adapter.adoc index 948cf69d4b..37888923f1 100755 --- a/topics/fuse-adapter.adoc +++ b/topics/oidc/java/fuse-adapter.adoc @@ -1,6 +1,6 @@ [[_fuse_adapter]] -= JBoss Fuse and Apache Karaf Adapter +=== JBoss Fuse and Apache Karaf Adapter Currently Keycloak supports securing your web applications running inside http://www.jboss.org/products/fuse/overview/[JBoss Fuse] or http://karaf.apache.org/[Apache Karaf] . It leverages <<_jetty8_adapter,Jetty 8 adapter>> as both JBoss Fuse 6.1 and Apache Karaf 3 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. diff --git a/topics/jaas.adoc b/topics/oidc/java/jaas.adoc similarity index 99% rename from topics/jaas.adoc rename to topics/oidc/java/jaas.adoc index 5307d39e05..8145355ce3 100755 --- a/topics/jaas.adoc +++ b/topics/oidc/java/jaas.adoc @@ -1,6 +1,6 @@ [[_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, but directly choose one of our adapters. However some applications and systems may still rely on pure legacy JAAS solution. diff --git a/topics/oidc.adoc b/topics/oidc/java/java-adapter-config.adoc old mode 100755 new mode 100644 similarity index 81% rename from topics/oidc.adoc rename to topics/oidc/java/java-adapter-config.adoc index 7c598b1d4e..26794cd084 --- a/topics/oidc.adoc +++ b/topics/oidc/java/java-adapter-config.adoc @@ -1,20 +1,9 @@ -[[_adapter_config]] - -= Adapters - -Keycloak can secure a wide variety of application types. -This section defines which application types are supported and how to configure and install them so that you can use Keycloak to secure your applications. - -These client adapters use an extension of the OpenID Connect protocol (a derivate of OAuth 2.0). This extension provides support for clustering, backchannel logout, and other non-standard adminstrative functions. -The Keycloak project also provides a separate, standalone, generic, SAML client adapter. -But that is describe in a separate document and has a different download. - - -== General Adapter Config +[[_java_adapter_config]] +=== Java Adapter Config Each adapter supported by Keycloak can be configured by a simple JSON text file. -This is what one might look like: +This is what one might look like: [source] @@ -45,117 +34,117 @@ This is what one might look like: "client-keystore-password" : "geheim", "client-key-password" : "geheim" } ----- +---- Some of these configuration switches may be adapter specific and some are common across all adapters. For Java adapters you can use `${...}` enclosure as System property replacement. For example `${jboss.server.config.dir}`. Also, you can obtain a template for this config file from the admin console. Go to the realm and select the application you want a template for. -Go to the `Installation` tab and this will provide you with a template that includes the public key of the realm. +Go to the `Installation` tab and this will provide you with a template that includes the public key of the realm. -Here is a description of each item: +Here is a description of each item: realm:: Name of the realm representing the users of your distributed applications and services. - This is _REQUIRED._ + This is _REQUIRED._ resource:: Username of the application. - Each application has a username that is used when the application connects with the Keycloak server to turn an access code into an access token (part of the OAuth 2.0 protocol). This is _REQUIRED._ + Each application has a username that is used when the application connects with the Keycloak server to turn an access code into an access token (part of the OAuth 2.0 protocol). This is _REQUIRED._ realm-public-key:: PEM format of public key. You can obtain this from the administration console. - This is _REQUIRED._ + This is _REQUIRED._ auth-server-url:: The base URL of the Keycloak Server. All other Keycloak pages and REST services are derived from this. - It is usually of the form `https://host:port/auth` This is _REQUIRED._ + It is usually of the form `https://host:port/auth` This is _REQUIRED._ ssl-required:: Ensures that all communication to and from the Keycloak server from the adapter is over HTTPS. This is _OPTIONAL_. The default value is _external_ meaning that HTTPS is required by default for external requests. - Valid values are 'all', 'external' and 'none'. + Valid values are 'all', 'external' and 'none'. use-resource-role-mappings:: If set to true, the adapter will look inside the token for application level role mappings for the user. If false, it will look at the realm level for user role mappings. This is _OPTIONAL_. - The default value is _false_. + The default value is _false_. public-client:: If set to true, the adapter will not send credentials for the client to Keycloak. - The default value is _false_. + The default value is _false_. enable-cors:: This enables CORS support. It will handle CORS preflight requests. It will also look into the access token to determine valid origins. This is _OPTIONAL_. - The default value is _false_. + The default value is _false_. cors-max-age:: If CORS is enabled, this sets the value of the `Access-Control-Max-Age` header. This is _OPTIONAL_. - If not set, this header is not returned in CORS responses. + If not set, this header is not returned in CORS responses. cors-allowed-methods:: If CORS is enabled, this sets the value of the `Access-Control-Allow-Methods` header. This should be a comma-separated string. This is _OPTIONAL_. - If not set, this header is not returned in CORS responses. + If not set, this header is not returned in CORS responses. cors-allowed-headers:: If CORS is enabled, this sets the value of the `Access-Control-Allow-Headers` header. This should be a comma-separated string. This is _OPTIONAL_. - If not set, this header is not returned in CORS responses. + If not set, this header is not returned in CORS responses. bearer-only:: This tells the adapter to only do bearer token authentication. That is, it will not do OAuth 2.0 redirects, but only accept bearer tokens through the `Authorization` header. This is _OPTIONAL_. - The default value is _false_. + The default value is _false_. enable-basic-auth:: This tells the adapter to also support basic authentication. If this option is enabled, then _secret_ must also be provided. This is _OPTIONAL_. - The default value is _false_. + The default value is _false_. expose-token:: If `true`, an authenticated browser client (via a Javascript HTTP invocation) can obtain the signed access token via the URL `root/k_query_bearer_token`. This is _OPTIONAL_. - The default value is _false_. + The default value is _false_. credentials:: Specify the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type. Currently only `password` is supported. - This is _REQUIRED_. + This is _REQUIRED_. connection-pool-size:: Adapters will make separate HTTP invocations to the Keycloak Server to turn an access code into an access token. This config option defines how many connections to the Keycloak Server should be pooled. This is _OPTIONAL_. - The default value is `20`. + The default value is `20`. disable-trust-manager:: If the Keycloak Server requires HTTPS and this config option is set to `true` you do not have to specify a truststore. While convenient, this setting is not recommended as you will not be verifying the host name of the Keycloak Server. This is _OPTIONAL_. - The default value is `false`. + The default value is `false`. allow-any-hostname:: If the Keycloak Server requires HTTPS and this config option is set to `true` the Keycloak Server's certificate is validated via the truststore, but host name validation is not done. This is not a recommended. This seting may be useful in test environments This is _OPTIONAL_. - The default value is `false`. + The default value is `false`. truststore:: This setting is for Java adapters. @@ -166,55 +155,55 @@ truststore:: 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 Keycloak server's SSL keystore. - This is _OPTIONAL_ if `ssl-required` is `none` or `disable-trust-manager` is `true`. + This is _OPTIONAL_ if `ssl-required` is `none` or `disable-trust-manager` is `true`. truststore-password:: Password for the truststore keystore. - This is _REQUIRED_ if `truststore` is set. + This is _REQUIRED_ if `truststore` is set. client-keystore:: _Not supported yet, but we will support in future versions._ This setting is for Java adapters. This is the file path to a Java keystore file. This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the Keycloak server. - This is _OPTIONAL_. + This is _OPTIONAL_. client-keystore-password:: _Not supported yet, but we will support in future versions._ Password for the client keystore. - This is _REQUIRED_ if `client-keystore` is set. + This is _REQUIRED_ if `client-keystore` is set. client-key-password:: _Not supported yet, but we will support in future versions._ Password for the client's key. - This is _REQUIRED_ if `client-keystore` is set. + This is _REQUIRED_ if `client-keystore` is set. auth-server-url-for-backend-requests:: Alternative location of auth-server-url used just for backend requests. It must be absolute URI. - Useful especially in cluster (see <<_relative_uri_optimization,Relative URI Optimization>>) or if you would like to use _https_ for browser requests but stick with _http_ for backend requests etc. + Useful especially in cluster (see <<_relative_uri_optimization,Relative URI Optimization>>) or if you would like to use _https_ for browser requests but stick with _http_ for backend requests etc. always-refresh-token:: If _true_, Keycloak will refresh token in every request. - More info in <<_refresh_token_each_req,Refresh token in each request>> . + More info in <<_refresh_token_each_req,Refresh token in each request>> . register-node-at-startup:: If _true_, then adapter will send registration request to Keycloak. - It's _false_ by default and useful just in cluster (See <<_registration_app_nodes,Registration of application nodes to Keycloak>>) + It's _false_ by default and useful just in cluster (See <<_registration_app_nodes,Registration of application nodes to Keycloak>>) register-node-period:: Period for re-registration adapter to Keycloak. Useful in cluster. - See <<_registration_app_nodes,Registration of application nodes to Keycloak>> for details. + See <<_registration_app_nodes,Registration of application nodes to Keycloak>> for details. token-store:: Possible values are _session_ and _cookie_. Default is _session_, which means that adapter stores account info in HTTP Session. Alternative _cookie_ means storage of info in cookie. - See <<_stateless_token_store,Stateless token store>> for details. + See <<_stateless_token_store,Stateless token store>> for details. principal-attribute:: OpenID Connection ID Token attribute to populate the UserPrincipal name with. If token attribute is null, defaults to `sub`. - Possible values are `sub`, `preferred_username`, `email`, `name`, `nickname`, `given_name`, `family_name`. + Possible values are `sub`, `preferred_username`, `email`, `name`, `nickname`, `given_name`, `family_name`. turn-off-change-session-id-on-login:: The session id is changed by default on a successful login on some platforms to plug a security attack vector (Tomcat 8, Jetty9, Undertow/Wildfly). Change this to true if you want to turn this off This is _OPTIONAL_. - The default value is _false_. + The default value is _false_. diff --git a/topics/oidc/java/java-adapters.adoc b/topics/oidc/java/java-adapters.adoc new file mode 100644 index 0000000000..274b47698a --- /dev/null +++ b/topics/oidc/java/java-adapters.adoc @@ -0,0 +1 @@ +== Java Adapters \ No newline at end of file diff --git a/topics/jboss-adapter.adoc b/topics/oidc/java/jboss-adapter.adoc similarity index 98% rename from topics/jboss-adapter.adoc rename to topics/oidc/java/jboss-adapter.adoc index 351eba5206..d65ac497be 100755 --- a/topics/jboss-adapter.adoc +++ b/topics/oidc/java/jboss-adapter.adoc @@ -1,6 +1,6 @@ [[_jboss_adapter]] -= JBoss/Wildfly Adapter +=== JBoss/Wildfly Adapter To be able to secure WAR apps deployed on JBoss AS 7.1.1, JBoss EAP 6.x, or Wildfly, you must install and configure the Keycloak Subsystem. You then have two options to secure your WARs. @@ -9,7 +9,7 @@ Alternatively, you don't have to crack open your WARs at all and can apply Keycl Both methods are described in this section. [[_jboss_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. @@ -144,7 +144,7 @@ public class CustomerService { We hope to improve our integration in the future so that you don't have to specify the @SecurityDomain annotation when you want to propagate a keycloak security context to the EJB tier. -== 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. @@ -206,7 +206,7 @@ Here's an example pulled from one of the examples that comes distributed with Ke ---- -== Securing WARs via Keycloak Subsystem +==== Securing WARs via Keycloak Subsystem You do not have to crack open a WAR to secure it with Keycloak. Alternatively, you can externally secure it via the Keycloak Adapter Subsystem. diff --git a/topics/jetty8-adapter.adoc b/topics/oidc/java/jetty8-adapter.adoc similarity index 94% rename from topics/jetty8-adapter.adoc rename to topics/oidc/java/jetty8-adapter.adoc index 39159755ad..2ccd38bd0d 100755 --- a/topics/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/jetty9-adapter.adoc b/topics/oidc/java/jetty9-adapter.adoc similarity index 98% rename from topics/jetty9-adapter.adoc rename to topics/oidc/java/jetty9-adapter.adoc index ed0a8c6daa..d1972e4da9 100755 --- a/topics/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/logout.adoc b/topics/oidc/java/logout.adoc similarity index 97% rename from topics/logout.adoc rename to topics/oidc/java/logout.adoc index da2a11e6b2..3a9c42dac4 100755 --- a/topics/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 point the browser at the url `http://auth-server/auth/realms/{realm-name}/tokens/logout?redirect_uri=encodedRedirectUri`. diff --git a/topics/multi-tenancy.adoc b/topics/oidc/java/multi-tenancy.adoc similarity index 98% rename from topics/multi-tenancy.adoc rename to topics/oidc/java/multi-tenancy.adoc index b792d0bdcc..5f339f16be 100755 --- a/topics/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 one single target application (WAR) can be secured by a single (or clustered) Keycloak server, authenticating its users against different realms. In practice, this means that one application needs to use different `keycloak.json` files. diff --git a/topics/servlet-filter-adapter.adoc b/topics/oidc/java/servlet-filter-adapter.adoc similarity index 98% rename from topics/servlet-filter-adapter.adoc rename to topics/oidc/java/servlet-filter-adapter.adoc index 07092c4a77..99e83244f7 100755 --- a/topics/servlet-filter-adapter.adoc +++ b/topics/oidc/java/servlet-filter-adapter.adoc @@ -1,5 +1,5 @@ -= Java Servlet Filter Adapter +=== Java Servlet Filter Adapter If you want to use Keycloak with a Java servlet application that doesn't have an adapter for that servlet platform, you can opt to use the servlet filter adapter that Keycloak has. This adapter works a little differently than the other adapters. diff --git a/topics/spring-boot-adapter.adoc b/topics/oidc/java/spring-boot-adapter.adoc similarity index 96% rename from topics/spring-boot-adapter.adoc rename to topics/oidc/java/spring-boot-adapter.adoc index e3ae217af2..ef70d29bb1 100755 --- a/topics/spring-boot-adapter.adoc +++ b/topics/oidc/java/spring-boot-adapter.adoc @@ -1,11 +1,11 @@ -= 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/spring-security-adapter.adoc b/topics/oidc/java/spring-security-adapter.adoc similarity index 97% rename from topics/spring-security-adapter.adoc rename to topics/oidc/java/spring-security-adapter.adoc index cce17a5f46..2766317e32 100755 --- a/topics/spring-security-adapter.adoc +++ b/topics/oidc/java/spring-security-adapter.adoc @@ -1,5 +1,5 @@ -= 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 <<_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. diff --git a/topics/tomcat-adapter.adoc b/topics/oidc/java/tomcat-adapter.adoc similarity index 96% rename from topics/tomcat-adapter.adoc rename to topics/oidc/java/tomcat-adapter.adoc index fc6b1b9d1a..06e93f794e 100755 --- a/topics/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/javascript-adapter.adoc b/topics/oidc/javascript-adapter.adoc similarity index 99% rename from topics/javascript-adapter.adoc rename to topics/oidc/javascript-adapter.adoc index e2bb8a7b5c..a9591730dd 100755 --- a/topics/javascript-adapter.adoc +++ b/topics/oidc/javascript-adapter.adoc @@ -1,5 +1,5 @@ -= Javascript Adapter +== Javascript Adapter The Keycloak Server comes with a Javascript library you can use to secure HTML/Javascript applications. This library is referenceable directly from the keycloak server. diff --git a/topics/installed-applications.adoc b/topics/oidc/oidc-generic.adoc old mode 100755 new mode 100644 similarity index 65% rename from topics/installed-applications.adoc rename to topics/oidc/oidc-generic.adoc index de5bbded5f..a697467c86 --- a/topics/installed-applications.adoc +++ b/topics/oidc/oidc-generic.adoc @@ -1,23 +1,46 @@ +== Other OpenID Connect libraries -= Installed Applications +OAuth2 https://tools.ietf.org/html/rfc6749 +OpenID Connect http://openid.net/connect/ -Keycloak provides two special redirect uris for installed applications. + +=== Endpoints + +TODO + +=== Flows + +==== Authorization Grant + +==== Implicit + +==== Resource Owner Password Credentials + +==== Client Credentials + +=== Redirect URIs + +Keycloak provides two special redirect uris for installed applications. [[_installed_applications_url]] -== Installed Applications url +==== Installed Applications url -http://localhost +http://localhost This returns the code to a web server on the client as a query parameter. Any port number is allowed. -This makes it possible to start a web server for the installed application on any free port number without requiring changes in the `Admin Console`. +This makes it possible to start a web server for the installed application on any free port number without requiring changes in the `Admin Console`. [[_installed_applications_urn]] -== Installed Applications urn +==== Installed Applications urn -`urn:ietf:wg:oauth:2.0:oob` +`urn:ietf:wg:oauth:2.0:oob` If its not possible to start a web server in the client (or a browser is not available) it is possible to use the special `urn:ietf:wg:oauth:2.0:oob` redirect uri. When this redirect uri is used Keycloak displays a page with the code in the title and in a box on the page. The application can either detect that the browser title has changed, or the user can copy/paste the code manually to the application. -With this redirect uri it is also possible for a user to use a different device to obtain a code to paste back to the application. +With this redirect uri it is also possible for a user to use a different device to obtain a code to paste back to the application. + +=== Session Management + +=== Dynamic Client Registration \ No newline at end of file diff --git a/topics/oidc/oidc-overview.adoc b/topics/oidc/oidc-overview.adoc new file mode 100644 index 0000000000..5be5b1b151 --- /dev/null +++ b/topics/oidc/oidc-overview.adoc @@ -0,0 +1,8 @@ +== OpenID Connect + +Keycloak can secure a wide variety of application types. +This section defines which application types are supported and how to configure and install them so that you can use Keycloak to secure your applications. + +These client adapters use an extension of the OpenID Connect protocol (a derivate of OAuth 2.0). This extension provides support for clustering, backchannel logout, and other non-standard adminstrative functions. +The Keycloak project also provides a separate, standalone, generic, SAML client adapter. +But that is describe in a separate document and has a different download. \ No newline at end of file diff --git a/topics/overview/overview.adoc b/topics/overview/overview.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/topics/overview/supported-protocols.adoc b/topics/overview/supported-protocols.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/topics/overview/what-are-client-adapters.adoc b/topics/overview/what-are-client-adapters.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/topics/preface.adoc b/topics/preface.adoc index fb0c9657df..860e9fd39f 100755 --- a/topics/preface.adoc +++ b/topics/preface.adoc @@ -1,4 +1,4 @@ -= Preface +== Preface In some of the example listings, what is meant to be displayed on one line does not fit inside the available page width.These lines have been broken up. A '\' at the end of a line means that a break has been introduced to fit in the page, with the following lines indented. So: diff --git a/topics/saml/saml-overview.adoc b/topics/saml/saml-overview.adoc new file mode 100644 index 0000000000..98e42693b2 --- /dev/null +++ b/topics/saml/saml-overview.adoc @@ -0,0 +1 @@ +== SAML \ No newline at end of file