OneLogin's SAML Java Toolkit

Add SAML support to your Java applications using this library. Forget those complicated libraries and use that open source library provided and supported by OneLogin Inc.

2.8.0 uses xmlsec 2.2.3 which fixes CVE-2021-40690

Version >= 2.5.0 compatible with java8 / java9. Not compatible with java7

2.5.0 sets the 'strict' setting parameter to true.

2.5.0 uses xmlsec 2.1.4 which fixes CVE-2019-12400

Version 2.0.0 - 2.4.0, compatible with java7 / java8.

We introduced some incompatibilities, that could be fixed and make it compatible with java6.

Version 1.1.2 is considered to be deprecated. If you have used it, we strongly recommend that you migrate to the new version. We rebuilt the toolkit on 2.0.0, so code/settings that you had been using in the previous version will no longer be compatible.

• Why add SAML support to my software?
• General description
• Security warning
• Installation
• Hosting
  • Github
  • Maven
• Dependencies
• Working with the github repository code and Eclipse.
• Get the toolkit.
• Adding java-saml toolkit components as a project
• Adding the java-saml-tookit-jspsample as a project
• Deploy the java-saml-tookit-jspsample
• Getting started
• Learning the toolkit
  • core (com.onelogin:java-saml-core)
  • toolkit (com.onelogin:java-saml)
  • samples (com.onelogin:java-saml-tookit-samples)
• How it works
  • Javadocs
  • Settings
  • Properties File
  • KeyStores
  • Dynamic Settings
  • The HttpRequest
  • Initiate SSO
  • The SP Endpoints
  • SP Metadata
  • Attribute Consumer Service(ACS)
  • Single Logout Service (SLS)
  • Initiate SLO
• Extending the provided implementation
• Working behind load balancer
• IdP with multiple certificates
• Replay attacks
• Demo included in the toolkit
  • SP setup
  • IdP setup
  • How it works

Why add SAML support to my software?

SAML is an XML-based standard for web browser single sign-on and is defined by the OASIS Security Services Technical Committee. The standard has been around since 2002, but lately it has become popular due to its advantages as follows:

• Usability - One-click access from portals or intranets, deep linking, password elimination and automatically renewing sessions make life easier for the user.
• Security - Based on strong digital signatures for authentication and integrity, SAML is a secure single sign-on protocol that the largest and most security conscious enterprises in the world rely on.
• Speed - SAML is fast. One browser redirect is all it takes to securely sign a user into an application.
• Phishing Prevention - If you don’t have a password for an app, you can’t be tricked into entering it on a fake login page.
• IT Friendly - SAML simplifies life for IT because it centralizes authentication, provides greater visibility and makes directory integration easier.
• Opportunity - B2B cloud vendor should support SAML to facilitate the integration of their product.

General description

OneLogin's SAML Java toolkit lets you turn a Java application into a SP (Service Provider) that can be connected to an IdP (Identity Provider).

Supports:

• SSO and SLO (SP-Initiated and IdP-Initiated).
• Assertion and nameId encryption.
• Assertion signatures.
• Message signatures: AuthNRequest, LogoutRequest, LogoutResponses.
• Enable an Assertion Consumer Service endpoint.
• Enable a Single Logout Service endpoint.
• Publish the SP metadata (which can be signed).

Key features:

• saml2int - Implements the SAML 2.0 Web Browser SSO Profile.
• Session-less - Forget those common conflicts between the SP and the final app; the toolkit delegates session in the final app.
• Easy to use - Programmer will be allowed to code high-level and low-level programming; 2 easy-to-use APIs are available.
• Tested - Thoroughly tested.
• Popular - OneLogin's customers use it. Add easy support to your java web projects.

Security warning

In production, the onelogin.saml2.strict setting parameter MUST be set as "true". Otherwise your environment is not secure and will be exposed to attacks.

In production also we highly recommend to register on the settings the IdP certificate instead of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism, we maintain it for compatibility and also to be used on test environment.

The IdPMetadataParser class does not validate in any way the URL that is introduced in order to be parsed.

Usually the same administrator that handles the Service Provider also sets the URL to the IdP, which should be a trusted resource.

But there are other scenarios, like a SAAS app where the administrator of the app delegates this functionality to other users. In this case, extra precaution should be taken in order to validate such URL inputs and avoid attacks like SSRF.

Installation

Hosting

Github

The toolkit is hosted on github. You can download it from: * Latest release: https://github.com/onelogin/java-saml/releases/latest * Master repo: https://github.com/onelogin/java-saml/tree/master

Maven

The toolkit is hosted at Sonatype OSSRH (OSS Repository Hosting) that is synced to the Central Repository.

Install it as a maven dependency:

  <dependency>
      <groupId>com.onelogin</groupId>
      <artifactId>java-saml</artifactId>
      <version>2.9.0</version>
  </dependency>

Dependencies

java-saml (com.onelogin:java-saml-toolkit) has the following dependencies:

core: * org.apache.santuario:xmlsec * joda-time:joda-time * org.apache.commons:commons-lang3 * commons-codec:commons-codec * testing: * org.hamcrest:hamcrest-core and org.hamcrest:hamcrest-library * junit:junit * org.mockito:mockito-core * logging: * org.slf4j:slf4j-api * ch.qos.logback:logback-classic * For CI: * org.jacoco:jacoco-maven-plugin

also the Java Cryptography Extension (JCE) is required. If you don't have it, download the version of jce-8, unzip it, and drop its content at ${java.home}/jre/lib/security/. JDK 9 and later offer the stronger cryptographic algorithms by default.

toolkit: * com.onelogin:java-saml-core * javax.servlet:servlet-api

maven: * org.apache.maven.plugins:maven-jar-plugin * org.apache.maven.plugins:maven-surefire-plugin * org.apache.maven.plugins:maven-enforcer-plugin

For more info, open and read the different pom.xml files: core/pom.xml, toolkit/pom.xml

Working with the github repository code and Eclipse.

Get the toolkit.

The toolkit is hosted on github. You can download it from: * Latest release: https://github.com/onelogin/java-saml/releases/latest * Master repo: https://github.com/onelogin/java-saml/tree/master

Adding java-saml toolkit components as a project

1. Open Eclipse and set a workspace
2. File > Import > Maven : Existing Maven Projects > Select the path where the core folder of the Java Toolkit is , resolve the Workspace project and select the pom.xml
3. File > Import > Maven : Existing Maven Projects > Select the path where the toolkit folder of the Java Toolkit is , resolve the Workspace project and select the pom.xml

Adding the java-saml-tookit-jspsample as a project

1. File > Import > Maven : Existing Maven Projects > Select the path where the core folder of the Java Toolkit is , resolve the Workspace project and select the pom.xml

Deploy the java-saml-tookit-jspsample

At the Package Explorer, select the jsp-sample project, 2nd bottom of the mouse and Run As > Run Server Select a Tomcat Server in order to deploy the server.

Getting started

Learning the toolkit

OneLogin's new SAML Java SAML Toolkit contains different folders (core, toolkit, samples) and some files.

Let's start describing them:

core (com.onelogin:java-saml-core)

This folder contains a maven project with the heart of java-saml, classes and methods to handle AuthNRequest, SAMLResponse, LogoutRequest, LogoutResponse and Metadata (low level API). In addition, it contains classes to load the settings of the toolkit and the HttpRequest class, a framework-agnostic representation of an HTTP request.

In the repo, at src/main/java you will find the source; at src/main/resources/schemas, there are xsd schemas used to validate the SAML messages; at src/test/java are the tests for its classes; and at src/test/resources can be found different settings, SAML messages and certificates used by the junit tests.

toolkit (com.onelogin:java-saml)

This folder contains a maven project with the Auth class to handle the low level classes of java-saml-core and the ServletUtils class to handle javax.servlet.http objects, used on the Auth class. In the repo, at src/main/java you will find the source and at src/test/java the junit tests for the classes Auth and ServletUtils.

samples (com.onelogin:java-saml-tookit-samples)

This folder contains a maven project with a jsp app used to learn how the java-saml toolkit works.

Within the java-saml-tookit-jspsample/src/main/webapp folder are several jsp files, each one representing a different endpoint: - index.jsp Index of the webapp. - dologin.jsp SP-initiated SSO endpoint. - dologout.jsp SP-initiated SLO endpoint. - acs.jsp Service Provider Assertion Consumer Service endpoint. - attrs.jsp Shows attributes collected from the SAMLResponse. - sls.jsp Service Provider Single Logout Service endpoint. - metadata.jsp Publish SP metadata.

At java-saml-tookit-jspsample/src/main/resources folder is the onelogin.saml.properties file which contains the SAML settings.

How it works

Javadocs

• toolkit (com.onelogin:java-saml)
• core (com.onelogin:java-saml-core)

Settings

First of all we need to configure the toolkit. The SP's info, the IdP's info, and in some cases, configuration for advanced security issues, such as signatures and encryption.

Properties File

All the settings are defined in one unique file; by default, the Auth class loads a onelogin.saml.properties file with the Auth() method, but if we named it in a different way, we can use Auth(filename);

Here are the list of properties to be defined on the settings file: ```properties

If 'strict' is True, then the Java Toolkit will reject unsigned

or unencrypted messages if it expects them signed or encrypted

Also will reject the messages if not strictly follow the SAML

onelogin.saml2.strict = false

Enable debug mode (to print errors)

onelogin.saml2.debug = false

Service Provider Data that we are deploying

Identifier of the SP entity (must be a URI)

onelogin.saml2.sp.entityid = http://localhost:8080/java-saml-tookit-jspsample/metadata.jsp

Specifies info about where and how the message MUST be

returned to the requester, in this case our SP.

URL Location where the from the IdP will be returned

onelogin.saml2.sp.assertion_consumer_service.url = http://localhost:8080/java-saml-tookit-jspsample/acs.jsp

SAML protocol binding to be used when returning the

message. Onelogin Toolkit supports for this endpoint the

HTTP-POST binding only

onelogin.saml2.sp.assertion_consumer_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Specifies info about where and how the message MUST be

returned to the requester, in this case our SP.

onelogin.saml2.sp.single_logout_service.url = http://localhost:8080/java-saml-tookit-jspsample/sls.jsp

SAML protocol binding to be used when returning the or sending the

message. Onelogin Toolkit supports for this en