JarCasting
JarCasting JarCasting

Spring Security SAML Keys Rollover

An extension of Spring Security SAML Library 1.0.x to add support for keys rollover

License

License
Categories

Categories

Security KeY Data Data Formats Formal Verification
GroupId

GroupId

com.paddypowerbetfair.springframework
ArtifactId

ArtifactId

spring-security-saml-keys-rollover
Last Version

Last Version

1.0.2
Release Date

Release Date
Type

Type

jar
Description

Description

Spring Security SAML Keys Rollover
An extension of Spring Security SAML Library 1.0.x to add support for keys rollover
Project URL

Project URL

https://github.com/PaddyPowerBetfair/SpringSecuritySAMLKeysRollover
Source Code Management

Source Code Management

https://github.com/PaddyPowerBetfair/SpringSecuritySAMLKeysRollover

Download spring-security-saml-keys-rollover

Filename Size
spring-security-saml-keys-rollover-1.0.2.pom
spring-security-saml-keys-rollover-1.0.2.jar 7 KB
spring-security-saml-keys-rollover-1.0.2-sources.jar 6 KB
spring-security-saml-keys-rollover-1.0.2-javadoc.jar 36 KB
Browse

How to add to project

<!-- https://jarcasting.com/artifacts/com.paddypowerbetfair.springframework/spring-security-saml-keys-rollover/ -->
<dependency>
    <groupId>com.paddypowerbetfair.springframework</groupId>
    <artifactId>spring-security-saml-keys-rollover</artifactId>
    <version>1.0.2</version>
</dependency>
// https://jarcasting.com/artifacts/com.paddypowerbetfair.springframework/spring-security-saml-keys-rollover/
implementation 'com.paddypowerbetfair.springframework:spring-security-saml-keys-rollover:1.0.2'
// https://jarcasting.com/artifacts/com.paddypowerbetfair.springframework/spring-security-saml-keys-rollover/
implementation ("com.paddypowerbetfair.springframework:spring-security-saml-keys-rollover:1.0.2")
'com.paddypowerbetfair.springframework:spring-security-saml-keys-rollover:jar:1.0.2'
<dependency org="com.paddypowerbetfair.springframework" name="spring-security-saml-keys-rollover" rev="1.0.2">
  <artifact name="spring-security-saml-keys-rollover" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.paddypowerbetfair.springframework', module='spring-security-saml-keys-rollover', version='1.0.2')
)
libraryDependencies += "com.paddypowerbetfair.springframework" % "spring-security-saml-keys-rollover" % "1.0.2"
[com.paddypowerbetfair.springframework/spring-security-saml-keys-rollover "1.0.2"]

Dependencies

compile (3)

Group / Artifact Type Version
javax.servlet : servlet-api jar 2.5
org.springframework.security.extensions : spring-security-saml2-core jar 1.0.3.RELEASE
org.projectlombok : lombok jar 1.18.2

test (2)

Group / Artifact Type Version
org.spockframework : spock-core jar 0.7-groovy-2.0
org.slf4j : slf4j-simple jar 1.7.25

Project Modules

There are no modules declared in this project.

Spring Security SAML Keys Rollover

Maven Central

An extension of Spring Security SAML Library 1.0.x to add support for keys rollover.

SAML 2.0 uses asymmetric cryptography to sign and encrypt messages that are sent between Service Providers (SPs) and Identity Providers (IdPs). Each SAML entity has, at least a key pair along with an X.509 certificate to be distributed using the standard SAML XML metadata. When the certificates are about to expire, or due to security reasons, a key rollover must occur so that there's no service interruption.

We've written a blog post explaining this problem in detail and why we needed this library extension.

The general process of rolling over a key on a Service Provider without any service interruption is as follows:

  1. Create a new key pair for signing and/or encryption together with the respective X.509 certificate
  2. Configure your SP to support the new key pair
    1. Add a new KeyDescriptor to your SAML metadata
    2. Support decrypting SAML messages using your new key
  3. Send your metadata (or just the X.509 certificate) to the IdP(s). They must:
    1. Switch the encryption certificate to the new one
    2. Trust in your new signing certificate, without stop trusting in the old one
  4. Wait for the IdP(s) to update its configurations
    1. Do not start to use the new key for signing your messages until the IdP(s) confirm they are supporting your new certificate
  5. Configure your SP to start using the new key for signing messages
    1. The old keys may be completely removed
    2. The IdP(s) can now untrust your old signing certificate

Supporting local key rollover in your project for both signing and encryption - a step-by-step guide

1. Add the maven dependency

This dependency extends some Spring Security SAML classes to support the Key Rollover feature.

<dependency>
    <groupId>com.paddypowerbetfair</groupId>
    <artifactId>spring-security-saml-keys-rollover</artifactId>
    <version>1.0.3</version>
</dependency>

2. Generate a new key pair and respective self-signed certificate

Please make sure if you want to use self-signed certificates for your deployment. If you don't, you should import a CA-signed certificate to your KeyStore instead.

keytool -genkey -alias <new_key_alias> -validity <number_of_day> -keyalg RSA -keystore <keystore_file>.jks

3. Update your keyManager configuration to include the new private key password

<bean id="keyManager" class="org.springframework.security.saml.key.JKSKeyManager">
    <constructor-arg value="classpath:<keystore_file>.jks"/>
    <constructor-arg type="java.lang.String" value="keystore_pass"/>
    <constructor-arg>
        <map>
            <entry key="old_key_alias" value="old_key_pass"/>
            <entry key="new_key_alias" value="new_key_pass"/>
        </map>
    </constructor-arg>
    <constructor-arg type="java.lang.String" value="old_key_alias"/>
</bean>

4. Update your metadataGeneratorFilter configuration to use a MetadataGeneratorKeysRollover together with an extendedMetatada attribute using a ExtendedMetadataKeysRollover bean

By updating your metadataGeneratorFilter configuration, your XML metadata will include both (current and new) the certificates so that IdP(s) can update their configurations.

<bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
    <constructor-arg>
        <bean class="com.paddypowerbetfair.springframework.keys.rollover.MetadataGeneratorKeysRollover">
            <!-- Your usual content here -->

            <property name="extendedMetadata">
                <bean class="com.paddypowerbetfair.springframework.keys.rollover.ExtendedMetadataKeysRollover">
                    <property name="rolloverKeys">
                        <map>
                            <entry key="ENCRYPTION" value="new_key_alias"/>
                            <entry key="SIGNING" value="new_key_alias"/>
                        </map>
                    </property>
                </bean>
            </property>
        </bean>
    </constructor-arg>
</bean>

5. Update your SAML contextProvider bean to use the SAMLContextProviderKeysRolloverImpl class

By using the SAMLContextProviderKeysRolloverImpl the SAML message decrypter will be able to decrypt messages using any of your encryption private keys. With this, your SP will be able to decrypt messages coming from IdPs who have not yet updated their configurations along with the messages from the IdPs who have updated.

<bean id="contextProvider" class="com.paddypowerbetfair.springframework.keys.rollover.SAMLContextProviderKeysRolloverImpl"/>

How can I contribute?

Please see CONTRIBUTING.md.

What licence is this released under?

This is released under a modified version of the BSD licence. Please see LICENSE.

com.paddypowerbetfair.springframework

Paddy Power Betfair

opensource at paddypowerbetfair dot com

Versions

Version
1.0.2