---
description: Enabling SSO with SAML
---

# Single Sign-On

{% hint style="info" %}
Enabling single sign-on requires you to enable SSL in Study Tracker.
{% endhint %}

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:

```bash
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

{% hint style="info" %}
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.
{% endhint %}

### 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_.

{% hint style="warning" %}
Prior to v1.0, the Single Sign-On URL provided to Okta was `/saml/SSO`
{% endhint %}

### 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](https://entra.microsoft.com)
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

### &#x20;Configure Study Tracker Properties

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

```properties
# 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
