Set up single sign-on for your team

Single sign-on (SSO) enables your organization to centralize access management, enforce multi-factor authentication policies, and streamline team onboarding through your enterprise Identity Provider (IdP).

SSO is managed by workspace Admins under Settings → Organisation → Single sign-on (/settings/organisation/sso). Single sign-on is available on ValueRamp Scale and Enterprise subscription plans.

What you'll do

1. Configure the connection: choose your protocol (OpenID Connect or SAML 2.0) and enter your identity provider's details.
2. Save: saving the connection shows your domain verification token.
3. Prove you own your domains: add a DNS TXT record to each domain, then click Verify domains.
4. Test the connection: click Test connection and sign in through your identity provider.
5. Enable: click Enable to turn single sign-on on.

Steps 3 and 4 can be done in either order. Enable stays unavailable until you have run a successful test after your last change and every domain is verified.

Configuring Your Identity Provider

ValueRamp supports OpenID Connect and SAML 2.0:

OpenID Connect

For Okta, Microsoft Entra ID, Google Workspace and most modern providers:

• Display Name: The friendly label shown to teammates on the sign-in screen (e.g., Okta (Corporate)).
• Issuer URL: The discovery endpoint serving OpenID Connect metadata at /.well-known/openid-configuration. For Microsoft Entra ID, use your tenant-specific issuer (https://login.microsoftonline.com/<tenant-id>/v2.0) — the shared common issuer cannot be used.
• Client ID & Client Secret: The OAuth application credentials generated within your IdP console.

SAML 2.0

For enterprise providers and legacy setups, select SAML 2.0:

• IdP metadata: give your identity provider's metadata, either as a Metadata URL (ValueRamp refreshes the certificates from it every night) or by choosing Paste XML. The entity ID and signing certificates are read from the metadata — you don't type them in.
• Give these to your IdP: copy the Entity ID (Audience), ACS URL and Metadata URL shown in this panel into your identity provider's application settings, along with the Signing certificate if your provider asks for it.
• Attribute mapping: the Email attribute defaults to NameID. Change it only if your provider sends the email in a different attribute.

Proving Domain Ownership via DNS

To ensure that only authorized domain administrators can route team logins, every email domain associated with your connection must be verified via DNS:

1. Under Allowed domains, enter each corporate domain (e.g., acme.com) and press Enter.
2. In the Prove you own these domains section, locate the host and token values.
3. In your DNS management console, create a TXT record on your domain:
   • Host / Name: _valueramp-sso.<your-domain> (or _valueramp-sso depending on your DNS provider)
   • Type: TXT
   • Value: The alphanumeric token provided in the ValueRamp interface (e.g., click Copy token).
4. Once your DNS host publishes the record, click Verify domains. ValueRamp queries the DNS records immediately and displays a green Verified ✓ badge next to confirmed domains.

Standing Security Check: ValueRamp runs automated background checks against all verified domains every night. If a TXT record is removed, your workspace enters a warning grace period (TXT missing · N days left). If the record is not restored before the countdown completes, single sign-on is automatically deactivated to safeguard workspace security.

Testing and Enabling Connection

Before activating SSO across your organization, you must validate that user claims map accurately:

1. In the Test & enable section, click Test connection.
2. Your browser goes to your identity provider in the same tab. Sign in using the same administrator account currently logged into ValueRamp.
3. Upon returning, the status confirms Last test: passed with your timestamp and email. If you authenticate with a different email, ValueRamp reports an identity mismatch error.
4. Click Enable. The connection switches to Enabled, and teammates with email addresses at your verified domains can now sign in using single sign-on.

Staff Enforcement Policy

Once single sign-on is enabled, Admins can optionally enforce mandatory IdP authentication:

• When Require single sign-on for all staff is enabled, standard email/password logins and direct Google/Microsoft buttons are refused for internal staff in your workspace.
• Session Requirement: You can only turn on enforcement from an active session that authenticated through this SSO connection. This invariant prevents Admins from accidentally locking themselves out.
• Customer & Stakeholder Protection: Enforcement applies strictly to internal team members. External customer users and client stakeholders collaborating in the customer portal continue to sign in with their standard authentication methods.

To learn how teammates log in once SSO is enabled, refer to the Sign in with single sign-on guide.