# 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's SAML implementation is built on the OneLogin SAML toolkit and is compatible with any SAML 2.0 identity provider. The primary documented setup is for **Azure Entra ID** (formerly Azure Active Directory).

***

## 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 > Integrations**.
2. Click **SSO**.
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 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 %}

***

## Enforcing SSO

To enforce SSO as the only authentication method:

1. Configure and test SSO as described above.
2. Verify that all team members can successfully authenticate via SSO.
3. Contact Interlynk support to disable password-based login for your organization.

{% hint style="warning" %}
Before enforcing SSO, ensure at least one admin user has been verified through the SSO flow. If SSO is misconfigured after enforcement, admin users will be locked out.
{% endhint %}

***

## Recovery Plan if Misconfigured

If SSO is misconfigured and users cannot sign in:

1. **If password login is still enabled**: Sign in with email and password, then correct the SAML configuration.
2. **If SSO is enforced**: Contact Interlynk support to temporarily disable SSO enforcement so you can reconfigure.
3. **Common fixes**:
   * Verify the **Tenant** value matches exactly between Azure and Interlynk.
   * Verify the **Entity ID** matches exactly.
   * Ensure the **ACS URL** is correctly configured in Azure.
   * Re-download and re-enter the **App Federation Metadata URL** if the certificate was rotated.

***

## 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 for an additional security layer.
* **Audit SSO users**: Periodically review the user list to ensure only authorized personnel have access.
* **Certificate rotation**: When rotating SAML signing certificates in Azure, update the metadata URL or re-import the metadata in Interlynk.
* **Separate admin access**: Maintain at least one admin user with password-based login as a break-glass account in case SSO fails.

***

## Common Misconfigurations

| Issue                     | Symptom                                     | Fix                                                                      |
| ------------------------- | ------------------------------------------- | ------------------------------------------------------------------------ |
| Tenant mismatch           | SSO redirects but authentication fails      | Ensure the tenant value in Interlynk matches the Azure configuration     |
| Entity ID mismatch        | SAML assertion rejected                     | Verify the Identifier/Entity ID is identical in both Azure and Interlynk |
| ACS URL wrong             | Azure returns an error after authentication | The ACS URL is auto-generated — verify the tenant is correct             |
| Missing email claim       | User created without email                  | Ensure `emailaddress` claim is mapped in Azure Attributes & Claims       |
| Certificate expired       | SAML assertion signature validation fails   | Rotate the certificate in Azure and update the metadata URL in Interlynk |
| Default role set to Admin | All new SSO users get admin access          | Change the default SSO user role to Viewer                               |