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)

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.

   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.

   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:

   -----BEGIN CERTIFICATE-----
   [certificate content]
   -----END CERTIFICATE-----
   
3. Enter the configuration in the Velt Console

   1. Sign in to the Velt Console 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, 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 [e-mail], 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.

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.

   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.

   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 [e-mail] 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. 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 [e-mail] with your workspace name, your URL slug, and a screenshot of the error. Never send the whole sync token.

​

FAQ

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.

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.

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.

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.

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.