From a25aed13ed39ddd937aca0a52a5ceab68ceda95b Mon Sep 17 00:00:00 2001 From: --add Date: Fri, 3 Jun 2016 18:16:22 +0530 Subject: [PATCH 1/4] resolving compilation errors for the downstream build system --- topics/oidc/java/fuse-adapter.adoc | 6 ++++-- topics/oidc/java/jboss-adapter.adoc | 4 ++-- topics/oidc/java/jetty9-adapter.adoc | 4 ++-- topics/oidc/java/servlet-filter-adapter.adoc | 4 ++-- topics/oidc/java/tomcat-adapter.adoc | 4 ++-- topics/saml/java/jetty-adapter.adoc | 2 +- topics/saml/java/jetty-adapter/jetty9_installation.adoc | 2 +- 7 files changed, 14 insertions(+), 12 deletions(-) diff --git a/topics/oidc/java/fuse-adapter.adoc b/topics/oidc/java/fuse-adapter.adoc index c8833f4154..2eb700964b 100755 --- a/topics/oidc/java/fuse-adapter.adoc +++ b/topics/oidc/java/fuse-adapter.adoc @@ -80,7 +80,9 @@ It's recommended to use your own Jetty engine for your apps (similarly like `cxf Keycloak mainly addresses usecases for authentication of web applications, however if your admin services (like fuse admin console) are protected with Keycloak, it may be good to protect non-web services like SSH with Keycloak credentials too. It's possible to do it by using JAAS login module, which -allows to remotely connect to Keycloak and verify credentials based on <<_direct_access_grants,Direct Access Grants>> . +allows to remotely connect to Keycloak and verify credentials based on + +// <<_direct_access_grants,Direct Access Grants>> . Example steps for enable SSH authentication require changing the configuration of `sshRealm` in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg`, then adding file `$FUSE_HOME/etc/keycloak-direct-access.json` (this is default location, which can be changed) and install the needed feature `keycloak-jaas`. It's described in details @@ -99,4 +101,4 @@ It's described in details in the README file of Fuse example, which in example d ===== 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 Keycloak. \ No newline at end of file +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 Keycloak. diff --git a/topics/oidc/java/jboss-adapter.adoc b/topics/oidc/java/jboss-adapter.adoc index f4d861fe13..cd1d7b0ce3 100755 --- a/topics/oidc/java/jboss-adapter.adoc +++ b/topics/oidc/java/jboss-adapter.adoc @@ -174,7 +174,7 @@ public class CustomerService { This section describes how to secure a WAR directly by adding config and editing files within your WAR package. The first thing you must do is create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <<_adapter_config,general adapter configuration>> section. +The format of this config file is describe in the <<_saml-general-config,general adapter configuration>> section. Next you must set the `auth-method` to `KEYCLOAK` in `web.xml`. You also have to use standard servlet security to specify role-base constraints on your URLs. @@ -259,7 +259,7 @@ 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 <<_adapter_config,general adapter configuration>>. +The rest of the configuration corresponds pretty much one to one with the `keycloak.json` configuration options defined in <<_saml-general-config,general adapter configuration>>. 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. diff --git a/topics/oidc/java/jetty9-adapter.adoc b/topics/oidc/java/jetty9-adapter.adoc index d1972e4da9..27021f3f0b 100755 --- a/topics/oidc/java/jetty9-adapter.adoc +++ b/topics/oidc/java/jetty9-adapter.adoc @@ -58,7 +58,7 @@ This is a Jetty specific config file and you must define a Keycloak specific aut ---- Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <<_adapter_config,general adapter configuration>> section. +The format of this config file is describe in the <<_saml-general-config,general adapter configuration>> section. WARNING: The Jetty 9.1.x adapter will not be able to find the `keycloak.json` file. You will have to define all adapter settings within the `jetty-web.xml` file as described below. @@ -145,4 +145,4 @@ Here's an example: user ----- \ No newline at end of file +---- diff --git a/topics/oidc/java/servlet-filter-adapter.adoc b/topics/oidc/java/servlet-filter-adapter.adoc index 3f8c809b68..d3f161eca1 100755 --- a/topics/oidc/java/servlet-filter-adapter.adoc +++ b/topics/oidc/java/servlet-filter-adapter.adoc @@ -31,7 +31,7 @@ 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.title}} 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. @@ -49,4 +49,4 @@ To use this filter, include this maven artifact in your WAR poms: keycloak-servlet-filter-adapter &project.version; ----- \ No newline at end of file +---- diff --git a/topics/oidc/java/tomcat-adapter.adoc b/topics/oidc/java/tomcat-adapter.adoc index 06e93f794e..6b51783b52 100755 --- a/topics/oidc/java/tomcat-adapter.adoc +++ b/topics/oidc/java/tomcat-adapter.adoc @@ -45,7 +45,7 @@ This is a Tomcat specific config file and you must define a Keycloak specific Va ---- Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <<_adapter_config,general adapter configuration>> section. +The format of this config file is describe in the <<_saml-general-config,general adapter configuration>> section. Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example: @@ -84,4 +84,4 @@ Here's an example: user ----- \ No newline at end of file +---- diff --git a/topics/saml/java/jetty-adapter.adoc b/topics/saml/java/jetty-adapter.adoc index 6a85ed2798..78ca40cc3f 100644 --- a/topics/saml/java/jetty-adapter.adoc +++ b/topics/saml/java/jetty-adapter.adoc @@ -1,4 +1,4 @@ - +[[_jetty_adapter]] ==== Jetty SAML Adapters To be able to secure WAR apps deployed on Jetty you must install the {{book.project.name}} Jetty 9.x or 8.x SAML adapter into your Jetty installation. diff --git a/topics/saml/java/jetty-adapter/jetty9_installation.adoc b/topics/saml/java/jetty-adapter/jetty9_installation.adoc index 2554091131..515c489aa7 100644 --- a/topics/saml/java/jetty-adapter/jetty9_installation.adoc +++ b/topics/saml/java/jetty-adapter/jetty9_installation.adoc @@ -1,4 +1,4 @@ -[[_jetty9_adapter_installation]] +[[_jetty_adapter_installation]] ===== Jetty 9 Adapter Installation From bda4e117f990a4a4aa4b5d6600678f7b857c1d28 Mon Sep 17 00:00:00 2001 From: --add Date: Fri, 3 Jun 2016 18:55:19 +0530 Subject: [PATCH 2/4] corrections as per review comments --- topics/oidc/java/jboss-adapter.adoc | 4 ++-- topics/oidc/java/jetty9-adapter.adoc | 5 ++--- topics/oidc/java/servlet-filter-adapter.adoc | 2 +- topics/oidc/java/tomcat-adapter.adoc | 2 +- topics/oidc/oidc-overview.adoc | 4 +++- topics/saml/java/jetty-adapter/jetty9_installation.adoc | 2 +- 6 files changed, 10 insertions(+), 9 deletions(-) diff --git a/topics/oidc/java/jboss-adapter.adoc b/topics/oidc/java/jboss-adapter.adoc index cd1d7b0ce3..00bcc5c3a5 100755 --- a/topics/oidc/java/jboss-adapter.adoc +++ b/topics/oidc/java/jboss-adapter.adoc @@ -174,7 +174,7 @@ public class CustomerService { This section describes how to secure a WAR directly by adding config and editing files within your WAR package. The first thing you must do is create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <<_saml-general-config,general adapter configuration>> section. +The format of this config file is describe in the <<_java_adapter_config,general adapter configuration>> section. Next you must set the `auth-method` to `KEYCLOAK` in `web.xml`. You also have to use standard servlet security to specify role-base constraints on your URLs. @@ -259,7 +259,7 @@ 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 <<_saml-general-config,general adapter configuration>>. +The rest of the configuration corresponds pretty much one to one with the `keycloak.json` configuration options defined in <<_java_adapter_config,general adapter configuration>>. 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. diff --git a/topics/oidc/java/jetty9-adapter.adoc b/topics/oidc/java/jetty9-adapter.adoc index 27021f3f0b..1f3017e726 100755 --- a/topics/oidc/java/jetty9-adapter.adoc +++ b/topics/oidc/java/jetty9-adapter.adoc @@ -1,4 +1,3 @@ - [[_jetty9_adapter]] === Jetty 9.x Adapters @@ -6,7 +5,7 @@ Keycloak has a separate adapter for Jetty 9.1.x and Jetty 9.2.x that you will ha You then have to provide some extra configuration in each WAR you deploy to Jetty. Let's go over these steps. -[[_jetty9_adapter_installation]] +[[_jetty-9_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. @@ -58,7 +57,7 @@ This is a Jetty specific config file and you must define a Keycloak specific aut ---- Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <<_saml-general-config,general adapter configuration>> section. +The format of this config file is describe in the <<_java_adapter_config,general adapter configuration>> section. WARNING: The Jetty 9.1.x adapter will not be able to find the `keycloak.json` file. You will have to define all adapter settings within the `jetty-web.xml` file as described below. diff --git a/topics/oidc/java/servlet-filter-adapter.adoc b/topics/oidc/java/servlet-filter-adapter.adoc index d3f161eca1..69c52a1daf 100755 --- a/topics/oidc/java/servlet-filter-adapter.adoc +++ b/topics/oidc/java/servlet-filter-adapter.adoc @@ -31,7 +31,7 @@ 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.title}} 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. diff --git a/topics/oidc/java/tomcat-adapter.adoc b/topics/oidc/java/tomcat-adapter.adoc index 6b51783b52..1b7f6ca7de 100755 --- a/topics/oidc/java/tomcat-adapter.adoc +++ b/topics/oidc/java/tomcat-adapter.adoc @@ -45,7 +45,7 @@ This is a Tomcat specific config file and you must define a Keycloak specific Va ---- Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is describe in the <<_saml-general-config,general adapter configuration>> section. +The format of this config file is describe in the <<_java_adapter_config,general adapter configuration>> section. Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example: diff --git a/topics/oidc/oidc-overview.adoc b/topics/oidc/oidc-overview.adoc index 8436712c35..bb5fdda906 100644 --- a/topics/oidc/oidc-overview.adoc +++ b/topics/oidc/oidc-overview.adoc @@ -1,4 +1,6 @@ == OpenID Connect This section describes how you can secure applications and services with OpenID Connect using either {{book.project.name}} adapters or generic OpenID Connect -Resource Provider libraries. \ No newline at end of file +Resource Provider libraries. + +// TODO: Update the cross-reference <<_direct_access_grants,Direct Access Grants>> in the topic /oidc/java/fuse-adapter.adoc diff --git a/topics/saml/java/jetty-adapter/jetty9_installation.adoc b/topics/saml/java/jetty-adapter/jetty9_installation.adoc index 515c489aa7..2554091131 100644 --- a/topics/saml/java/jetty-adapter/jetty9_installation.adoc +++ b/topics/saml/java/jetty-adapter/jetty9_installation.adoc @@ -1,4 +1,4 @@ -[[_jetty_adapter_installation]] +[[_jetty9_adapter_installation]] ===== Jetty 9 Adapter Installation From cc4654922ed1d9a9bcb0309c96ec3e629b5eaed8 Mon Sep 17 00:00:00 2001 From: --add Date: Tue, 7 Jun 2016 11:44:38 +0530 Subject: [PATCH 3/4] sync with latest changes --- topics/oidc/java/fuse-adapter.adoc | 46 +--------------------------- topics/oidc/java/jboss-adapter.adoc | 4 --- topics/oidc/java/jetty9-adapter.adoc | 7 ++--- topics/oidc/java/tomcat-adapter.adoc | 4 +-- topics/oidc/oidc-generic.adoc | 3 +- topics/oidc/oidc-overview.adoc | 4 +-- 6 files changed, 8 insertions(+), 60 deletions(-) diff --git a/topics/oidc/java/fuse-adapter.adoc b/topics/oidc/java/fuse-adapter.adoc index 5513281432..f00dcefb33 100755 --- a/topics/oidc/java/fuse-adapter.adoc +++ b/topics/oidc/java/fuse-adapter.adoc @@ -22,51 +22,7 @@ What is supported for Fuse is: 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. -<<<<<<< HEAD -===== Builtin CXF web applications - -Some services automatically come with deployed servlets on startup. One of such examples is CXF servlet running on -http://localhost:8181/cxf context. Securing such endpoints is quite tricky. The approach, which Keycloak 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 Keycloak. -You can see the `OSGI-INF/blueprint/blueprint.xml` inside `cxf-jaxrs` example, which adds JAX-RS `customerservice` endpoint and more importantly, it secures whole `/cxf` context. - -As a side effect, all other CXF services running on default CXF HTTP destination will be secured too. Once you uninstall feature `keycloak-fuse-6.2-example`, the -original unsecured servlet on `/cxf` context is deployed back and hence context will become unsecured again. - -It's recommended to use your own Jetty engine for your apps (similarly like `cxf-jaxws` application is doing). - - -==== How to secure Fuse admin services - -===== SSH authentication to Fuse terminal with Keycloak credentials - -Keycloak mainly addresses usecases for authentication of web applications, however if your admin services (like fuse admin console) are protected -with Keycloak, it may be good to protect non-web services like SSH with Keycloak credentials too. It's possible to do it by using JAAS login module, which -allows to remotely connect to Keycloak and verify credentials based on - -// <<_direct_access_grants,Direct Access Grants>> . - -Example steps for enable SSH authentication require changing the configuration of `sshRealm` in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg`, then adding -file `$FUSE_HOME/etc/keycloak-direct-access.json` (this is default location, which can be changed) and install the needed feature `keycloak-jaas`. It's described in details -in the README file of Fuse example, which in example distribution is inside `fuse/fuse-admin/README.md` . - - -===== JMX authentication with Keycloak credentials - -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 http://hawt.io by default. - -You need to configure `jmxRealm` in `$FUSE_HOME/etc/org.apache.karaf.management.cfg`, then adding file `$FUSE_HOME/etc/keycloak-direct-access.json` -(this is default location, which can be changed) and install the needed feature `keycloak-jaas`. -It's described in details in the README file of Fuse example, which in example distribution is inside `fuse/fuse-admin/README.md` . - - -===== 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 Keycloak. -======= {% if book.community %} The best place to start is look at Fuse demo bundled as part of {{book.project.name}} examples in directory `fuse` . Most of the steps should be understandable from testing and understanding the demo. -{% endif %} ->>>>>>> 163974a212546af0df02970a57466a056b83ba5a +{% endif %} \ No newline at end of file diff --git a/topics/oidc/java/jboss-adapter.adoc b/topics/oidc/java/jboss-adapter.adoc index ddc6a4fa03..737724b9ef 100755 --- a/topics/oidc/java/jboss-adapter.adoc +++ b/topics/oidc/java/jboss-adapter.adoc @@ -174,10 +174,8 @@ public class CustomerService { This section describes how to secure a WAR directly by adding config and editing files within your WAR package. The first thing you must do is create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. - The format of this config file is describe in the <> section. - Next you must set the `auth-method` to `KEYCLOAK` in `web.xml`. You also have to use standard servlet security to specify role-base constraints on your URLs. @@ -261,9 +259,7 @@ 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 <>. - 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. diff --git a/topics/oidc/java/jetty9-adapter.adoc b/topics/oidc/java/jetty9-adapter.adoc index ca21ecf29e..9aaf122886 100755 --- a/topics/oidc/java/jetty9-adapter.adoc +++ b/topics/oidc/java/jetty9-adapter.adoc @@ -1,3 +1,4 @@ + [[_jetty9_adapter]] === Jetty 9.x Adapters @@ -5,7 +6,7 @@ Keycloak has a separate adapter for Jetty 9.1.x and Jetty 9.2.x that you will ha You then have to provide some extra configuration in each WAR you deploy to Jetty. Let's go over these steps. -[[_jetty-9_adapter_installation]] +[[_jetty9_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. @@ -57,10 +58,8 @@ This is a Jetty specific config file and you must define a Keycloak specific aut ---- Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. - The format of this config file is describe in the <> section. - WARNING: The Jetty 9.1.x adapter will not be able to find the `keycloak.json` file. You will have to define all adapter settings within the `jetty-web.xml` file as described below. @@ -146,4 +145,4 @@ Here's an example: user ----- +---- \ No newline at end of file diff --git a/topics/oidc/java/tomcat-adapter.adoc b/topics/oidc/java/tomcat-adapter.adoc index d978d4901b..f07a135e09 100755 --- a/topics/oidc/java/tomcat-adapter.adoc +++ b/topics/oidc/java/tomcat-adapter.adoc @@ -45,10 +45,8 @@ This is a Tomcat specific config file and you must define a Keycloak specific Va ---- Next you must create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR. - The format of this config file is describe in the <> section. - Finally you must specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example: @@ -86,4 +84,4 @@ Here's an example: user ----- +---- \ No newline at end of file diff --git a/topics/oidc/oidc-generic.adoc b/topics/oidc/oidc-generic.adoc index 4c71cdade3..04fac12202 100644 --- a/topics/oidc/oidc-generic.adoc +++ b/topics/oidc/oidc-generic.adoc @@ -118,6 +118,7 @@ browser history. This is somewhat mitigated by using short expiration for Access For more details refer to the http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth[Implicit Flow] in the OpenID Connect specification. +[[_resource_owner_password_credentials_flow]] ==== Resource Owner Password Credentials Resource Owner Password Credentials, referred to as Direct Grant in {{book.project.name}}, allows exchanging user credentials for tokens. It's not recommended @@ -171,4 +172,4 @@ There's also a few special redirect URIs: 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. \ No newline at end of file + 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. diff --git a/topics/oidc/oidc-overview.adoc b/topics/oidc/oidc-overview.adoc index bb5fdda906..8436712c35 100644 --- a/topics/oidc/oidc-overview.adoc +++ b/topics/oidc/oidc-overview.adoc @@ -1,6 +1,4 @@ == OpenID Connect This section describes how you can secure applications and services with OpenID Connect using either {{book.project.name}} adapters or generic OpenID Connect -Resource Provider libraries. - -// TODO: Update the cross-reference <<_direct_access_grants,Direct Access Grants>> in the topic /oidc/java/fuse-adapter.adoc +Resource Provider libraries. \ No newline at end of file From c41a00c608c110f5b0a6dd016fc9b2b48cc6eef0 Mon Sep 17 00:00:00 2001 From: --add Date: Thu, 9 Jun 2016 16:01:11 +0530 Subject: [PATCH 4/4] added master-docinfo.xml and metadata.ini --- master-docinfo.xml | 12 ++++++++++++ metadata.ini | 20 ++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100755 master-docinfo.xml create mode 100644 metadata.ini diff --git a/master-docinfo.xml b/master-docinfo.xml new file mode 100755 index 0000000000..819b70d24c --- /dev/null +++ b/master-docinfo.xml @@ -0,0 +1,12 @@ +Red Hat Single Sign-On +7.0.0 +Securing Applications and Services Guide +Securing Applications and Services Guide +7.0.0 + + This guide consist of information for securing applications and services using Red Hat Single Sign-On 7.0.0 + + + Red Hat Customer Content Services + + diff --git a/metadata.ini b/metadata.ini new file mode 100644 index 0000000000..fbb306cc3f --- /dev/null +++ b/metadata.ini @@ -0,0 +1,20 @@ +[source] +language = en-US +type = book +markup = asciidoc + +[metadata] +title = Securing Applications and Services Guide +product = Red Hat Single Sign-On +version = 7.0.0 +edition = +subtitle = +keywords = +abstract = + +[bugs] +reporting_url = +type = +product = +component = Documentation +