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

# SAML Single Sign-On (SSO)

> Connect your identity provider to the Velt Console so your team signs in with SSO, and optionally let Okta add and remove people for you. This guide uses Okta as the example provider.

SAML SSO controls how your team signs in to the Velt Console. It does not affect the Velt SDK running in your product, and no integration code changes are required. Setup takes about 15 minutes, plus 5 minutes for the optional user sync.

## How it works

1. You create a SAML 2.0 app in your identity provider (Okta in this guide) for the Velt Console.
2. You copy three values from that app (Issuer, Sign-on URL, Certificate) into the Velt Console SAML settings page and click **Save Configuration**. There are no extra steps on the Velt side.
3. You add the people who should get in to your Velt workspace: invite them, or let Okta add them with user sync.
4. Your team signs in at a dedicated SSO URL such as `https://console.velt.dev/saml/acme/login`, or from the Okta dashboard tile, and lands in the Velt Console.

## Before you begin

You need:

* **Okta admin access:** permission to create a new App Integration in your Okta org.
* **Velt workspace owner or admin access:** only owners and admins can manage SAML settings. The SAML tab is hidden from workspace members, so ask an owner or admin to complete Step 3.
* **Your company email domain** (for example `acme.com`). All users signing in through SSO must have emails on this domain. You can't use public email domains such as `gmail.com`. Workspaces owned by the same account can share a domain; a domain already used by another organization's workspace can't be used.

### Values cheat sheet

You exchange values in both directions. Fill this in as you go.

**Velt to Okta:** copy these from the Velt Console SAML page, under **Values for you**.

| Okta field | Value |
| - | - |
| Single sign-on URL (ACS) | `https://console.velt.dev/__/auth/handler` |
| Audience URI (SP Entity ID) | `console.velt.dev` (must match the Velt Service Provider ID exactly) |

**Okta to Velt:** copy these from Okta after you create the app.

| Okta value | Velt field |
| - | - |
| Identity Provider Issuer | Entity ID |
| Identity Provider SSO URL | SSO URL |
| X.509 Certificate | X.509 Certificate |

**Choices you make in Velt:**

| Velt field | Example |
| - | - |
| Display Name | `Acme` |
| Email Domain | `acme.com` |
| URL Slug | `acme` (lowercase letters, numbers, and dashes only) |

> [!TIP]
>
> The exact values for your environment are shown with copy buttons in the Velt Console under **Team → SAML → Values for you**. Always copy from there. The values in this guide assume the production console at `console.velt.dev`.

## Setup

## 1. Create the SAML app in Okta

1. Sign in to your Okta Admin Console.
2. Go to **Applications → Applications → Create App Integration**.
3. Select **SAML 2.0** and click **Next**.
4. Under **General Settings**, set **App name** to `Velt Console` or anything your team will recognize, then click **Next**.
5. Under **Configure SAML**, fill in the **General** section:

| Okta field | What to enter |
| - | - |
| Single sign-on URL | `https://console.velt.dev/__/auth/handler` |
| Use this for Recipient URL and Destination URL | Keep checked |
| Audience URI (SP Entity ID) | `console.velt.dev` |
| Default RelayState | Leave blank |
| Name ID format | `EmailAddress` |
| Application username | `Email` |

6. Leave **Attribute Statements** empty. None are required.
7. Click **Next**, choose **I'm an Okta customer adding an internal app**, then click **Finish**.

> [!WARNING]
>
> The Name ID must be the user's email address. Velt identifies each user by the email Okta sends in the SAML response, so leaving Name ID format as `Unspecified` with a non-email username breaks sign-in.

> [!NOTE]
>
> The Audience URI is a shared identifier. It only has to match byte for byte what you enter as **Service Provider ID** in Velt in Step 3. Use `console.velt.dev` with no `https://`, no trailing slash, and no spaces.

## 2. Copy the Okta values

After the app is created:

1. Open the app's **Sign On** tab.
2. Find the SAML 2.0 metadata and setup details. Click **More details**, or **View SAML setup instructions** on older Okta versions.
3. Copy these three values into your cheat sheet:

| Okta value | Paste it into this Velt field |
| - | - |
| Issuer (Identity Provider Issuer / Entity ID) | Entity ID |
| Sign on URL (Identity Provider Single Sign-On URL) | SSO URL |
| Signing Certificate (download or copy the PEM) | X.509 Certificate |

The certificate must be the full PEM block, including the header and footer lines:

```text theme={null}
-----BEGIN CERTIFICATE-----
[certificate content]
-----END CERTIFICATE-----
```

## 3. Enter the configuration in the Velt Console

1. Sign in to the [Velt Console](https://console.velt.dev) as a workspace owner or admin.
2. Go to **Team → SAML**. If you see a **Manual** / **App-based** switch, choose **Manual**.
3. Fill in **Basic Settings**:

| Field | What to enter | Example |
| - | - | - |
| Display Name | Your company name, shown on your team's branded SSO login page | `Acme` |
| Email Domain | Your company email domain, with no `@` and no `https://` | `acme.com` |
| URL Slug | A short identifier used in your SSO login link. Lowercase letters, numbers, and dashes only | `acme` |

4. Fill in **SAML Settings** with the values you copied from Okta in Step 2:

| Field | What to enter |
| - | - |
| Entity ID | The Okta Issuer (Identity Provider Issuer) |
| SSO URL | The Okta Sign on URL. Must start with `https://` |
| X.509 Certificate | The full PEM certificate, including the BEGIN and END CERTIFICATE lines |
| Service Provider ID | Prefilled with `console.velt.dev`. Keep it, and make sure it matches the Audience URI you entered in Okta |

5. Click **Save Configuration**. You should see "SAML configuration saved."

Saving the form provisions the SSO connection. There is nothing else to enable on the Velt side.

## 4. Assign users in Okta

Back in Okta, open your new app's **Assignments** tab and assign the people or groups who should have access to the Velt Console. Users who are not assigned get an Okta error when they try to sign in.

## 5. Give people access in Velt

Okta decides who can sign in. Your Velt workspace decides who gets in: signing in with SSO never adds anyone to a workspace. People who aren't members see "Contact your admin to sign in."

Add people one of two ways:

* **Invite each person** under **Team → Users**, with the email they use in Okta.
* **Let Okta add them** with [user sync](#sync-users-from-okta), so assigning someone in Okta adds them to the workspace and unassigning them removes them.

## 6. Test sign-in

Your team can sign in through either URL:

| URL | Best for |
| - | - |
| `https://console.velt.dev/saml/<your-slug>/login` (for example `/saml/acme/login`) | Recommended. Your branded login page. Bookmark this and share it with your team |
| `https://console.velt.dev/saml/login` | Generic SSO page. Users enter their work email and are routed to your Okta based on the email domain |

To test:

1. Open your branded URL in a private or incognito window.
2. Enter a work email on your configured domain, for example `you@acme.com`, and click **Continue with SSO**.
3. You are redirected to Okta. Authenticate there, and you land back in the Velt Console dashboard.

## Sign in from the Okta dashboard tile

With the settings above, sign-in starts from Velt. To let people also click the app's tile on their Okta dashboard, change three settings in Okta. Velt shows these values with copy buttons under **Team → SAML → Okta dashboard tile**.

1. In Okta, open the app and go to **General → SAML Settings → Edit**, then **Next** to reach **Configure SAML**.
2. Set **Single sign-on URL** to `https://console.velt.dev/saml/<your-slug>/acs`.
3. Uncheck **Use this for Recipient URL and Destination URL**, and set both **Recipient URL** and **Destination URL** to `https://console.velt.dev/__/auth/handler`.
4. Click **Show Advanced Settings**. Under **Other Requestable SSO URLs**, click **+ Add Another** and enter `https://console.velt.dev/__/auth/handler` with index `1`.
5. Click **Next**, then **Finish**.

Sign-in from Velt keeps working. The direct sign-in link, `https://console.velt.dev/saml/<your-slug>/sso`, starts the same sign-in without the email step, which is useful for an Okta bookmark app.

> [!NOTE]
>
> The tile's Single sign-on URL contains your URL Slug. If you change the slug in Velt, update this URL in Okta too.

## Sync users from Okta

User sync lets Okta add people to your Velt workspace when you assign them to the app, and remove them when you unassign or deactivate them. It uses SCIM 2.0 and needs Okta Lifecycle Management on your Okta plan. Without it, invite people under **Team → Users**.

**1. Create a sync token in Velt**

Save your SAML configuration first. Then, on **Team → SAML → Automatic user sync (SCIM)**:

1. Copy the **SCIM connector base URL**: `https://console.velt.dev/scim/v2`.
2. Click **Turn on and create token** and copy the token.

> [!WARNING]
>
> Velt shows the token once. Treat it like a password and paste it only into Okta. If it's lost or shared, create a new one: the old one stops working right away.

**2. Turn on SCIM for the app in Okta**

1. Open the app's **General** tab. Under **App Settings**, click **Edit**, set **Provisioning** to **SCIM**, and click **Save**.
2. Open the new **Provisioning** tab, select **Integration**, and click **Edit**:

| Okta field | What to enter |
| - | - |
| SCIM connector base URL | `https://console.velt.dev/scim/v2` |
| Unique identifier field for users | `userName` |
| Supported provisioning actions | **Push New Users** and **Push Profile Updates** |
| Authentication Mode | **HTTP Header** |
| Authorization (Bearer) | The token from Velt |

3. Click **Test Connector Configuration**. Okta should report that the connector is configured. Then click **Save**.

> [!NOTE]
>
> Your browser's password manager may fill your Okta password into the **Authorization** field when you change the Authentication Mode. Clear the field before you paste the token.

**3. Choose what Okta sends to Velt**

Under **Provisioning → To App**, click **Edit** and enable **Create Users**, **Update User Attributes** and **Deactivate Users**. Click **Save**. Leave **Import Groups** off: Velt doesn't sync groups.

**4. Assign people and check the result**

Assign people or groups on the **Assignments** tab. Okta adds each person to Velt within seconds, and **Team → Users** lists them. The sync section in Velt shows the last four characters of your token and when Okta last connected.

If people you assigned before turning on sync don't appear, unassign and assign them again.

### What Okta changes in Velt

| In Okta you | In Velt |
| - | - |
| Assign someone, or add them to an assigned group | They're added to the workspace as a Member. Nothing changes if they're already a member. |
| Change their profile | Okta sends the change to Velt. |
| Unassign or deactivate them | They're removed from the workspace, and signed out if it was their only Velt workspace. |
| Reactivate or reassign them | They're added back. |
| Unassign the workspace owner | Nothing. Sync never removes the owner. |

Only emails on your workspace's Email Domain are synced. Sync never changes anyone's role; change roles under **Team → Users**. Velt doesn't email the people sync adds.

## Updating your configuration

Any value can be changed later. Return to **Team → SAML**, edit, and click **Save Configuration** again. Changes take effect immediately.

* **Certificate rotation:** when your Okta signing certificate is renewed, paste the new certificate into the **X.509 Certificate** field and save. Do this before the old certificate expires to avoid sign-in interruptions.
* **Changing the URL Slug:** this updates your branded login URL to `/saml/<new-slug>/login`. Share the new link with your team, and update the tile's Single sign-on URL in Okta if you set it up. Existing sessions are unaffected.
* **Replacing the sync token:** click **Create a new token** and confirm. The old token stops working right away. Paste the new one into Okta under **Provisioning → Integration → Edit**, test it, and save.
* **Turning sync off:** click **Turn off** and confirm. Okta can no longer add or remove anyone. Current members stay.
* **Removing SSO:** contact Velt support at `support@velt.dev` to disable SAML for your workspace.

## Troubleshooting

| Problem | Cause and fix |
| - | - |
| "Only workspace owners and admins can manage SAML configuration" | You are signed in as a workspace member. Ask an owner or admin to make the change. |
| "SAML slug is already in use by another workspace" | Another Velt workspace already claimed that slug. Pick a different one, for example `acme-corp`. |
| "This email domain is already used for SAML by a workspace outside your organization." | A workspace that belongs to another organization uses that domain. If you believe your domain is claimed in error, contact Velt support. |
| "Public email domains cannot be used for SAML." | Use your organization's own domain, not a provider such as `gmail.com`. |
| "Certificate must be a valid X.509 PEM block" | The pasted certificate is missing the BEGIN or END CERTIFICATE lines, or extra characters were introduced. Re-copy the full PEM from Okta. |
| "SSO URL must start with http\:// or https\://." | Paste the full Okta Sign-on URL including `https://`. |
| "SAML is not set up for this email domain." at login | The email entered does not match the Email Domain configured in Velt. The match is exact, so subdomains such as `mail.acme.com` count as different domains. |
| "Contact your admin to sign in" after signing in with Okta | The person isn't a member of the workspace. Invite them under **Team → Users**, or set up user sync. |
| "Signed in as a different account" | Okta already had a session for a different person than the email typed in Velt. Sign out of Okta or use a private window, then try again. |
| Okta shows a 400 error or "The app returned an error" after entering credentials | Usually an Audience URI mismatch. The Okta Audience URI (SP Entity ID) and the Velt Service Provider ID must match exactly. Check for `https://`, trailing slashes, or stray whitespace on either side. |
| Redirected to Okta but returned to the login page with an error | Check that the user is assigned to the app in Okta, and that the app's Single sign-on URL matches Step 1, or the tile settings if you set them up. |
| Clicking the Okta tile doesn't sign people in | Set up the [tile settings](#sign-in-from-the-okta-dashboard-tile). If you changed the URL Slug, update the tile's Single sign-on URL in Okta. |
| Sign-in works for some users but not others | Those users are unassigned in Okta, their Okta email is on a different domain than the configured Email Domain, or they aren't members of the workspace. |
| **Test Connector Configuration** fails in Okta | Check that sync is on in Velt, the base URL is `https://console.velt.dev/scim/v2`, and the Authorization field has only the newest token. |
| Someone you assigned isn't added to Velt | Their email isn't on your Email Domain, or **Create Users** is off under **To App**. Okta lists failed pushes under **Dashboard → Tasks**, where you can retry them. |
| Some pushes fail while you assign a very large group | Velt accepts up to 600 sync requests a minute per workspace. Wait a minute, then retry the failed tasks in Okta. |

Still stuck? Contact `support@velt.dev` with your workspace name, your URL slug, and a screenshot of the error. Never send the whole sync token.

## FAQ

> [accordion] Does this affect my Velt SDK integration or my end users?
>
> No. SAML SSO only controls how your team signs in to the Velt Console, which is the admin dashboard. It has no effect on the Velt SDK running in your product.

> [accordion] Can team members still sign in with Google or an email link after SSO is enabled?
>
> Yes. Enabling SAML adds an SSO sign-in path. It does not block other sign-in methods.

> [accordion] Does signing in with SSO add people to my workspace?
>
> No. Each person needs an invite under **Team → Users**, or has to be added by user sync. Okta only decides who can sign in.

> [accordion] We use an identity provider other than Okta (Entra ID, OneLogin, Google Workspace).
>
> The Velt side is identical. Any SAML 2.0 identity provider works. In your IdP, set the ACS or Reply URL to `https://console.velt.dev/__/auth/handler`. Set the SP Entity ID or Audience to the same value as the Velt **Service Provider ID** field, and make sure the Name ID is the user's email. Then copy your IdP's Issuer, SSO URL, and certificate into the Velt form as described in Step 3. The tile and user sync steps in this guide are written for Okta.

> [accordion] Is Single Logout (SLO) supported?
>
> No. Signing out of the Velt Console does not sign the user out of Okta, and signing out of Okta does not sign the user out of the Velt Console.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.