> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.deeto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure SAML with Okta

> Step-by-step guide to setting up SAML 2.0 single sign-on between Deeto and Okta — including app creation, SAML signing settings, metadata parsing, and user assignment.

This guide walks through configuring SAML 2.0 single sign-on between Deeto and Okta. Once complete, users in your Okta organization can authenticate into Deeto using your identity provider.

<Warning>
  Only users who already have accounts in Deeto can authenticate via SAML. Deeto does not provision new users automatically — accounts must exist in Deeto first with a matching email address.
</Warning>

***

## What you'll need

* Okta admin dashboard access
* Deeto vendor admin access
* Your Deeto `integrationId` (obtained in Step 1 below)

***

## Step 1 — Create the integration in Deeto

Before configuring Okta, create a placeholder integration in Deeto to obtain the `integrationId`. This ID is required to build the ACS URL you'll paste into Okta.

Contact your Deeto Customer Success Manager or [support@deeto.ai](mailto:support@deeto.ai) to have this created. You'll receive an `integrationId` (a UUID) in return.

<Note>
  Save your `integrationId` — you'll need it to construct the ACS URL and Audience URI in the next steps.
</Note>

***

## Step 2 — Create a SAML app in Okta

<Steps>
  <Step title="Start the app wizard">
    Log in to your **Okta Admin Console**. Go to **Applications → Applications → Create App Integration**. Select **SAML 2.0** and click **Next**.
  </Step>

  <Step title="General Settings">
    Enter **Deeto SSO** (or any descriptive name) as the app name. Optionally upload the Deeto logo. Click **Next**.
  </Step>

  <Step title="Configure SAML tab">
    Fill in the following fields:

    | Field                           | Value                                                                   |
    | ------------------------------- | ----------------------------------------------------------------------- |
    | **Single Sign-On URL**          | `https://api.deeto.ai/v2/sso/integration/saml/{integrationId}/acs`      |
    | **Audience URI (SP Entity ID)** | `https://api.deeto.ai/v2/sso/integration/saml/{integrationId}/metadata` |
    | **Name ID format**              | `EmailAddress`                                                          |
    | **Application username**        | `Email`                                                                 |

    Replace `{integrationId}` with the UUID provided by Deeto.
  </Step>

  <Step title="Configure SAML signing settings">
    Click **Show Advanced Settings** and set:

    | Field                | Value       | Why                                                                  |
    | -------------------- | ----------- | -------------------------------------------------------------------- |
    | Response             | Unsigned    | Okta signs only the inner Assertion, not the outer Response envelope |
    | Assertion Signature  | Signed      | Deeto requires a signed Assertion                                    |
    | Signature Algorithm  | RSA-SHA256  |                                                                      |
    | Digest Algorithm     | SHA256      |                                                                      |
    | Assertion Encryption | Unencrypted |                                                                      |

    <Warning>
      Setting **Response** to Signed will cause validation failures. Okta's standard behavior is to sign only the Assertion — this is correct and expected.
    </Warning>
  </Step>

  <Step title="Add attribute statements (recommended)">
    Add the following attributes so Okta sends the user's name alongside authentication:

    | Name        | Name format | Value            |
    | ----------- | ----------- | ---------------- |
    | `firstName` | Unspecified | `user.firstName` |
    | `lastName`  | Unspecified | `user.lastName`  |

    <Note>
      Deeto uses **NameID (email)** for user lookup — attribute statements are not required for authentication to work, but are recommended for profile completeness.
    </Note>
  </Step>

  <Step title="Finish">
    Click **Next**. On the Feedback page, select **"I'm an Okta customer adding an internal app"** and click **Finish**.
  </Step>
</Steps>

***

## Step 3 — Get the Okta metadata URL

After saving the app in Okta:

1. Go to the **Sign On** tab of the Deeto SSO app
2. Scroll to **SAML Signing Certificates** and click **View IdP metadata**, OR click **More details** and copy the **Metadata URL**

The metadata URL follows this format:

```
https://your-org.okta.com/app/{appId}/sso/saml/metadata
```

Keep this URL — you'll use it in Step 4.

***

## Step 4 — Send metadata to Deeto

Send your Okta metadata URL to Deeto so the integration can be finalized:

1. Copy the metadata URL from Step 3
2. Send it to your Deeto CSM or email it to [support@deeto.ai](mailto:support@deeto.ai)

Deeto will parse the metadata to extract your IdP certificate, issuer, and entry point, then activate the integration. If the metadata URL is not reachable externally, download the XML from Okta (**View IdP metadata → save page**) and send the XML file instead.

***

## Step 5 — Assign users in Okta

In the Okta app, go to the **Assignments** tab. Click **Assign → Assign to People** (or **Assign to Groups** for group-based access). Add the users who should authenticate into Deeto via SSO.

<Note>
  Only users who are both assigned in Okta **and** have an existing Deeto account with a matching email address will be able to authenticate.
</Note>

***

## Step 6 — Test the login

Once Deeto confirms the integration is active:

1. Log into Okta as a test user
2. Click the **Deeto SSO** app tile on the Okta dashboard
3. You should be redirected to Deeto and logged in automatically

A successful authentication redirects to a Deeto magic link URL.

***

## Certificate rotation

Okta rotates signing certificates periodically. When this happens, SAML authentication will fail until the certificate is updated in Deeto.

**When you see authentication errors after a certificate rotation:**

1. In Okta: go to **Sign On → SAML Signing Certificates** to confirm the new active certificate
2. Send the updated metadata URL to [support@deeto.ai](mailto:support@deeto.ai)
3. Deeto will update the integration — no downtime required beyond the time to process the update

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="errors.access_denied immediately on login">
    The IdP certificate or issuer value doesn't match what Deeto has on file. Ask Deeto to re-parse your metadata URL and update the integration.
  </Accordion>

  <Accordion title="errors.access_denied after certificate appears correct">
    The authenticating user's email address doesn't exist in Deeto. Create the user account in Deeto first, then retry.
  </Accordion>

  <Accordion title="SAML signature validation failed">
    Okta's signing certificate was rotated. Follow the certificate rotation steps above.
  </Accordion>

  <Accordion title="Redirect loop after login">
    The ACS URL in Okta doesn't match the `integrationId`. Re-check the Single Sign-On URL in the Okta app matches exactly: `https://api.deeto.ai/v2/sso/integration/saml/{integrationId}/acs`.
  </Accordion>

  <Accordion title="NameID format error">
    Okta is sending a persistent or transient NameID instead of email. Ensure **Name ID format** is set to `EmailAddress` in the Okta SAML configuration tab.
  </Accordion>

  <Accordion title="Assertion not signed">
    Ensure **Assertion Signature** is set to **Signed** in the Advanced Settings section of the Okta SAML configuration.
  </Accordion>
</AccordionGroup>

***

## Need help?

Contact your Deeto Customer Success Manager or email [support@deeto.ai](mailto:support@deeto.ai) with your metadata URL or XML and any error messages you're seeing.