> For the complete documentation index, see [llms.txt](https://incident-tracker.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://incident-tracker.gitbook.io/docs/admin-guide/application-information/authentication-settings/single-sign-on.md).

# Single Sign-on

This guide explains how to configure Single Sign-On (SSO) between Microsoft Entra ID (Azure AD) and Incident Tracker.

{% hint style="success" %}
If SCIM is configured already, SSO can use the same Enterprise Application.
{% endhint %}

***

## Prerequisites

* Admin access to Microsoft Entra ID (Azure AD)
* Admin access to Incident Tracker
* Permission to create and manage enterprise app registrations

***

## Configure Single Sign-On (SSO)

#### 1. Register an Enterprise Application

* Go to **Microsoft Entra Admin Center** > **Enterprise Applications**
* Click **+ New application** > Choose **Create your own application**
* Name it: `Incident Tracker SSO`

#### 2. Set Up SAML SSO

* In the app, go to **Single sign-on** > Choose **SAML**
* Enter values from Incident Tracker:
  * Identifier (Entity ID)
    * `Incident-Tracker-SSO`
  * Reply URL (Assertion Consumer Service URL)
    * <https://secure.incident-tracker.com/> (default URL)
    * <https://secure2.incident-tracker.com/>
  * Sign-on URL (optional)
    * <https://secure.incident-tracker.com/`[clientID> or clientName]\`
* Download the **Federation Metadata XML**

#### 3. Configure SSO in Incident Tracker

* In Incident Tracker admin settings, paste in the following:
  * Login URL (SAML endpoint URL in Incident Tracker)
  * Application ID
  * Base64 Certificate

{% hint style="warning" %}
After saving the SAML configuration, any existing user accounts intended for SSO must be manually converted to third-party accounts. Users who have not been converted will receive a sign-in error (\`samlfailed=error4\`) when attempting to log in via SSO. Contact Incident Tracker for assistance with mass converting accounts.
{% endhint %}

#### 4. Assign Users and Test

* Assign users/groups in Entra ID to the application
* Log in via Incident Tracker to test

***

## SSO Configuration

### ▶️ Interactive Tutorial – SSO Configuration

{% @arcade/embed flowId="xZha9EZnidRDLgAdUfGF" url="<https://app.arcade.software/share/xZha9EZnidRDLgAdUfGF>" %}

***

### SSO Error Codes

After SAML is enabled, sign-in errors will appear as a code in the browser URL. Use the table below to identify and troubleshoot the issue.

| Error Code          | Meaning                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `samlfailed=error4` | The username from the SAML response was not found in Incident Tracker, or the account has not been configured for third-party SSO login. |
| `samlfailed=error3` | The SAML response was not valid. This is typically a technical issue with the SAML token or federation metadata configuration.           |
| `code=6`            | A cookie or session error occurred. This may indicate an expired session, blocked cookies, or a browser configuration issue.             |

{% hint style="info" icon="mobile" %}
To enable SSO for the Incident Tracker Mobile app, additional Azure configuration is required. See [Mobile App Settings — Part 3](https://incident-tracker.gitbook.io/docs/admin-guide/application-information/mobile-app-settings#part-3-microsoft-sso-configuration-azure) for step-by-step instructions.
{% endhint %}