See saml Menu

Code Your Java App to Provide SSO via OneLogin

Use OneLogin’s open-source SAML toolkit for JAVA to enable single sign-on (SSO) for your app via any identity provider that offers SAML authentication.

java-saml is available in maven repositories.

This document provides instructions to create an SSO connection between your app and OneLogin. We’ll use the java-saml-tookit-jspsample app java-saml-master/samples/java-saml-tookit-jspsample delivered in the toolkit to demonstrate the setup tasks.

The sample app is a simple app that demonstrates the SSO and single logout (SLO) flow enabled by the SAML toolkit. We assume you understand how to deploy a java project. See deploy a project with Eclipse and Tomcat if you require guidance to deploy java projects.

For information about prerequisites, installation, and developing an app with the SAML Toolkit for JAVA, see OneLogin’s SAML JAVA Toolkit.

Note, there is specific code documentation available for the OneLogin SAML Toolkit Java library. See toolkit documentation and core documentation.

Task 1: Prepare sample project

  1. Download the sample project from SAML Toolkit for JAVA.
  2. Configure the IDE/Server and verify the dependencies defined on the pom.xml are installed.

Task 2: Create an app connector in OneLogin

Use the SAML Test Connector (Advanced) connector to build an application connector for your app. For demo purposes, we’ll build one for the demo1 app.

This app connector provides the SAML values your app needs to communicate with OneLogin as an identity provider. It also provides a place for you to provide SAML values that OneLogin requires to communicate with your app as a service provider.

  1. Access OneLogin.
  2. Go to Apps > Add Apps.
  3. Search for SAML Test Connector.
  4. Select the SAML Test Connector (IdP w/ attr) app.

    SAML Connector

  5. Edit the Display Name, if required. In the case of working with the demo1 app, enter demo1.

  6. Accept the default values and click Save.
  7. Keep the OneLogin app connector UI open for the next task.

Task 3: Define identity provider values in onelogin.saml.properties

In this step, select the identity provider values for your app so it can communicate with OneLogin.

  1. Open onelogin.saml.properties (src/main/resources/onelogin.saml.properties).
  2. Select the SSO tab in the OneLogin app connector UI.
  3. Copy values from the SSO tab and paste them into the ‘idp’ (identity provider, the parameters that start with onelogin.saml2.idp) section of onelogin.saml.properties, as shown below.

    Copy SSO Tab Field Value to settings.json Location

    Issuer URL

    onelogin.saml2.idp.entityid

    SAML 2.0 Endpoint (HTTP)

    onelogin.saml2.idp.single_sign_on_service.url

    SLO Endpoint (HTTP)

    onelogin.saml2.idp.single_logout_service.url

    X.509 Certificate > View Details

    onelogin.saml2.idp.x509cert

  4. Save onelogin.saml.properties.

  5. Keep the OneLogin app connector UI open for the next task.

Task 4: Define service provider values in onelogin.saml.properties

In this step, define the service provider values to identify your app to OneLogin. To do this:

  1. Open onelogin.saml.properties (src/main/resources/onelogin.saml.properties).
  2. The following values are related to the url where the sample is published. Let’s suppose that the base url of the sample app is ‘http://localhost:8080/sample/’ Then we should define:

    • onelogin.saml2.sp.entityid = http://localhost:8080/sample/metadata.jsp
    • onelogin.saml2.sp.assertion_consumer_service.url = http://localhost:8080/sample/acs.jsp
    • onelogin.saml2.sp.single_logout_service.url = http://localhost:8000/sample/sls.jsp
  3. For the onelogin.saml2.sp.nameidformat, change unspecified to emailAddress. This is the value used by OneLogin.

  4. Save onelogin.saml.properties.
  5. In the OneLogin app connector UI, open from the previous task, select the Configuration tab.
  6. Copy values from onelogin.saml.properties into the Configuration tab fields as shown below.
  7. In the OneLogin app connector UI, open from the previous task, select the Configuration tab.

    Copy settings.json Value to Configuration Tab Field

    onelogin.saml2.sp.assertion_consumer_service.url

    • ACS (Consumer) URL

    • Recipient

    onelogin.saml2.sp.single_logout_service.url

    Single Logout URL

    onelogin.saml2.sp.entityid

    Audience

    For a detailed description of each of the fields on the Configuration tab, see How to Use the OneLogin SAML Test Connector for more details.

  8. You can leave RelayState blank. It respects the value sent by the Service Provider.

  9. For now, set ACS (Consumer) URL Validator to .*.
  10. Once you verify that the connection between your app and OneLogin is working, set this value to perform an actual validation. See How to Use the OneLogin SAML Test Connector for more details.
  11. Your Configuration tab should look like this:

    SAML App Config

  12. Click save

If you need advanced security for production, configure the parameters prefixed by Onelogin.saml2.security of the onelogin.saml.properties file.

For more information about how configure those settings, read the settings section of the Java toolkit documentation.

Task 5: Add users to your app connector

In this task, provide users with access to the app connector you created and configured. For example, ensure you have access to the app connector and the sample app.

To do this:

  1. With your app connector open, select the Access tab.
  2. Verify that the settings provide access to the app connector. For example, enable a role that will give you access. In this case, the selected Default role grants access to relevant users, as shown below.

    SAML App Access

  3. Click Save.

Task 6: Log in to your app

At this point, the setup is complete. You can single sign-on and logout of your app. For demo purposes, we demonstrate the login and logout behavior using the sample app.

Log in using service provider-initiated SAML

The following login flow illustrates service provider-initiated SAML, in which the request for authentication and authorization is initiated from the app, or service provider.

  1. Access the sample app, as shown in below. Access http://localhost:8080/sample/index.jsp.

    SAML Demo App

  2. Select Login. Selecting the Login link in the sample app demonstrates the user experience when logging into your app via SSO.

  3. The OneLogin login UI displays. Enter your OneLogin credentials and log in.
  4. A page listing the values from the app connector’s Parameters UI displays. When implemented for your app, this point in the flow displays your app in a logged in state.

    SAML App Params

  5. Select Logout. Selecting the Logout link demonstrates the user experience when logging out of your app via SLO, as shown below.

    SAML App Logout

Troubleshooting: If you see the following UI instead of the OneLogin login UI, please ensure that you have completed Task 5: Add users to your app connector.

SAML App Error

Log in using identity provider-initiated SAML

The following login flow illustrates identity provider-initiated SAML, in which the login request is initiated from OneLogin. In this case, that user experience is as follows:

  1. On your OneLogin App Home page, select the app connector you created and the sample, as shown below.

    SAML Demo App in Portal

  2. The page listing the values from the app connector’s Parameters UI displays. For your app, this displays your app in a logged in state.

  3. Select Logout. Selecting the Logout link demonstrates the user experience when logging out of your app via SLO.

    SAML App Logout

    ?tags=onelogin+saml+java” target=”_blank”>StackOverflow.


Have a Question?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

Have a product idea or request? Share it with us in our Ideas Portal.