# 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

Once configured, go to the Properties sub-page of the Enterprise Application page for your application. Copy the 'User access URL' value. The URL will be used for starting the sign-in process for Study Tracker.

<figure><img src="/files/J2Bgxn5H8L3X2tQYyVCd" alt="" width="563"><figcaption></figcaption></figure>

### &#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 User Access URL from Entra ID)
sso.entra.url=https://launcher.myapps.microsoft.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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://study-tracker.gitbook.io/documentation/installation-and-configuration/single-sign-on.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.