# SAML SSO with Okta

This guide walks through setting up SAML single sign-on between Okta and Screendesk. After completing these steps, your team members can log in to Screendesk using their Okta credentials.

{% hint style="info" %}
**Plan Availability:** Enterprise only
{% endhint %}

{% hint style="info" %}
Before starting, make sure you have admin access to both the **Okta Admin Console** and your **Screendesk workspace**. You will also need your Screendesk service provider details — find them in **Account Settings → Security → SAML SSO**.
{% endhint %}

***

### Configuration Overview

Setting up SAML SSO with Okta involves creating a SAML app integration in the Okta Admin Console, configuring the SAML settings, and then entering Okta's IdP details in Screendesk.

You will need these Screendesk values for the Okta side:

| Screendesk Field                | Value                                     |
| ------------------------------- | ----------------------------------------- |
| **Single sign-on URL**          | `https://app.screendesk.io/saml_callback` |
| **Audience URI (SP Entity ID)** | `urn:screendesk.io:saml`                  |

***

### Step 1 — Create a SAML App Integration in Okta

{% stepper %}
{% step %}

#### Open the Okta Admin Console

Sign in to your Okta organization and open the **Admin Console**. Navigate to **Applications → Applications**.
{% endstep %}

{% step %}

#### Create a new app integration

Click **Create App Integration**. Select **SAML 2.0** as the sign-in method and click **Next**.
{% endstep %}

{% step %}

#### Name the app

Enter **Screendesk** as the app name. Optionally upload the Screendesk logo. Click **Next**.
{% endstep %}

{% step %}

#### Configure SAML settings

On the **Configure SAML** screen, enter the following:

**General:**

| Field                                              | Value                                     |
| -------------------------------------------------- | ----------------------------------------- |
| **Single sign-on URL**                             | `https://app.screendesk.io/saml_callback` |
| **Use this for Recipient URL and Destination URL** | Checked                                   |
| **Audience URI (SP Entity ID)**                    | `urn:screendesk.io:saml`                  |
| **Default RelayState**                             | Leave blank                               |
| **Name ID format**                                 | **EmailAddress**                          |
| **Application username**                           | **Email**                                 |

**Attribute Statements:**

| Name         | Name format | Value            |
| ------------ | ----------- | ---------------- |
| `email`      | Unspecified | `user.email`     |
| `first_name` | Unspecified | `user.firstName` |
| `last_name`  | Unspecified | `user.lastName`  |

Click **Next**.
{% endstep %}

{% step %}

#### Complete the feedback step

On the **Feedback** screen, select **I'm an Okta customer adding an internal app** and click **Finish**.
{% endstep %}

{% step %}

#### Copy the Okta IdP details

After the app is created, go to the **Sign On** tab and scroll down to the **SAML Signing Certificates** section. Find the active certificate and click **Actions → View IdP metadata**.

Alternatively, use the values shown under **SAML 2.0** in the Sign On tab:

* **Sign on URL** (or **Identity Provider Single Sign-On URL**) — Copy this. You will paste it as the **Single Sign On URL** in Screendesk.
* **Issuer** (or **Identity Provider Issuer**) — Copy this. You will paste it as the **IDP Entity ID** in Screendesk.
* **Signing Certificate** — Click **Download certificate**. You will paste its contents as the **IDP Certificate** in Screendesk.

{% hint style="info" %}
You can also find these values by clicking **View SAML setup instructions** under the **Sign On** tab, which provides all three values on a single page.
{% endhint %}
{% endstep %}

{% step %}

#### Assign users to the app

Go to the **Assignments** tab and click **Assign**. Assign the app to individual users or groups who should have access to Screendesk.

{% hint style="warning" %}
Only users assigned to the Screendesk app in Okta will be able to log in via SAML. Unassigned users will receive an error from Okta.
{% endhint %}
{% endstep %}
{% endstepper %}

***

### Step 2 — Configure Screendesk

{% stepper %}
{% step %}

#### Open SAML SSO settings

In Screendesk, go to **Account Settings → Security → SAML SSO** and click **Edit SAML SSO Settings**.
{% endstep %}

{% step %}

#### Enter the Okta IdP details

Using the values you copied from the Okta Admin Console in Step 1:

| Screendesk Field       | Value from Okta                                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SSO Domain**         | Your company's email domain (e.g., `yourcompany.com`)                                                                                                                                 |
| **IDP Entity ID**      | The **Issuer** (Identity Provider Issuer)                                                                                                                                             |
| **Single Sign On URL** | The **Sign on URL** (Identity Provider Single Sign-On URL)                                                                                                                            |
| **IDP Certificate**    | The contents of the downloaded certificate file. Open it in a text editor and paste the full text, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. |
| {% endstep %}          |                                                                                                                                                                                       |

{% step %}

#### Save the configuration

Click **Save Changes**.
{% endstep %}
{% endstepper %}

***

### Step 3 — Test the Connection

{% stepper %}
{% step %}

#### Test from Okta

In the Okta Admin Console, go to the Screendesk app's **General** tab and click **Test SAML login**. This opens a new window and attempts a full SAML login.
{% endstep %}

{% step %}

#### Test from the Screendesk login page

Open an incognito window, go to the Screendesk login page, click **Sign in with SAML SSO**, and enter an email address that belongs to your SSO domain. You should be redirected to Okta's login page and then signed in to Screendesk.
{% endstep %}
{% endstepper %}

***

### Optional — SCIM Provisioning with Okta

Okta supports SCIM 2.0 for automatic user provisioning. Once configured, Okta can create, update, and deactivate Screendesk user accounts based on app assignments.

{% stepper %}
{% step %}

#### Enable SCIM provisioning in Okta

On the Screendesk app in Okta, go to the **General** tab and click **Edit**. Change **Provisioning** to **SCIM** and click **Save**.
{% endstep %}

{% step %}

#### Configure the SCIM connection

Go to the **Provisioning** tab and click **Edit** under **SCIM Connection**:

| Field                                 | Value                                                        |
| ------------------------------------- | ------------------------------------------------------------ |
| **SCIM connector base URL**           | `https://app.screendesk.io/api/v2/scim`                      |
| **Unique identifier field for users** | `userName`                                                   |
| **Supported provisioning actions**    | Push New Users, Push Profile Updates, Push Groups (optional) |
| **Authentication Mode**               | HTTP Header                                                  |
| **Authorization**                     | The **SCIM Token** from your Screendesk SAML SSO settings    |

Click **Test Connector Configuration** to verify, then click **Save**.
{% endstep %}

{% step %}

#### Enable provisioning actions

Under **Provisioning → To App**, click **Edit** and enable:

* **Create Users**
* **Update User Attributes**
* **Deactivate Users**

Click **Save**.
{% endstep %}
{% endstepper %}

***

### Troubleshooting

<details>

<summary>"SAML Authentication failed" error</summary>

This usually means the SAML response signature could not be verified. Check the following:

* The **IDP Certificate** in Screendesk matches the certificate downloaded from Okta. Make sure you pasted the full PEM text including header and footer lines.
* The **Single sign-on URL** in Okta matches `https://app.screendesk.io/saml_callback` exactly.
* The **Audience URI** in Okta matches `urn:screendesk.io:saml` exactly.
* Make sure the signing certificate in Okta is **Active** (not expired or inactive).

</details>

<details>

<summary>Okta shows "app not assigned" error</summary>

The user trying to log in has not been assigned to the Screendesk app in Okta. Go to the **Assignments** tab and add the user or their group.

</details>

<details>

<summary>SCIM provisioning fails</summary>

* Verify the **SCIM Token** in Okta matches the token shown in your Screendesk SAML SSO settings.
* Confirm the base URL is `https://app.screendesk.io/api/v2/scim` (not `/scim/Users`).
* Check that the **Authentication Mode** is set to **HTTP Header**.

</details>

<details>

<summary>New users get "Ask your IT administrator" message</summary>

This means **Automatic account creation** is turned off in your Screendesk SAML settings. Either enable it in **Account Settings → Security → SAML SSO**, or use SCIM provisioning to create user accounts before they try to log in.

</details>