> 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://docs.trustswiftly.com/single-sign-on/saml2-sso-okta-etc.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.