> For the complete documentation index, see [llms.txt](https://docs.trustswiftly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustswiftly.com/single-sign-on/saml2-sso-okta-etc.md).

# SAML2 SSO (Okta, etc)

Integrating Trust Swiftly with a SAML 2.0 identity provider (IdP) like Okta, Azure AD, or others centralizes user management, enhances security, and simplifies the login process. This guide will walk you through the setup process.

{% stepper %}
{% step %}

## Configure Your Identity Provider (Okta Example)

First, create a new application within your identity provider. The following steps use Okta as an example.

1. Log in to your Okta organization with administrative privileges.
2. Navigate to **Applications** > **Applications**, and click **Create App Integration**.
3. In the pop-up window, select **SAML 2.0** as the sign-in method and click **Next**.
4. **General Settings:**
   * Give the application a name, such as "Trust Swiftly".
   * *Optional:* Upload the Trust Swiftly logo using this URL: `https://app.trustswiftly.com/assets/images/icon.png`
   * Click **Next**.
5. **Configure SAML:** Enter the following values into the corresponding fields (replacing `{subdomain}` with your actual Trust Swiftly subdomain):
   * **Single sign-on URL:** `https://{subdomain}.trustswiftly.com/auth/saml2/callback`
   * **Audience URI (SP Entity ID):** `https://{subdomain}.trustswiftly.com/auth/saml2`
   * **Name ID format:** `EmailAddress`
   * **Application username:** `Email` (or `Okta username` if your Okta usernames are emails)
6. **Attribute Statements:** Configure an attribute to pass the user's email address to Trust Swiftly:
   * **Name:** `email`
   * **Name format:** `Unspecified`
   * **Value:** `user.email`
7. Click **Next**. On the feedback page, select *"I'm an Okta customer adding an internal app"* and click **Finish**.
8. **Get Metadata URL:** After creating the app, go to the **Sign On** tab. In the "SAML 2.0" section, find the link labeled **Identity Provider metadata**. Right-click and copy this URL. *(The URL will look similar to: `https://your-org.okta.com/app/xxxxxxxx/sso/saml/metadata`)*
   {% endstep %}

{% step %}

## Configure Trust Swiftly

Provide the Identity Provider details to your Trust Swiftly instance. (Contact <support@trustswiftly.com> with the URL for setup if your account does not have permission)

1. Log in to your Trust Swiftly dashboard with an administrator account.
2. Navigate to **Settings** > **Auth & Registration**.
3. On the **Authentication** tab, locate the **Single Sign On** section.
4. Paste the **Metadata URL** you copied from Okta into the text field.
5. Click **Update Settings** at the bottom of the page to save the configurations.
   {% endstep %}

{% step %}

## Enforce Single Sign-On (Optional)

You can require all administrators and analysts to log in exclusively through SSO, disabling password-based login for those roles.

{% hint style="warning" %}
**Important Warning:** Do not enable this setting until you have successfully tested the SSO login flow in a separate, incognito/private browser window. Keep your current administrator session active during testing to avoid locking yourself out of the dashboard.
{% endhint %}

1. While still on the **Auth & Registration** page, locate the **Enforce Single Sign On** toggle.
2. Enable this option to restrict admins and analysts to SSO logins only.
3. Click **Update Settings** to save your changes.
   {% endstep %}

{% step %}

## Logging In via SSO

To log in, users must first be assigned the application within Okta. Once assigned, they can log in using either of the following methods:

* **Identity Provider (IdP) Initiated:** Users click the **Trust Swiftly** application tile on their Okta dashboard. They will be automatically redirected and logged in.
* **Service Provider (SP) Initiated:** Users navigate directly to `https://{subdomain}.trustswiftly.com/auth/saml2/login` (replacing `{subdomain}` with your company's subdomain). This will automatically redirect them to Okta to authenticate before returning to the dashboard.
  {% endstep %}
  {% endstepper %}