SAML 2.0 SSO certificate rollover

At Paddy Power Betfair (PPB) we build software not only for us and our direct customers but also for several partners. We’re responsible for empowering them to run their betting businesses without having to build and run a whole infrastructure from scratch.

Some of the web applications we build for our external partners run within our infrastructure but are meant to be used by both, us and them.

Since we use multiple web applications on a daily basis, we love to use applications with Single Sign-On (SSO). SSO provides us with the following benefits:

  • Users own a single set of credentials for all of the apps
  • Users will not need to provide those credentials dozens of times per day.

For these reasons, our apps use the SAML 2.0 standard for exchanging authentication and authorisation data between them, acting as Service Providers (SPs), and several Identity Providers (IdPs).

Figure 1 illustrates the trust network between a PPB application (Service Provider) and multiple Identity Providers both, internal and external.

SAML 2.0 trust relationships of a PPB Web APP
Figure 1 – SAML 2.0 trust relationships of a PPB Web APP

SAML quick review

If you’re not familiar with the SAML 2.0 standard, let’s have a quick high-level review.

SAML stands for Security Assertion Markup Language. It is an XML-based open standard used to exchange authentication and authorisation data between security domains, in particular, between an Identity Provider (IdP) and a Service Provider (SP).

The data is transmitted in the form of security assertions containing information about a principal (typically an application user). Besides assertions, the standard defines also:

  • XML-based protocols and their respective messages
  • Protocol message bindings
    • To specify how the messages can be sent through HTTP and SOAP
  • Profiles
    • Combining assertions, protocols and bindings to enable specific use cases

The most commonly used ones are the Web Browser SSO and Single Logout profiles. The SSO profile is illustrated in Figure 2.

Web Browser SSO with HTTP Redirect binding
Figure 2 – Web Browser SSO with HTTP Redirect binding
  1. The user’s browser accesses the SP which is running the application.
    • Depending on the implementation and use case, the user may go directly to the IdP instead (Step 3)
  2. The application discovers which IdP should be used to authenticate the user and redirects the browser to the respective SSO Service
    • This step may require the user to provide some info (g. email or select the IdP from a list)
  3. The browser redirects the user to the IdP SSO Service. The content of the AuthnRequest is validated, including its signature (if applicable)
    • If the user has an IdP valid session then Step 4 starts automatically
    • Otherwise, the user must be authenticate itself
  4. The IdP responds with an XHTML form which brings a SAML Response with one or multiple assertions regarding the user
  5. The browser automatically submits the form to the Service Provider’s Assertion Consumer Service
  6. The Service Provider decrypts the SAML Response (if applicable), checks the message signature and user authorization using the assertion’s attributes
    • Upon success, it creates the user session and starts providing the service

SAML security

As described above, the SSO process optionally requires message encryption/decryption and signature validation. Enforcing these requirements is essential for us, mainly because we don’t control the entire infrastructure as some of our SAML parties are external.

To ensure message authenticity and confidentiality, the SAML standard makes use of asymmetric cryptography, requiring each party to have a pair of keys, public and private.

The public key is usually transmitted to other parties using X.509 certificates and, to ease and automate this process, the standard defines a metadata document which describes a SAML deployment (including relevant endpoints and X.509 certificate).

The problem: keys and certificate rollover

Recently the certificate of one of our applications has expired. So, we needed to update our certificate with a new key pair, propagate the new certificate to our external partners, giving them some time to update their configurations without the risk of having a service downtime.

This application uses the Spring Security SAML library which implements the SAML 2.0 standard. Unfortunately, the current stable version does not support key rollover processes by allowing the applications to handle two key pairs and certificates at the same time, like other libraries support (e.g. SimpleSAMLphp, OneLogin’s SAML PHP Toolkit).

As far as we could find, the next major version of Spring Security SAML will support this feature. However, that version is still unstable and we cannot afford to use it on production.

Since we have partners all around the globe, setting up a coordinated release with all of them along with a small service downtime was not only risky but also unfeasible due to the time zone differences.

The solution: Spring Security SAML Keys Rollover

Our solution was to develop an extension to the Spring Security SAML library so that it can support handling multiple certificates and key pairs.

With this extension, we were able to perform a first release supporting two certificates and key pairs, propagate the new certificate to our partners and give them time to update their Identity Provider configurations. Their IdPs must trust in the new certificate and start using the new public key to encrypt the SAML messages they sent to our application. Upon confirmation from all of them, we could then make a new release to remove the old certificate which was about to expire, concluding the rollover process.

Since at PPB we love open source, we published this extension on:

On GitHub, you can find a detailed guide to follow in case you need to rollover your certificate. We’ll also be happy to accept your contributions.

SAML 2.0 SSO certificate rollover

2 thoughts on “SAML 2.0 SSO certificate rollover

  1. Saurabh says:

    May I know which major version of Spring Security SAML will support this feature? I tried to search but not able to find out. Thank you in advance for your help.


    1. Samuel Campos says:

      Last time it was tested, it was supporting the version 1.0.3.RELEASE. We haven’t tested this with the latest (1.0.10.RELEASE) but, given it is still the same minor version, I think it will work.
      Please let us know if you find any issues with it.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s