> For the complete documentation index, see [llms.txt](https://docs.interlynk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interlynk.io/administration/sso.md).

# SSO

Interlynk supports SAML 2.0-based single sign-on (SSO) for centralized identity management. This allows users to authenticate through your organization's identity provider (IdP) instead of managing separate credentials.

***

## Supported Identity Providers

Interlynk works with any SAML 2.0 identity provider. Step-by-step setup guides are available for:

* [**Azure Entra ID**](#saml-setup-with-azure-entra-id) (formerly Azure Active Directory)
* [**Okta**](#saml-setup-with-okta)

***

## SAML Setup with Azure Entra ID

### Prerequisites

* An Azure Entra ID tenant with administrative access.
* An Interlynk organization with Admin permissions.
* The ability to create Enterprise Applications in Azure Entra ID.

### Step 1: Create an Enterprise Application in Azure

1. Sign in to the [Azure Entra ID portal](https://entra.microsoft.com).
2. Navigate to **Enterprise Applications > New Application > Create your own application**.
3. Name the application (e.g., "Interlynk SSO").
4. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
5. Click **Create**.

### Step 2: Configure SAML in Azure

1. In the application, navigate to **Single sign-on > SAML**.
2. Configure the **Basic SAML Configuration**:

| Field                  | Value                                                                                         |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| Identifier (Entity ID) | Enter the value from the Interlynk SSO configuration modal                                    |
| Reply URL (ACS URL)    | Auto-generated in Interlynk: `https://api.interlynk.io/auth/saml/callback?tenant=YOUR_TENANT` |
| Sign on URL            | (Optional) Your Interlynk dashboard URL                                                       |

3. Configure **Attributes & Claims** (see attribute mapping table below).
4. Download the **App Federation Metadata URL** from the SAML Signing Certificate section.

### Step 3: Configure SAML in Interlynk

1. Navigate to **Settings > Organization > People & Access > SSO**.

![Settings sidebar: Organization > People & Access > SSO](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-4ea4a8dc8adea43fff0abe7a2099ab104ed78010%2Fsso_settings_nav.png?alt=media)

2. Click **Configure App** on the **Microsoft Entra ID** card.
3. Fill in the following fields:

| Field                           | Description                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| **Tenant**                      | A unique identifier for your organization's SAML tenant (e.g., your domain name)             |
| **Identifier / Entity ID**      | The entity ID configured in Azure (must match exactly)                                       |
| **Reply URL / ACS URL**         | Auto-generated: `https://api.interlynk.io/auth/saml/callback?tenant=YOUR_TENANT` (read-only) |
| **App Federation Metadata URL** | The metadata URL from Azure Entra ID                                                         |
| **Default User Role**           | The role assigned to users who authenticate via SSO for the first time                       |

4. Click **Save**.

### Step 4: Test SSO

1. After configuration, attempt to sign in using SSO.
2. You will be redirected to your Azure Entra ID login page.
3. After successful authentication, you will be redirected back to Interlynk.
4. Verify that the user's name, email, and role are populated correctly.

***

## SAML Setup with Okta

Interlynk supports **SP-initiated login** with Okta, where the user starts sign-in from Interlynk.

{% hint style="warning" %}
**IdP-initiated login** (clicking the app tile on the Okta dashboard) is not supported. It may appear to work, but it may stop working in a future release.
{% endhint %}

### Prerequisites

* An Okta admin account that can create app integrations. To try it out, you can [sign up for a free Okta account](https://developer.okta.com/signup/).
* An Interlynk organization with Admin permissions.
* A **tenant** value for your organization: a short identifier without spaces (e.g., `acme`). It appears in the URLs below and must be unique across Interlynk.

Use **one Okta app per Interlynk organization**. Each Interlynk organization has exactly one SAML configuration, and the tenant ties the two together.

### Step 1: Create the Okta App Integration

1. In the Okta Admin Console, navigate to **Applications > Applications**.
2. Click **Create App Integration**.
3. Select **SAML 2.0** and click **Next**.
4. Name the app (e.g., "Interlynk") and click **Next**.

![Create app integration with SAML 2.0 selected](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-7537a08277f5c174a5af4474527a272a8ba42139%2Fcreate_app_integration.png?alt=media)

{% hint style="info" %}
On a new Okta Integrator or developer org, do not use the **Create your first Okta app** button on the home page. It starts the Okta Integration Network submission flow, not a private app.
{% endhint %}

### Step 2: Configure SAML Settings in Okta

Fill in the **General** section under **SAML Settings**:

| Okta Field                                     | Value                                                            |
| ---------------------------------------------- | ---------------------------------------------------------------- |
| Single sign-on URL                             | `https://api.interlynk.io/auth/saml/callback?tenant=YOUR_TENANT` |
| Use this for Recipient URL and Destination URL | Checked                                                          |
| Audience URI (SP Entity ID)                    | `https://api.interlynk.io/saml/YOUR_TENANT`                      |
| Default RelayState                             | Leave empty                                                      |
| Name ID format                                 | **EmailAddress**                                                 |
| Application username                           | **Email**                                                        |

Replace `YOUR_TENANT` with your tenant value. The `?tenant=` part of the Single sign-on URL is required: Interlynk uses it to find your organization's configuration.

![SAML General settings in Okta](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-59e993608b893ce9e7fe86df61e68b71056eb5c4%2Fsaml_general_settings.png?alt=media)

{% hint style="warning" %}
The Audience URI must be **exactly** the same string you enter as the **Identifier (Entity ID)** in Interlynk (Step 6). Any difference, including a trailing slash, causes logins to fail.
{% endhint %}

Click **Next**, answer the feedback question (e.g., "This is an internal app that we have created"), and click **Finish**.

### Step 3: Add Attribute Statements

You can only add attribute statements after the app is created; the creation wizard doesn't show them.

1. Open the app's **Sign On** tab.
2. In the **Attribute statements** section, click **Add expression**.
3. Enter the **Name** and **Expression** for the first row below, then click **Save**.
4. Repeat for the remaining rows.

| Name        | Expression               |
| ----------- | ------------------------ |
| `email`     | `user.profile.email`     |
| `firstName` | `user.profile.firstName` |
| `lastName`  | `user.profile.lastName`  |

![Attribute statements for email, firstName and lastName](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-26bf729cd979c7718c8299b7576b251468bdd22d%2Fattribute_statements.png?alt=media)

`email` is required. Without it, login fails with *"Your identity provider did not send a valid email address."* `firstName` and `lastName` set the user's display name.

{% hint style="info" %}
Names are case-sensitive: enter them exactly as shown.
{% endhint %}

#### Using the Legacy Configuration

If your Okta org doesn't show **Add expression**, or you already manage attribute statements in the legacy configuration, use that instead:

1. Open the app's **Sign On** tab.
2. Under **Attribute statements**, expand **Show legacy configuration** and click **Edit** next to **Profile attribute statements**. Older Okta admin UIs show these rows directly, without the legacy section.
3. Add the following rows:

| Name        | Name Format | Value            |
| ----------- | ----------- | ---------------- |
| `email`     | Unspecified | `user.email`     |
| `firstName` | Unspecified | `user.firstName` |
| `lastName`  | Unspecified | `user.lastName`  |

4. Click **Save**.

![Legacy profile attribute statements for email, firstName and lastName](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-b59b8552bb14cd219f917cf5abc7e10086208730%2Fattribute_statements_legacy.png?alt=media)

{% hint style="warning" %}
Use either the new expressions or the legacy configuration, not both. Okta sends statements from both, so defining the same attribute twice can lead to duplicate values.
{% endhint %}

### Step 4: Assign Users

1. Open the app's **Assignments** tab.
2. Click **Assign > Assign to People** or **Assign to Groups**, and assign everyone who should sign in to Interlynk.

![Assignments tab in Okta](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-d8836407d7552e1368c11e0124de30747b79e7e5%2Fassign_users.png?alt=media)

Unassigned users are stopped by Okta before they reach Interlynk.

Optionally, on the **General** tab under **App Settings**, check **Do not display application icon to users**. This hides the dashboard tile, since IdP-initiated login is not supported.

### Step 5: Copy the Metadata URL

On the app's **Sign On** tab, copy the **Metadata URL**. It has this form:

```
https://<your-okta-org>.okta.com/app/<app-id>/sso/saml/metadata
```

![Metadata URL on the Sign On tab](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-9d60cfcb4e636411e5eff1da1019ae50127e6ede%2Fmetadata_url.png?alt=media)

### Step 6: Configure SAML in Interlynk

1. Navigate to **Settings > Organization > People & Access > SSO**.

![Settings sidebar: Organization > People & Access > SSO](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-4ea4a8dc8adea43fff0abe7a2099ab104ed78010%2Fsso_settings_nav.png?alt=media)

2. Click **Configure App** on the **Okta** card.

![Okta card on the SSO settings page](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-4bd195807c1b584a96fdd915e2acb0b075005576%2Finterlynk_sso_card.png?alt=media)

3. Fill in the following fields:

| Field                                          | Value                                                                         |
| ---------------------------------------------- | ----------------------------------------------------------------------------- |
| **Tenant**                                     | Your tenant value                                                             |
| **Identifier (Entity ID)**                     | The Audience URI from Step 2                                                  |
| **Reply URL (Assertion Consumer Service URL)** | Auto-generated from the tenant; must match the Single sign-on URL from Step 2 |
| **Okta Metadata URL**                          | The metadata URL from Step 5                                                  |
| **Default User Role**                          | The role assigned to users who authenticate via SSO for the first time        |

![Configure Okta form](https://3359124359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1iY0x7YnBpq0rnTB0Tt4%2Fuploads%2Fgit-blob-2158c3a6783387db56dcce44b35ad9685a1d67b1%2Finterlynk_configure_form.png?alt=media)

4. Click **Save**.

### Step 7: Test SSO

1. Sign out of Interlynk, or use a private browser window.
2. Start SSO sign-in from the Interlynk sign-in page for your tenant.
3. Sign in to Okta when prompted.
4. You are redirected back to Interlynk, signed in. On a user's first login, Interlynk creates the account and adds it to your organization with the default role (see [Auto-Registration](#auto-registration)).

***

## SAML Attribute Mapping

Interlynk requires the following attributes in the SAML assertion:

| SAML Attribute                                                       | Interlynk Field | Required    | Description                                          |
| -------------------------------------------------------------------- | --------------- | ----------- | ---------------------------------------------------- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`         | Name            | Yes         | User's full display name                             |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | Email           | Yes         | User's email address (used as the unique identifier) |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    | First Name      | Recommended | User's first name                                    |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      | Last Name       | Recommended | User's last name                                     |

### Azure Entra ID Default Claims

Azure Entra ID provides these attributes by default. Verify they are included in the **Attributes & Claims** section of your Enterprise Application:

| Claim Name     | Source Attribute                        |
| -------------- | --------------------------------------- |
| `name`         | `user.displayname`                      |
| `emailaddress` | `user.mail` or `user.userprincipalname` |
| `givenname`    | `user.givenname`                        |
| `surname`      | `user.surname`                          |

***

## Auto-Registration

When a user authenticates via SSO for the first time and does not have an existing Interlynk account:

1. An Interlynk account is automatically created using the email and name from the SAML assertion.
2. The user is automatically associated with the organization linked to the SAML tenant.
3. The user is assigned the **Default User Role** configured in the SSO settings.
4. No separate invitation is required.

{% hint style="info" %}
Auto-registration is enabled by default when SSO is configured.
{% endhint %}

***

## Security Best Practices

* **Use a strong default role**: Set the default SSO user role to **Viewer** to follow least-privilege principles. Promote users to higher roles after onboarding.
* **Require MFA in your IdP**: Interlynk defers authentication to your identity provider — enable MFA in Azure Entra ID or Okta for an additional security layer.
* **Audit SSO users**: Periodically review the user list to ensure only authorized personnel have access.

***

## Rotating the Signing Certificate

When you activate a new SAML signing certificate in Azure Entra ID or Okta, refresh it in Interlynk:

1. Navigate to **Settings > Organization > People & Access > SSO**.
2. On your SSO card, open the **⋮** menu and click **Refresh metadata**.

{% hint style="danger" %}
**Do this immediately after activating the new certificate.** Until you refresh, SSO sign-in fails for everyone in your organization.
{% endhint %}

***

## Troubleshooting

| What You See                                                   | Fix                                                                                                                                                                                                        |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *"Your identity provider did not send a valid email address."* | Make sure your IdP sends the user's email: the `email` attribute in Okta ([Step 3](#step-3-add-attribute-statements)) or the `emailaddress` claim in Azure. Check that the user has an email in the IdP    |
| *"Saml authentication failed"*                                 | Check that the Entity ID and Reply URL in your IdP match Interlynk exactly, character by character. If you recently rotated the signing certificate, [refresh metadata](#rotating-the-signing-certificate) |
| *"SSO configuration not found"*                                | Check the tenant spelling and that SSO is enabled for your organization                                                                                                                                    |
| Okta shows "User is not assigned to this application"          | Assign the user or their group to the Okta app ([Step 4](#step-4-assign-users))                                                                                                                            |
| All new SSO users get admin access                             | Change the **Default User Role** to **Viewer**                                                                                                                                                             |
