Single Sign-On

Enabling SSO with SAML

Enabling single sign-on requires you to enable SSL in Study Tracker.

Study Tracker support SAML2 single-sign-on using either Okta or Microsoft Entra as identity providers.

Creating a key store

Regardless of which identity provider you choose, you will need to create a Java key store (JKS) for the application to store credentials from the provider. Generate a JKS keystore and save it in the same directory that the study-tracker.war file is located. For example:

keytool -genkeypair -alias stsaml -keyalg RSA -keysize 2048 -storetype JKS -keystore saml-keystore.jks -validity 3650

Add the key store location, alias, and password to your application.properties file:

saml.keystore.location=file:/path/to/saml-keystore.jks
saml.keystore.alias=stsaml
saml.keystore.password=mypassword

Okta

Signing-in with Okta requires the user to be registered in Study Tracker. If a user tries to sign into Study Tracker who does not already have an account, the authentication will fail with a not-very-helpful message.

Create a Study Tracker application in Okta

Configure your application in the Okta portal. Be sure that you use SAML 2 and not OAuth. Using your Study Tracker host as a root URL, configure the Okta app to use the following endpoints for your Study Tracker instance:

• Single Sign-On URL: /login/saml2/sso/okta

• Audience URI (SP Entity ID): /saml/metadata

So for example, if your Study Tracker app was being hosted at https://mystudytracker.com:8443, the SSO URL value would be https://mystudytracker.com:8443/login/saml2/sso/okta. These URLs are case-sensitive.

Prior to v1.0, the Single Sign-On URL provided to Okta was /saml/SSO

Configuring Study Tracker for Okta SAML authentication

Add the following items to your application.properties file:

security.sso=okta-saml
sso.okta.url=xxxx
saml.audience=https://mystudytracker.com/saml/metadata
saml.idp=xxxxx
saml.metadata-url=xxxx
saml.metadata-base-url=https://mystudytracker.com

The sso.okta.url value refers to the URL that Okta generates and uses as the entrypoint to authentication for the application. This will be used to generate a link in the web application to allow users to trigger authentication with their Okta provider (as opposed to clicking the Study Tracker link on their Okta dashboard). The saml.idp and saml.metadata-url values refer to the Identity Provider Issuer and Identity Provider metadata URL values in the Okta app configuration, respectively. The saml.audience value should configured as your application's host, with /saml/metadata appended to it.

Entra ID

Setting Up the Application in Entra ID

Step 1: Create a New Enterprise Application in Entra ID

1. Log in to the Microsoft Entra admin center
2. Navigate to Identity > Applications > Enterprise applications

3. Click + New application

4. Select Create your own application

5. Enter a name for your application (e.g., "Study Tracker")

6. Select Integrate any other application you don't find in the gallery (Non-gallery)

7. Click Create

Step 2: Configure SAML Settings

1. In your new application, go to the Single sign-on section

2. Select SAML as the sign-on method

3. Configure the following settings:

Basic SAML Configuration

1. Identifier (Entity ID): Enter the URI that identifies your Study Tracker application

   • Format: https://[your-study-tracker-domain]/saml/metadata

   • Example: https://studytracker.example.com/saml/metadata

2. Reply URL (Assertion Consumer Service URL): Enter the URL where Entra ID will send the SAML response

   • Format: https://[your-study-tracker-domain]/login/saml2/sso/entra

   • Example: https://studytracker.example.com/login/saml2/sso/entra

3. Sign on URL: Enter the URL where users will start the login process

   • Format: https://[your-study-tracker-domain]/login

   • Example: https://studytracker.example.com/login

4. Relay State: Leave empty or specify a URL where users should be directed after authentication

Configure Study Tracker Properties

Add or update the following properties in your Study Tracker application.properties file:

# Enable Entra ID SAML SSO
security.sso=entra-saml

# Entra ID URL (the Login URL from Entra ID)
sso.entra.url=https://login.microsoftonline.com/12345678-1234-1234-1234-123456789012/saml2

# SAML Configuration
saml.audience=https://studytracker.example.com/saml/metadata
saml.idp=https://sts.windows.net/12345678-1234-1234-1234-123456789012/
saml.metadata-url=https://login.microsoftonline.com/12345678-1234-1234-1234-123456789012/federationmetadata/2007-06/federationmetadata.xml
saml.metadata-base-url=https://studytracker.example.com

Replace the example values with your actual configuration:

• sso.entra.url: The Login URL from Entra ID

• saml.audience: The Identifier (Entity ID) you configured in Entra ID

• saml.idp: The Issuer URL from Entra ID (typically in the format shown)

• saml.metadata-url: The URL to the Federation Metadata XML from Entra ID

• saml.metadata-base-url: The base URL of your Study Tracker application