1. Introduction

1.1 What this manual covers

This manual describes Spring Security SAML Extension component, its uses, installation, configuration, design and integration possibilities.

1.2 When to use Spring Security SAML Extension

The extension enables both new and existing applications to act as a Service Provider in federations based on Web Single Sign-On and Single Logout profiles of SAML 2.0 protocol. The extension allows seamless combination of SAML 2.0 and other authentication and federation mechanisms in a single application. All products supporting SAML 2.0 in Identity Provider mode (e.g. ADFS, Okta, Shibboleth, OpenAM, Efecte EIM or Ping Federate) can be used with the extension.

The extension can also be used in applications which are not primarily secured using Spring Security. It can be adapted for both single and multi-tenant environments.

The extension can be either embedded inside your application and work along other authentication or single sign-on mechanisms, or it can be deployed separately and convey authentication information to applications using a custom mechanism.

The extension is probably the most complete open-source SAML 2.0 SP implementation with the widest feature-set and configuration possibilities. Other Java open-source alternatives are e.g. native SAML service providers integrating with IIS or Apache from Shibboleth (SAML processing is done on the web server and not on the application level) or OpenAM Fedlet.

1.3 Features and supported profiles

Current implementation should be conformant to SAML SP Lite and SAML eGovernment profile. The following profiles, bindings and features are supported as part of the product:

  • Web single sign-on profile

  • Web single sign-on holder-of-key profile

  • IDP and SP initialized single sign-on

  • Single logout profile

  • Enhanced client/proxy profile

  • Identity provider discovery profile and IDP selection

  • Metadata interoperability and PKIX trust management

  • Automatic service provider metadata generation

  • Metadata loading from files, URLs, file-backed URLs

  • Processing and automatic reloading of metadata with many identity providers

  • Support for authentication contexts

  • Logging for authentication events

  • Customization of both SP and IDP metadata

  • Processing of SAML attributes and user data using UserDetails interface

  • Support for HTTP-POST, HTTP-Redirect, SOAP, PAOS and Artifact bindings

  • Easy integration with applications using Spring Security

  • Sample application with an user interface for quick configuration

You can use the following supported standards as a reference:

SAML 2.0 basic profiles

  • https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf

  • https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf

  • https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf

  • https://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf

  • https://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf

  • https://docs.oasis-open.org/security/saml/v2.0/saml-conformance-2.0-os.pdf

SAML 2.0 additional profiles

  • https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf

  • https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf

  • https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml2-holder-of-key.pdf

  • https://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-iop.pdf

eGovernment profile

  • https://kantarainitiative.org/confluence/download/attachments/42139782/kantara-egov-saml2-profile-2.0.pdf

1.4 Requirements

Spring Security SAML Extension requires as a minimum Java 1.6 and is known to work with most Java containers and application servers. It can also be used with PaaS providers, such as Google App Engine, please see https://github.com/vschafer/spring-security-saml-gae for details.

1.5 Source code

Source code for the project is maintained on Github.

1.6 Builds

Snapshot builds of the project are available in the SpringSource repository. We use Bamboo for continuous integration.

1.7 License

Source code of the module is licensed under the Apache License, Version 2.0. You may obtain copy of the license at https://www.apache.org/licenses/LICENSE-2.0.

1.8 Issue tracking

Please use Spring Security Extensions Jira for submitting of bugs and feature requests. Patches can be sent directly to GitHub as pull requests, but preferably open a Jira issue as well.

1.9 Contributions

Please send your pull requests directly to GitHub and preferably also open issue in Jira.

1.10 Commercial support

For commercial support and consulting services please contact [email protected]

1.11 Community support

For community support please use Stack Overflow. The Spring Security forums contain some previously answered questions, but are now in read-only mode.

1.12 Dependencies

Internal processing of SAML messages, marshalling and unmarshalling is handled by OpenSAML.

Spring SAML has a transitive dependency to library Not-Going-To-Be-Commons-SSL. Inside Spring SAML this library is only used for hostname verifications and will be removed in case OpenSAML removes the dependency.