SAML Java Toolkit

The SAML Java Toolkit allows you to transform a Java application into a Service Provider (SP) that connects to an Identity Provider (IdP).

Core Capabilities:

• Profiles: Implements the SAML 2.0 Web Browser SSO Profile (saml2int).
• SSO & SLO: Supports both SP-Initiated and IdP-Initiated Single Sign-On (SSO) and Single Logout (SLO).
• Encryption & Signatures: Supports Assertion and NameID encryption, as well as Assertion signatures and Message signatures (AuthNRequest, LogoutRequest, LogoutResponses).
• Endpoints: Enables Assertion Consumer Service (ACS) and Single Logout Service (SLS) endpoints.
• Metadata: Can publish SP metadata (with optional signing).
• Session Management: The toolkit is designed to be 'Session-less', meaning it delegates session management to your final application to avoid conflicts.

The toolkit is organized into three main Maven projects:

• core (com.onelogin:java-saml-core): The low-level API. It handles AuthNRequest, SAMLResponse, LogoutRequest, LogoutResponse, and Metadata. It also includes framework-agnostic HttpRequest and settings loading.
• toolkit (com.onelogin:java-saml): The high-level API. It provides the Auth class (which wraps core) and ServletUtils for handling javax.servlet.http objects.
• samples (com.onelogin:java-saml-tookit-samples): A JSP-based web application demonstrating how to implement SP endpoints like ACS, SLS, and Metadata.

Security Warning

In production environments, you MUST set the onelogin.saml2.strict setting parameter to "true". Failure to do so leaves your environment insecure and exposed to attacks.

Additionally, for production, it is highly recommended to register the IdP certificate directly in your settings rather than using the fingerprint method. The fingerprint method uses a hash which is susceptible to collision attacks that could allow signature validation bypass.

The toolkit supports two types of Single Logout (SLO) workflows: SP-initiated and IdP-initiated.

SLO Initiated by SP

1. The user clicks a "logout" link at the SP.
2. The user is redirected to /dologout.jsp.
3. A LogoutRequest is sent to the IdP.
4. The IdP closes its session and sends a LogoutResponse to the SP's Single Logout Service (SLS) endpoint: /sls.jsp.
5. The /sls.jsp endpoint validates the response and closes the local application session. The workflow starts and ends at the SP.

SLO Initiated by IdP

1. The logout process is triggered at the IdP.
2. The IdP sends a LogoutRequest to the SP's SLS endpoint: /sls.jsp.
3. The /sls.jsp endpoint validates the request, closes the local session, and sends a LogoutResponse back to the IdP's SLS endpoint.
4. The IdP receives the response and closes the IdP session. The workflow starts and ends at the IdP.

To prevent replay attacks, you should store the unique ID of every SAML message you process. When a new message arrives, check its ID against your stored list. If the ID has already been processed, reject the message.

You can retrieve the ID of the most recently processed message using auth.getLastMessageId().

String lastId = auth.getLastMessageId();
// Store lastId in a cache/database to check against future incoming messages

To use the SAML Java Toolkit in your project, add it as a Maven dependency. The toolkit is hosted at Sonatype OSSRH and synced to the Maven Central Repository.

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

To run the provided JSP sample project in Eclipse:

Importing the project:

1. Go to File > Import > Maven: Existing Maven Projects.
2. Select the path: <path>/java-saml/samples/java-saml-tookit-jspsample and select the pom.xml.

Deploying the project:

1. In the Package Explorer, right-click the jsp-sample project.
2. Select Run As > Run Server.
3. Select a configured Tomcat Server to deploy and run the application.

The toolkit includes a JSP sample project that demonstrates how to configure SAML settings via a unique settings file.

SP Setup

1. Configure the Service Provider (SP) settings.
2. Review the Identity Provider (IdP) metadata.
3. Complete the IdP information.
4. Enable or disable specific security settings as required.

IdP Setup

1. Once the SP is configured, the SP's metadata is published at the /metadata.jsp URL.
2. Use the information from that URL to configure your Identity Provider (IdP).

The toolkit requires the Java Cryptography Extension (JCE).

• JDK 9 and later: Stronger cryptographic algorithms are offered by default; no manual installation is typically required.
• JDK 8 and earlier: You may need to manually download and install jce-8. To install, unzip the download and place its contents into ${java.home}/jre/lib/security/.

If you are working with the source code from the GitHub repository in Eclipse, follow these steps to import the components as Maven projects:

1. Open Eclipse and set a workspace.
2. Import Core: Go to File > Import > Maven: Existing Maven Projects. Select the path to the core folder: <path>/java-saml/core and select the pom.xml.
3. Import Toolkit: Go to File > Import > Maven: Existing Maven Projects. Select the path to the toolkit folder: <path>/java-saml/toolkit and select the pom.xml.

The toolkit is configured using a properties file (defaulting to onelogin.saml.properties). The Auth class can load this file using Auth() or a custom filename via Auth(filename).

Key configuration categories include:

• Global Settings: onelogin.saml2.strict (enforce signatures/encryption) and onelogin.saml2.debug.
• Service Provider (SP) Data: Entity ID, ACS URL, SLO URL, bindings, and certificates (onelogin.saml2.sp.x509cert, onelogin.saml2.sp.privatekey).
• Identity Provider (IdP) Data: IdP Entity ID, SSO/SLO service URLs, bindings, and IdP certificate (onelogin.saml2.idp.x509cert).
• Security Settings: Controls for signing/encrypting AuthnRequest, LogoutRequest, LogoutResponse, Assertion, and Metadata.