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

# SAML

## Instruqt SSO Integration with SAML 2.0

Set up Single Sign-On (SSO) for play.instruqt.com using your Security Assertion Markup Language (SAML) 2.0 Identity Provider (IdP). This process uses SAML to securely authenticate users.

#### Prerequisites

* An active SAML 2.0 Identity Provider (IdP) account with administrative privileges (e.g., Okta, Azure AD, OneLogin, W3ID, etc.).
* An active Instruqt account with access to the SSO configuration page: `https://play.instruqt.com/manage/{team-name}/sso`

***

## Step-by-Step Configuration

The configuration involves three main phases:

1. Setting up the application in your IdP and retrieving its metadata
2. Configuring Instruqt with this information
3. Potentially updating your IdP with the final Assertion Consumer Service (ACS) URL from Instruqt.

### **Phase 1: Configure Your SAML Application (In Your IdP)**

Follow these steps within your chosen SAML Identity Provider (IdP) to set up the Instruqt application and retrieve the necessary configuration details.

Step 1: Create a New SAML Application

* Log in to your IdP's administrative console.
* Create a new application for Instruqt, and Configure the application to use SAML 2.0. This process varies per IdP.
* When prompted for configuration details, use placeholders if required, as the final details will be completed in Phase 3. Ensure you save the application setup to generate the IdP metadata.

Step 2: Retrieve IdP Metadata

After creating the application, your IdP will provide the essential metadata needed for Instruqt:

* Signing Endpoint (SSO URL): The URL where Instruqt will send authentication requests.
* Signing Certificate: The X.509 certificate used by your IdP to sign SAML assertions.

Step 3: Map the User Attributes

{% hint style="warning" %}
Sign-in fails if your IdP does not send the email address. Complete this step before you test the connection.
{% endhint %}

Instruqt identifies a user by email address, and needs a name to create the account. Map both attributes in your SAML application:

* Email: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
* Name: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`

Set the NameID format to EmailAddress.

Step 4: Choose the Audience URI

Your IdP sends an Audience URI (also called the SP Entity ID) in every SAML response. Instruqt does not generate this value — you choose it, and you enter the same value on both sides.

* Set the Audience URI in your SAML application. Your Instruqt team name is a clear choice.
* Keep this value. You enter it in Instruqt in Phase 2.

### **Phase 2: Configure Instruqt (In Instruqt)**

Use the details retrieved from your IdP to configure the SAML integration in Instruqt.

Step 1: Access Instruqt SSO Settings

* Go to your Instruqt SSO configuration page: `https://play.instruqt.com/manage/{team-name}/sso` (replace `{team-name}` with your actual team name).
* Select the SAML 2.0 option.

Step 2: Enter IdP Details

Use the parameters from Phase 1 to configure the integration:

* Entity ID (Audience URI): Paste the Audience URI you set in your SAML application in Phase 1, Step 4. The two values must match exactly.
* Signing Endpoint (SSO URL): Paste the IdP's Signing Endpoint here.
* Signing Certificate (Base64): Paste the Base64 encoded Signing Certificate here.

{% hint style="warning" %}
Do not paste your IdP's own Entity ID in the Entity ID field. Instruqt expects the Audience URI that your IdP sends. A mismatch makes the IdP reject the sign-in with an invalid audience error.
{% endhint %}

{% hint style="info" %}
Important Note on Certificate: The Signing Certificate must be Base64 encoded before entering it into Instruqt. The raw certificate should begin with `-----BEGIN CERTIFICATE-----`

```
$ cat cert.pem | base64
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCg...
```

{% endhint %}

* Click Save.
* Instruqt will now display the generated Service Provider (SP) metadata, including the required Assertion Consumer Service (ACS) URL and the Email Attribute Mapping.

Essential Instruqt Metadata:

* Assertion Consumer Service URL (ACS URL): This is the URL where your IdP must send the SAML response.

  *Example:* `https://sso.play.instruqt.com/login/callback?connection={team-name}-samlp&organization_id={organization_id}`\
  Note: The organization id is only known after saving the details in Step 2
* Email Attribute Mapping (NameID Format): Instruqt requires the user's email address to identify the user.

  *Example:* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`

### **Phase 3: Finalize Configuration (In Your IdP)**

Step 1: Update Your SAML Application with ACS URL

* Return to your SAML application settings in your IdP's administrative console.
* Update the Assertion Consumer Service (ACS) URL with the exact value provided by Instruqt in Phase 2. This URL tells your IdP where to send the authentication response.
* Confirm the email and name attributes from Phase 1, Step 3 are still mapped.

Once these steps are complete, users in your organization will be able to sign in to play.instruqt.com using their SAML credentials via `https://play.instruqt.com/{team-name}/login`

***

## FAQ

<details>

<summary>Sign-in fails with a 401 Unauthorized error. What is wrong?</summary>

Your IdP accepted the sign-in, but did not send an attribute that Instruqt needs.

Map the email and name attributes as described in Phase 1, Step 3, then sign in again:

* Email: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
* Name: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`

</details>

<details>

<summary>My IdP reports an invalid audience error. What is wrong?</summary>

The Audience URI in your SAML application does not match the Entity ID in Instruqt.

Open your Instruqt SSO settings, copy the Entity ID (Audience URI) value, and set the same value as the Audience URI in your SAML application.

</details>

<details>

<summary>Does Instruqt support user de-provisioning and/or SCIM?</summary>

Not at this time. If your use case requires de-provisioning, we encourage you to contact our support team and share your request with us.

</details>