diff --git a/SUMMARY.adoc b/SUMMARY.adoc index be30ca59e8..f254c1fd1e 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -50,12 +50,12 @@ {% if book.community %} ... link:topics/saml/java/tomcat-adapter.adoc[Tomcat SAML adapters] .... link:topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc[Adapter Installation] - .... link:topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc[Required Per WAR Configuration] + .... link:topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc[Per WAR Configuration] ... link:topics/saml/java/jetty-adapter.adoc[Jetty SAML Adapters] .... link:topics/saml/java/jetty-adapter/jetty9_installation.adoc[Jetty 9 Adapter Installation] - .... link:topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc[Jetty 9 Required Per WAR Configuration] + .... link:topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc[Jetty 9 Per WAR Configuration] .... link:topics/saml/java/jetty-adapter/jetty8-installation.adoc[Jetty 8 Adapter Installation] - .... link:topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc[Jetty 8 Required Per WAR Configuration] + .... link:topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc[Jetty 8 Per WAR Configuration] {% endif %} ... link:topics/saml/java/servlet-filter-adapter.adoc[Java Servlet Filter Adapter] ... link:topics/saml/java/idp-registration.adoc[Registering with an IDP] diff --git a/topics/saml/java/assertion-api.adoc b/topics/saml/java/assertion-api.adoc index d2a32a5248..28e6919adb 100644 --- a/topics/saml/java/assertion-api.adoc +++ b/topics/saml/java/assertion-api.adoc @@ -1,7 +1,9 @@ ==== Obtaining Assertion Attributes -After a successful SAML login, your application code may want to obtain attribute values passed with the SAML assertion. `HttpServletRequest.getUserPrincipal` returns a Principal object that you can typecast into a Keycloak specific class called `org.keycloak.adapters.saml.SamlPrincipal`. +After a successful SAML login, your application code may want to obtain attribute values passed with the SAML assertion. +`HttpServletRequest.getUserPrincipal()` returns a `Principal` object that you can typecast into a {{book.project.name}} specific class +called `org.keycloak.adapters.saml.SamlPrincipal`. This object allows you to look at the raw assertion and also has convenience functions to look up attribute values. diff --git a/topics/saml/java/debugging.adoc b/topics/saml/java/debugging.adoc index 5b567045f6..84fb0696a7 100644 --- a/topics/saml/java/debugging.adoc +++ b/topics/saml/java/debugging.adoc @@ -1,6 +1,6 @@ ==== Troubleshooting -The best way to troubleshoot some problems is to turn on debugging for saml in both the client adapter and the keycloak server. +The best way to troubleshoot some problems is to turn on debugging for saml in both the client adapter and the {{book.project.name}} server. To do this turn on debugging int the `org.keycloak.saml` package to `debug` in your log4j or other logging framework. Turning this on allows you to see the SAML requests and response documents being sent to and from the server. diff --git a/topics/saml/java/error_handling.adoc b/topics/saml/java/error_handling.adoc index 82be3d8057..9033571fd2 100644 --- a/topics/saml/java/error_handling.adoc +++ b/topics/saml/java/error_handling.adoc @@ -1,10 +1,10 @@ ==== 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()`. -You can set up an error-page within your `web.xml` file to handle the error however you want. -Keycloak may throw 400, 401, 403, and 500 errors. +{{book.project.name}} has some error handling facilities for servlet based client adapters. +When an error is encountered in authentication, the client adapter will call `HttpServletResponse.sendError()`. +You can set up an `error-page` within your `web.xml` file to handle the error however you want. +The client adapter may throw 400, 401, 403, and 500 errors. [source,xml] @@ -15,7 +15,7 @@ Keycloak may throw 400, 401, 403, and 500 errors. ---- -Keycloak also sets an `HttpServletRequest` attribute that you can retrieve. +The client adapter also sets an `HttpServletRequest` attribute that you can retrieve. The attribute name is `org.keycloak.adapters.spi.AuthenticationError`. Typecast this object to: `org.keycloak.adapters.saml.SamlAuthenticationError`. This class can tell you exactly what happened. diff --git a/topics/saml/java/idp-registration.adoc b/topics/saml/java/idp-registration.adoc index c1cb78d025..630a29ae32 100644 --- a/topics/saml/java/idp-registration.adoc +++ b/topics/saml/java/idp-registration.adoc @@ -2,4 +2,4 @@ ==== Registering with an IDP For each servlet based adapter, the endpoint you register for the assert consumer service url and and single logout service -must be the base url of your servlet application with `/saml` appended to it i.e. https://example.com/contextPath/saml +must be the base url of your servlet application with `/saml` appended to it i.e. `https://example.com/contextPath/saml` diff --git a/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc b/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc index 073cfd8b97..75b5381438 100644 --- a/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc +++ b/topics/saml/java/jetty-adapter/jetty8-per_war_config.adoc @@ -1,5 +1,5 @@ -===== Jetty 8 Required Per WAR Configuration +===== Jetty 8 Per WAR Configuration Enabling Keycloak for your WARs is the same as the Jetty 9.x adapter. -See <<_jetty9_per_war,Required Per WAR Configuration>> +See <> diff --git a/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc b/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc index 415373de79..e27def08a0 100644 --- a/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc +++ b/topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc @@ -1,6 +1,6 @@ [[_saml-jetty9-per-war]] -===== Jetty 9 Required Per WAR Configuration +===== Jetty 9 Per WAR Configuration This section describes how to secure a WAR directly by adding config and editing files within your WAR package. @@ -22,7 +22,7 @@ This is a Jetty specific config file and you must define a Keycloak specific aut ---- Next you must create a `keycloak-saml.xml` 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 <> 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/saml/java/logout.adoc b/topics/saml/java/logout.adoc index e30c08282a..25528af316 100644 --- a/topics/saml/java/logout.adoc +++ b/topics/saml/java/logout.adoc @@ -1,6 +1,6 @@ ==== 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 any url of your web application that has a security constraing and pass in a query parameter GLO, i.e. `http://myapp?GLO=true`. +For Java EE servlet containers, you can call `HttpServletRequest.logout()`. For any other browser application, you can point +the browser at any url of your web application that has a security constraint and pass in a query parameter GLO, i.e. `http://myapp?GLO=true`. This will log you out if you have an SSO session with your browser. diff --git a/topics/saml/java/servlet-filter-adapter.adoc b/topics/saml/java/servlet-filter-adapter.adoc index 434d3b1480..f8c3ab5a02 100644 --- a/topics/saml/java/servlet-filter-adapter.adoc +++ b/topics/saml/java/servlet-filter-adapter.adoc @@ -1,14 +1,15 @@ ==== Java Servlet Filter Adapter -If you want to use SAML 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. +If you want to use SAML 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 {{book.project.name}} has. This adapter works a little differently than the other adapters. You do not define security constraints in web.xml. -Instead you define a filter mapping using the Keycloak 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 instead marks the session id as logged out. -There's just no way of arbitrarily invalidating an http session based on a session id. +NOTE: Backchannel logout works a bit differently than the standard adapters. + Instead of invalidating the http session it instead marks the session id as logged out. + There's just no way of arbitrarily invalidating an http session based on a session id. WARNING: Backchannel logout does not currently work when you have a clustered application that uses the SAML filter. @@ -32,12 +33,13 @@ WARNING: Backchannel logout does not currently work when you have a clustered ap ---- -The Keycloak filter has the same configuration parameters available 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 available as the other adapters except you must +define them as filter init params instead of context params. You can define multiple filter mappings if you have various different secure and unsecure url patterns. WARNING: You must have a filter mapping that covers `/saml`. -This mapping covers all server callbacks. + This mapping covers all server callbacks. When registering SPs with an IDP, you must register `http[s]://hostname/{context-root}/saml` as your Assert Consumer Service URL and Single Logout Service URL. @@ -45,9 +47,9 @@ To use this filter, include this maven artifact in your WAR poms [source,xml] ---- - - org.keycloak - keycloak-saml-servlet-filter-adapter - &project.version; - + + org.keycloak + keycloak-saml-servlet-filter-adapter + &project.version; + ---- diff --git a/topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc b/topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc index 635a1ed19b..9f6ecf19dc 100644 --- a/topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc +++ b/topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc @@ -7,7 +7,8 @@ Each adapter is a separate download on the Keycloak download site. They are also available as a maven artifact. You must unzip the adapter distro into Tomcat's `lib/` directory. -Including adapter's jars within your WEB-INF/lib directory will not work! The Keycloak SAML adapter is implemented as a Valve and valve code must reside in Tomcat's main lib/ directory. +Including adapter's jars within your WEB-INF/lib directory will not work! The Keycloak SAML adapter is implemented as +a Valve and valve code must reside in Tomcat's main lib/ directory. [source] diff --git a/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc b/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc index 8f867af000..7b63cc8068 100644 --- a/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc +++ b/topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc @@ -1,5 +1,5 @@ -===== Required Per WAR Configuration +===== Per WAR Configuration This section describes how to secure a WAR directly by adding config and editing files within your WAR package. @@ -14,7 +14,7 @@ This is a Tomcat specific config file and you must define a Keycloak specific Va ---- Next you must create a `keycloak-saml.xml` 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 <<> 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: