fixes
This commit is contained in:
Bill Burke
parent
32938bacca
commit
31c474f37b
11 changed files with 37 additions and 32 deletions
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
|||
</error-page>
|
||||
----
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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 <<fake/../../../../saml/java/jetty-adapter/jetty9_per_war_config.adoc#_saml-jetty9-per-war,Per War Configuration>>
|
||||
|
|
|
|||
|
|
@ -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 <<fake/../../../../saml/java/general-config.adoc#_saml-general-config,General Adapter Config>> 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:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
|||
</web-app>
|
||||
----
|
||||
|
||||
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]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.keycloak</groupId>
|
||||
<artifactId>keycloak-saml-servlet-filter-adapter</artifactId>
|
||||
<version>&project.version;</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.keycloak</groupId>
|
||||
<artifactId>keycloak-saml-servlet-filter-adapter</artifactId>
|
||||
<version>&project.version;</version>
|
||||
</dependency>
|
||||
----
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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 <<<fake/../../../../saml/java/general-config.adoc#_saml-general-config,General Adapter Config>> 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:
|
||||
|
|
|
|||
Loading…
Reference in a new issue