[CONF] Apache CXF Documentation > SAML Web SSO

[confluence]

SAML Web SSO Page edited by Sergey Beryozkin Changes (7) ... SP Security Filter protects the application endpoints by checking that a valid SSO security context is available. If it is then the filter lets the request to continue, if not then it redirects the current user to IDP. When a filter redirects a user to IDP, it creates a SAML Authentication Request, see [this page|http://en.wikipedia.org/wiki/SAML_2.0#Web_Browser_SSO_Profile] for the example and appends it to the IDP Service URI or gets it POSTed to IDP. Additionally, a RelayState token pointing to the state of the current user request is also included which IDP will return to Request Assertion Consumer Service (RACS) after the user has authenticated. CXF offers two SP Security filters, one for redirecting the user back to IDP via GET and another one - via POST. ... 3. Reference to SSO State Provider. The following optional property affecting the created SAML request may also be set: * String issuerId - it defaults to the base URI of the application endpoint protected by this filter, for example, "http://localhost:8080/services/app1". The IDP address is where filters will redirect users to and the RACS address is where users will be redirected by IDP to. RACS will set up a security context and redirect the user back to the original application address by using the RelayState token which is included by the filters when users are initially redirected to IDP. h2. POST Binding Filter ... {code} Note that the POST binding filter has the same base properties as org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter has but also Note that the POST binding filter has the same 3 required properties as org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter has but also sets a "useDeflateEncoding" property for getting a SAML request deflated. Some IDPs might not be able to process deflated SAML requests with POST binding redirects thus the compression may be optionally disabled. What is actually different in this case from the GET-based redirect is that the filter prepares an instance of [SAMLRequestInfo|http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/SamlRequestInfo.java] which is subsequently bound to an XHTML view via a JSP filter. The view will typically have a _javascript_ handler which will actually redirect the user to IDP when it is loaded into the browser. The data to view binding is facilitated by org.apache.cxf.jaxrs.provider.RequestDispatcherProvider, please see [this page|http://cxf.apache.org/docs/jax-rs-redirection.html#JAX-RSRedirection-WithRequestDispatcherProvider] for more information. One may prefer using the POST binding filter in cases where having SAML request to IDP encoded as a URI parameter prohibited. Here is a typical JSP handler for binding org.apache.cxf.rs.security.saml.sso.SAMLRequestInfo to the view: ... {code} h2. Signing SAML Authentication Requests The filters may optionally sign SAML requests, the following configuration properties can be set-up: * boolean signRequest - Whether to sign the AuthnRequest or not. The default is false. * String signatureUsername - The keystore alias to use to sign the AuthnRequest. * Crypto signatureCrypto - A WSS4J Crypto object if the SAML AuthnRequest is to be signed. * String signaturePropertiesFile - This points to a properties file that can be used to load a Crypto instance if the SAML AuthnRequest is to be signed. * CallbackHandler callbackHandler - A CallbackHandler object to retrieve the private key password used to sign the request. * String callbackHandlerClass - A class name that is loaded for use as the CallbackHandler object. Either the "signatureCrypto" or "signaturePropertiesFile" properties must be set if "signRequest" is set to true. Similarly, either "callbackHandler" or "callbackHandlerClass" must be configured. h2. Filters and State Management The following properties affect the way filters manage the SSO state: * [SPStateManager|http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/state/SPStateManager.java] stateProvider * long stateTimeToLive - default is 2 minutes (in milliseconds). * String webAppDomain. * boolean addWebAppContext - default is true. * boolean boolean addEndpointAddressToContext - default is false. The 'stateProvider' refers to a custom [SPStateManager|http://svn.apache.org/repos/asf/cxf/trunk/rt/rs/security/sso/saml/src/main/java/org/apache/cxf/rs/security/saml/sso/state/SPStateManager.java] implementation and is used for filters and RACS coordinating with the filters persisting the current user request state, RACS validating it and persisting the current security context state and filters getting the information about the context. Filters and RACS use a 'RelayState' token to work with the current request state. RACS persists the security context and the filters retrieve and validate it using the cookie which RACS also sets to point to this security context. Note that a 'stateTimeToLive' property can be used to control how long the current security context can be valid for. Both filters and RACS use opaque cookies to refer to the original request and security context state and 'webAppDomain', 'addWebAppContext' and 'addEndpointAddressToContext' affect the way these cookies can be shared between multiple SP custom applications. For example, here is a typical Set Cookie request issued by a web application to the browser: {code:java} Set-Cookie: value; Domain=mydomain; Path=/accounts; Expires=Wed, 13-Jan-2021 22:23:01 GMT; {code} By default, CXF will get a Cookie 'Path' property set to something like "/services", where 'services' is the actual name of the war archive. The 'addEndpointAddressToContext' property can be further restrict this path to something like "/services/app1", "/services/app2", where "/app1" and "/app2" are jaxrs:endpoint addresses, this can be handy for testing, with every jaxrs:endpoint within a single war having its own security context. If the custom SP application is 'spread' across multiple containers with different application context names, then the 'addWebAppContext' can be set to 'false' leading to Cookie 'Path' parameters set to '/' and the 'webAppDomain' property set to some shared value. Note that the stateTimeToLive property affects a Cookie 'Expires' property but also used by filters and RACS to enforce that the internal state has not expired. h1. Request Assertion Security Service ... Full Content JAX-RS: SAML Web SSO Introduction Typical Flow Maven dependencies Identity Provider Service Provider Security Filter Redirect Binding Filter POST Binding Filter Signing SAML Authentication Requests Filters and State Management Request Assertion Security Service SSO State Provider Introduction SSO is about a user having to sign in only once when interacting with a custom web application which may offer of a number of individual endpoints. CXF 2.6.1 introduces a comprehensive service provider (SP) support for the SAML Web SSO profile. This page also offers a good overview of the profile. HTTP Redirect(via GET) and POST bindings are supported. The module has been tested against many IDP providers and is easily configurable. The following components are required to get SSO supported: Identity Provider (IDP) supporting SAML SSO Request Assertion Consumer Service (RACS) Service Provider Security Filter SSO State Provider The following sections will describe these components in more details Typical Flow Typically, the following flow represents the way SAML SSO is enforced: 1. User accesses a custom application for the first time 2. Service Provider Security Filter checks if the security context is available and redirects the user to IDP with a SAML SSO request 3. IDP challenges the user with the authentication dialog and redirects the user to Request Assertion Consumer Service (RACS) after the user has authenticated 4. RACS validates the response from IDP, establishes a security context and redirects the user to the original application endpoint 5. Service Provider Security Filter enforces that a valid security context is available and lets the user access the custom application. Maven dependencies <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-rs-security-sso-saml</artifactId> <version>2.6.1</version> </dependency> Identity Provider Identity Provider (IDP) is the service which accepts the redirect requests from application security filters, authenticates users and redirects them back to Request Assertion Security Service. CXF does not offer its own IDP SAML Web SSO implementation but might provide it in the future as part of the Fediz project. However, CXF has been tested against a number of popular IDP implementations which support SAML SSO and thus should be interoperable with whatever IDP is being used in the specific production environment. The interoperability tests have shown that some IDPs may process SAML request and produce SAML response data the way which may not be exactly specification-compliant and thus CXF Request Assertion Consumer Service (RACS) and Service Provider Security Filter implementations have a number of configuration properties for adjusting the way SAML requests to IDP are prepared and SAML responses from IDP are processed. Service Provider Security Filter SP Security Filter protects the application endpoints by checking that a valid SSO security context is available. If it is then the filter lets the request to continue, if not then it redirects the current user to IDP. When a filter redirects a user to IDP, it creates a SAML Authentication Request, see this page for the example and appends it to the IDP Service URI or gets it POSTed to IDP. Additionally, a RelayState token pointing to the state of the current user request is also included which IDP will return to Request Assertion Consumer Service (RACS) after the user has authenticated. CXF offers two SP Security filters, one for redirecting the user back to IDP via GET and another one - via POST. Redirect Binding Filter Redirect Binding Filter is implemented by org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter. Here is an example of a typical filter protecting a custom JAX-RS endpoint: <bean id="serviceBean" class="org.apache.cxf.samlp.sso.BookStore"/> <jaxrs:server address="/app1"> <jaxrs:serviceBeans> <ref bean="serviceBean"/> </jaxrs:serviceBeans> <jaxrs:providers> <ref bean="redirectGetFilter"/> </jaxrs:providers> </jaxrs:server> <bean id="redirectGetFilter" class="org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter"> <property name="idpServiceAddress" value="https://localhost:9443/idp"/> <!-- both relative and absolute URIs are supported --> <property name="assertionConsumerServiceAddress" value="/racs/sso"/> <property name="stateProvider" ref="stateManager"/> </bean> <bean id="stateManager" class="org.apache.cxf.rs.security.saml.sso.state.EHCacheSPStateManager"> <constructor-arg ref="cxf"/> </bean> Note that at the very minimum the filter needs to have 3 properties set-up: 1. IDP service address 2. RACS address - it can be absolute or relative if RACS is collocated (shares the same web application context) with the application endpoint. 3. Reference to SSO State Provider. The following optional property affecting the created SAML request may also be set: String issuerId - it defaults to the base URI of the application endpoint protected by this filter, for example, "http://localhost:8080/services/app1". The IDP address is where filters will redirect users to and the RACS address is where users will be redirected by IDP to. RACS will set up a security context and redirect the user back to the original application address by using the RelayState token which is included by the filters when users are initially redirected to IDP. POST Binding Filter POST Binding Filter is implemented by org.apache.cxf.rs.security.saml.sso.SamlPostBindingFilter. Here is an example of a typical filter protecting a custom JAX-RS endpoint. <bean id="serviceBean" class="org.apache.cxf.samlp.sso.BookStore"/> <jaxrs:server address="/app2"> <jaxrs:serviceBeans> <ref bean="serviceBean"/> </jaxrs:serviceBeans> <jaxrs:providers> <ref bean="ssoRedirectPOST"/> <ref bean="samlRequestFormCreator"/> </jaxrs:providers> </jaxrs:server> <bean id="ssoRedirectPOST" class="org.apache.cxf.rs.security.saml.sso.SamlPostBindingFilter"> <property name="idpServiceAddress" value="https://localhost:9443/idp"/> <property name="assertionConsumerServiceAddress" value="/racs/sso"/> <property name="stateProvider" ref="stateManager"/> <property name="useDeflateEncoding" value="true"/> </bean <bean id="samlRequestFormCreator" class="org.apache.cxf.jaxrs.provider.RequestDispatcherProvider"> <property name="dispatcherName" value="jsp"/> <property name="useClassNames" value="true"/> </bean> <bean id="stateManager" class="org.apache.cxf.rs.security.saml.sso.state.EHCacheSPStateManager"> <constructor-arg ref="cxf"/> </bean> Note that the POST binding filter has the same 3 required properties as org.apache.cxf.rs.security.saml.sso.SamlRedirectBindingFilter has but also sets a "useDeflateEncoding" property for getting a SAML request deflated. Some IDPs might not be able to process deflated SAML requests with POST binding redirects thus the compression may be optionally disabled. What is actually different in this case from the GET-based redirect is that the filter prepares an instance of SAMLRequestInfo which is subsequently bound to an XHTML view via a JSP filter. The view will typically have a _javascript_ handler which will actually redirect the user to IDP when it is loaded into the browser. The data to view binding is facilitated by org.apache.cxf.jaxrs.provider.RequestDispatcherProvider, please see this page for more information. One may prefer using the POST binding filter in cases where having SAML request to IDP encoded as a URI parameter prohibited. Here is a typical JSP handler for binding org.apache.cxf.rs.security.saml.sso.SAMLRequestInfo to the view: <%@ page import="javax.servlet.http.HttpServletRequest,org.apache.cxf.rs.security.saml.sso.SamlRequestInfo" %> <% SamlRequestInfo data = "" class="code-quote">"samlrequestinfo"); %> <html xmlns="http://www.w3.org/1999/xhtml"> <body _onLoad_="document.forms[0].submit();"> <form action="" class="code-quote">"<%= data.getIdpServiceAddress() %>" method="POST"> <div> <input type="hidden" name="SAMLRequest" value="<%= data.getSamlRequest() %>"/> <input type="hidden" name="RelayState" value="<%= data.getRelayState() %>"/> </div> <div> <input type="submit" value="Continue"/> </div> </form> </body> </html> Signing SAML Authentication Requests The filters may optionally sign SAML requests, the following configuration properties can be set-up: boolean signRequest - Whether to sign the AuthnRequest or not. The default is false. String signatureUsername - The keystore alias to use to sign the AuthnRequest. Crypto signatureCrypto - A WSS4J Crypto object if the SAML AuthnRequest is to be signed. String signaturePropertiesFile - This points to a properties file that can be used to load a Crypto instance if the SAML AuthnRequest is to be signed. CallbackHandler callbackHandler - A CallbackHandler object to retrieve the private key password used to sign the request. String callbackHandlerClass - A class name that is loaded for use as the CallbackHandler object. Either the "signatureCrypto" or "signaturePropertiesFile" properties must be set if "signRequest" is set to true. Similarly, either "callbackHandler" or "callbackHandlerClass" must be configured. Filters and State Management The following properties affect the way filters manage the SSO state: SPStateManager stateProvider long stateTimeToLive - default is 2 minutes (in milliseconds). String webAppDomain. boolean addWebAppContext - default is true. boolean boolean addEndpointAddressToContext - default is false. The 'stateProvider' refers to a custom SPStateManager implementation and is used for filters and RACS coordinating with the filters persisting the current user request state, RACS validating it and persisting the current security context state and filters getting the information about the context. Filters and RACS use a 'RelayState' token to work with the current request state. RACS persists the security context and the filters retrieve and validate it using the cookie which RACS also sets to point to this security context. Note that a 'stateTimeToLive' property can be used to control how long the current security context can be valid for. Both filters and RACS use opaque cookies to refer to the original request and security context state and 'webAppDomain', 'addWebAppContext' and 'addEndpointAddressToContext' affect the way these cookies can be shared between multiple SP custom applications. For example, here is a typical Set Cookie request issued by a web application to the browser: Set-Cookie: value; Domain=mydomain; Path=/accounts; Expires=Wed, 13-Jan-2021 22:23:01 GMT; By default, CXF will get a Cookie 'Path' property set to something like "/services", where 'services' is the actual name of the war archive. The 'addEndpointAddressToContext' property can be further restrict this path to something like "/services/app1", "/services/app2", where "/app1" and "/app2" are jaxrs:endpoint addresses, this can be handy for testing, with every jaxrs:endpoint within a single war having its own security context. If the custom SP application is 'spread' across multiple containers with different application context names, then the 'addWebAppContext' can be set to 'false' leading to Cookie 'Path' parameters set to '/' and the 'webAppDomain' property set to some shared value. Note that the stateTimeToLive property affects a Cookie 'Expires' property but also used by filters and RACS to enforce that the internal state has not expired. Request Assertion Security Service SSO State Provider Change Notification Preferences View Online | View Changes | Add Comment