Premise

Organizations use multiple services to achieve their deliverables. These services may be built in-house or maybe standard SAAS applications like Gmail, Salesforce etc. Each service requires users of the organization to sign up and remember separate complicated passwords. Eventually, the representatives of each service have to manually handle login and account settings.

Consider traditional authentication involving an organization, user and services

Organization                   User                                       Services

  • The organization is not happy as, if a user leaves the organization or if his role changes, the admin of the organization has to update the same in all of the services that maintain user information separately.
  • The user is unhappy as he has to remember multiple logins and passwords for accessing different services attached to the same organization.
  • The separate service admins are not happy as apart from the service they provide, they should also handle account creation, password resets of the user, which in their point of view is an overhead. If some authority can confirm to the SAAS applications that the user is valid, then they will be more than happy to provide the services they intend to, rather than maintaining user credentials.

SAML comes in aiming to help companies and services have better authentication processes, without having to manually sign up for every service.

What’s SAML and when should I use it?

SAML, Security Assertion Markup Language, is an open standard data format for exchanging authentication and authorization data between Identity Providers and service providers. It’s a security protocol similar to OpenId, OAuth, Kerberos etc. One of the main use cases SAML addresses is Single-Sign-On (SSO) across services, to offer a simple login experience through a single service.

This method provides great value for both the user and the company.

  • Users don’t have to deal with remembering passwords for various applications, while still providing the services the information they need.
  • Companies can have a process to identify internal users easily, providing them with the needed data.
  • Also, in the case an employee leaves a company, it’s easier to revoke one main account without having to go through and search for multiple accounts for each service this user has had access to.

Parties involved in the authentication

SAML  defines 2 parties in the authentication process:

Service provider – The service to which the user wants to log into

Identity provider – A provider who creates, maintains, and manages identity information for users and provides user authentication to other service providers within a federation, such as with web browser profiles

These 2 providers establish trust by passing XML metadata files from one to the other. This is a one-time configuration step. Afterward, when a user tries to access the service, SAMLRequest and SAMLResponse are XML strings that are sent between the two providers and do the actual authentication.

Spring SAML2.0 WebSSO Authentication

The SAML2.0 WebSSO authentication is pretty well described by the following sequence diagram from Wikipedia.

  1. User hits the Service Provider URL Service provider discovers the IDP to contact for authentication
  2. Service provider redirects to the corresponding IDP
  3. User hits the IDP and identifies the user
  4. IDP redirects to the Login form
  5. Redirect to Service provider Assertion consumer URL (the URL in Service provider that accepts SAML assertion)
  6. SP initiates redirect to target resource
  7. Browser requests for the target resource
  8. Service provider responds with the requested resource

This blog is aimed at setting up SAML2.0 WEB SSO authentication with Spring security SAML (java based) and assumes the user has a basic understanding of SAML concepts.

Frameworks and libraries

We have used the following frameworks and libraries

  • Spring-boot https://spring.io/projects/spring-boot
  • Spring-security https://spring.io/projects/spring-security
  • Spring-security-saml2-core https://projects.spring.io/spring-security-saml/

The project uses  java based configuration of spring security SAML 2.0  

Identity provider

For SAML authentication to work we need an identity provider (IdP). We will use Onelogin as our Identity Provider throughout the application: https://www.onelogin.com

The configuration of Onelogin can be done through here

Project setup dependencies

We use the following gradle dependencies:

 

Configurations overview

SAML Entrypoint – Defining when SAML authentication process kicks in

Login – SAML Login configuration

Processing SAML Response – Configuration for processing SAML assertion

Logout – SAML Logout configuration

Displaying SP metadata – Configuration to display Service provider metadata

SP metadata generation – Configuration to auto-generate Service provider metadata

IDP Metadata – Configuration to obtain IDP metadata form resource URL

XML Parsing – Configuration for SAML XML parsing

SAML Binding – Configuration for defining binding parameters for IDP and SP exchange

Context Provider – Configuration for understanding HttpRequest/HttpResponse and delegating handlers to SP/IDP related classes

Web SSO profile – Configurations to handle response for SP and IDP initiated SSO

Spring Security – Authentication Provider configuration

HttpSecurity – Http Configurations

Other Configurations – Other security configurations

Let’s create the main security configuration class, SamlSecurityConfig which will be responsible for all SAML bean declarations and configuration.

SAML Entrypoint

Let’s build the spring SAML security step by step from this point.

Users will try to access a SAML protected resource and fail. This failure will be handled by Spring security ExceptionTranslationFilter implementation which then will hand over to saml authentication entry point thus starting the saml authentication from your app (Service Provider or SP) to the identity provider (IdP).

Add the following beans to configure entry point:

 

The WebSSOProfileOptions bean allows us to setup parameters of the AuthNRequest. The AuthNRequest is the request sent from SP to IdP for asking user authentication. We can also force authentication from IdP each time the SP sends a new AuthNRequest:

Let’s start configuring HttpSecurity to declare which AuthenticationEntryPoint to call when an authentication exception is triggered:

Let’s add another bean and start initializing the Saml security filter chain i.e the set of all SAML filters which can be involved in SAML operations.

Displaying SP metadata

Spring security SAML will generate SP metadata according to our SAML configuration.

MetadataDisplayFilter will allow users to download the SP metadata from a specific url.

This metadata will be provided/uploaded to the IDP.

 

The filter is bound to the /saml/metadata url pattern and can be disabled for production environment if we do not want to expose it.

Login

To directly trigger samlEntryPoint, let us add specific login url (/saml/login)  to the filter chain that will act as the entry point for SAML requests.

 

After user logs in, the IDP redirects the SAML response to a configured URL (e.g. «/saml/SSO») called the SAML processing endpoint (often called Assertion Consumer URL) in the SP.  This redirection triggers the following filter bean class: SamlWebSSOProcessingFilter. This filter processes arriving SAML messages by delegating to the WebSSOProfile. After the SAMLAuthenticationToken is obtained, authentication providers are asked to authenticate it. Let us configure the filter and add it to the filter chain to handle the authentication response.


Processing SAML Response

 

and plug the filter into the «/saml/SSO» url.

 

 

Logout

Logging out can be a two step process depending on where we want the user’s session invalidated
Logout

Global logout

Global logout is a 2 step process, where we clear our SP Spring security context and invalidate any SP cookie so that user is no more authenticated on behalf of our application (let’s call it Spring Logout) and also terminate the sessions of all the SPs with the help of the IDP (SingleLogout)

Spring Logout only

SingleLogout is sometimes not preferred as it terminates all the sessions from all SPs (i.e multiple apps) previously authenticated by the IdP. However, if we want to only logout (Spring Logout) from our app, that is also possible through configuration.

Global logout can be configured with these beans:

 

Now, let us map the logout url (/saml/logout/**) to proper filter and add it to the filter chain.

 

SAMLLogoutProcessingFilter: Filter processes arriving SAML Single Logout messages by delegating to the LogoutProfile.

SAMLLogoutFilter : Upon invocation of the filter URL it is determined whether global (termination of all participating sessions) or local (/saml/logout?local=true) (termination of only session running within Spring Security) logout is requested based on request attribute. In case global logout is in question a LogoutRequest is sent to the IDP.

HttpSecurity

Our HttpSecurity looks like this now:

we should configure the following :

 

  • Disable csrf : IDP and SP belong to different domains, and since IdP will redirect to our SP, we should disable csrf protection as the IdP has no way to know which csrf token it should provide.
  • Add the saml filter chain that has been built so far.
  • Permit certain URL patterns (/error, /saml/**). These patterns will not need authentication and will allow the users to access the resources without a need to login.

 

SP Metadata generation

The service provider metadata can either be provided as an XML file into the application or generated. Metadata is mandatory to allow IdP know on which SP endpoint redirect to. We can configure MetadataGenerator bean to enable Spring SAML to generate the SP metadata

APP_BASE_URL –This is the application’s base url after deployment, it varies according to the environment the application is deployed in.
APP_ENTITY_ID – This is the name of the application/ audience field in the application set-up for the IDP

We have disabled IdPDiscovery in ExtendedMetadata Bean as this example is targeted for single SAML IDP.  We will cover the keymanager() configuration in this section.

Let us now add the metadata generator filter to the HttpSecurity:

 

KeyManager

Metadata generation requires a keyManager

keyManager is responsible to encrypt the saml assertion sent to IdP.

A self-signed key and keystore can be generated with the JRE keytool command:

 

XML parsing

SAML being XML based protocol, XML parser pools should be initialized to read metadata and assertions that are in XML format.

SAML Binding configuration

SAML Binding that we use depends on the IDP specifications. We use POST and Redirect bindings with respect to our configuration in Onelogin and initialize SAMLProcessorImpl accordingly.

Other configurations

We initialize HTTPClient with multithreaded connection manager, initialize saml logger and more importantly SAML BootStrap which is responsible for the initialization of SAML library and is automatically called as part of Spring initialization.

 

Context provider

SAMLContextProviderImpl is responsible for parsing HttpRequest/Response and determining which local entity (IDP/SP) is responsible for its handling.

This configuration is for the application that is not behind a Reverse Proxy.

 

Alternatively, SAMLContextProviderLB can be used, which is a Context provider that overrides request attributes with values of the load-balancer or reverse-proxy in front of the local application. The settings help to provide correct redirect URls and verify destination URLs during SAML processing.

Web SSO profile

We need beans for configuring WebSSO profile and logout. We use default spring saml provided implementation

WebSSOProfileConsumer Class is able to process Response objects returned from the IDP after SP initialized SSO or unsolicited response from IDP.

WebSSOProfile Class implements WebSSO profile and offers capabilities for SP initialized SSO and process Response coming from IDP or IDP initialized SSO. HTTP-POST and HTTP-Redirect bindings are supported.

SingleLogoutProfileImplImplementation of the SAML 2.0 Single Logout profile.

IdP metadata

The IDP metadata provides the means of contacting it through metadata.

It can either be downloaded from the IDP (Onelogin) , or if we provide the resource URL from where the metadata can be downloaded, the Spring SAML configuration does it for us.

 


ONELOGIN_METADATA_URL.concat(getAppId()) –
The IDPs metadata URL followed by the unique app Id for the application set in the IDP

Spring security

Now let’s add some classic Spring Security configuration: – AuthenticationProvider. The authentication provider is capable of verifying the validity of a SAMLAuthenticationToken and in case the token is valid to create an authenticated UsernamePasswordAuthenticationToken.

AuthenticationProvider

 

Conclusion

We have completed SAML configuration in Java and the web urls in the application now are authenticated through SAML.

You can find sample project here https://github.com/lakshmiabinaya/saml-java

In the next section of the blog, we will address two problems

  • How to combine SAML with other authentication mechanisms
  • How to authenticate the REST APIs in the application ie what if your application uses SAML for web pages and also another authentication mechanism for its REST APIs