> For the complete documentation index, see [llms.txt](https://study-tracker.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://study-tracker.gitbook.io/documentation/installation-and-configuration/single-sign-on.md). # 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.
### 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