Skip to main content

Single Sign-On (SSO) & SCIM Provisioning with WorkOS

This article will walk you through the steps to configure SSO for your team, and connect your Active Directory.

Nuvo SSO supports most major Identity Providers that are SAML or OIDC compatible (i.e. Okta, Azure, Google Workspace, etc.).

Overview

Nuvo supports enterprise Single Sign-On (SSO) and automated user provisioning (SCIM) through WorkOS. WorkOS acts as a translator between Nuvo and your identity provider, so the same setup works whether you use Okta, Microsoft Entra ID (Azure AD), Google Workspace, OneLogin, or any other SAML 2.0 / OIDC provider.

Connecting your identity provider lets your team:

  • Sign in with your company credentials — users log into Nuvo using your existing identity provider. There's no separate Nuvo password to manage, and your provider's MFA and security policies apply automatically.

  • Onboard new users automatically (just-in-time provisioning) — anyone your IT team has assigned to Nuvo in your identity provider can sign in on day one. The first time they log in via SSO, their Nuvo account is created automatically — no manual invite, no password setup.

  • Map identity-provider groups to Nuvo roles — a user's Nuvo permissions and functions (e.g., Credit Approver, Sales Rep, Admin) are assigned automatically based on the groups they belong to in your directory.

  • Automatically remove departed users (SCIM) — when someone is deactivated or deleted in your directory, their Nuvo access is revoked automatically.

What You'll Need

  • Administrator access in Nuvo — only Nuvo Admins can configure SSO (Settings → My Team).

  • Administrator access to your identity provider (Okta, Entra ID, Google Workspace, etc.) to configure the connection and, if desired, directory sync.

  • A decision on protocol — SAML or OIDC. Your IT contact chooses one when setting up the connection. The attribute claims you'll send Nuvo differ between the two (see Required Attribute Claims).

  • Your company email domain(s) — e.g. yourcompany.com. These are verified as part of setup.

  • A WorkOS invitation — your Nuvo team creates a WorkOS Organization for your company and emails your IT contact a secure WorkOS invitation, a guided portal where they connect your identity provider. Your IT contact does not need their own WorkOS account.

💡 Tip: Reach out to your Nuvo contact (or support@nuvo.com) to start SSO setup. Let them know who your IT contact is and which identity provider you use, and they'll send the WorkOS invitation.

How It Works

Capability

What it does

Direction

SSO (SAML / OIDC)

Authenticates users against your identity provider at login

Your IdP → Nuvo

Just-in-time provisioning

Creates a Nuvo account on a user's first SSO login

Your IdP → Nuvo

Group → role mapping

Grants Nuvo permissions/functions based on group membership at first login

Your IdP → Nuvo

SCIM directory sync

Revokes a user's Nuvo access when they're deactivated/deleted in your directory

Your IdP → Nuvo

Required Attribute Claims

This is where most setup hiccups happen. When configuring your connection, your identity provider must send Nuvo the following. Use the list that matches your protocol.

If you're using SAML, send these attribute statements:

  • givenname — first name

  • surname — last name

  • emailaddress

  • name

  • Unique User ID — in Entra SAML this is objectidentifier; other providers may call it nameidentifier

  • groups — required so Nuvo can map your groups to roles

If you're using OIDC, send these claims:

  • given_name

  • family_name

  • email

  • name (or preferred_username)

  • sub — the unique user identifier

  • groups — required so Nuvo can map your groups to roles

If any of these don't come through correctly, login will fail. The groups claim in particular must be present for role mapping to work.

How Access Is Granted and Revoked

Understanding this up front avoids a common misconception:

  • On a user's first SSO login, Nuvo reads their groups claim and assigns Nuvo roles/permissions based on your group → role mappings. Those roles are saved to their Nuvo account.

  • On every login after that, Nuvo only verifies the user's email. It does not re-read groups or re-run the role mapping.

What this means in practice:

  • Removing a user from a group (or changing their group membership) does not revoke or change their Nuvo access. Group changes don't reach Nuvo.

  • The only way to revoke a user's Nuvo access is to deactivate or delete them in your identity provider. That event syncs to Nuvo via SCIM and automatically removes their access (their session is ended and their roles are stripped).

  • To change a role for future logins, update the mappings in Configure SSO. For a user who's already active, contact Nuvo support to adjust their current access.

⚠️ Set your internal access-management process around this: use IdP deactivation/deletion (not group removal) to remove someone's Nuvo access.

Setup Steps

Step 1 — Kick off SSO setup with Nuvo

Tell your Nuvo contact you'd like to enable SSO, and share:

  • Your identity provider (Okta, Entra ID, Google Workspace, etc.) and whether you'll set up SAML or OIDC.

  • The email of your IT contact who will configure the connection.

Your Nuvo team creates a WorkOS Organization for your company, adds your email domain(s), and sends your IT contact a WorkOS invitation.

Step 2 — Connect your identity provider (your IT contact)

Using the WorkOS invitation, your IT contact:

  1. Selects your identity provider and follows WorkOS's step-by-step instructions for it (provider guides at https://workos.com/docs/integrations).

  2. Configures the SAML or OIDC connection.

  3. Sends the required attribute claims for the chosen protocol (see Required Attribute Claims above) — including groups.

  4. (Optional) Enables Directory Sync (SCIM) in the same flow so deactivations sync to Nuvo automatically.

ℹ️ The WorkOS portal handles the SSO connection only. Group creation happens in your identity provider, not in WorkOS.

Step 3 — Link SSO inside Nuvo

Your Nuvo contact will send you your Organization ID (looks like org_xxxx). A Nuvo Admin then:

  1. Goes to Settings → My Team.

  2. Clicks the ⋯ (three-dot menu) next to Invite, then chooses Configure SSO.

  3. Enters the Organization ID.

Step 4 — Map groups to Nuvo roles (self-serve)

In the same Configure SSO screen, add one mapping per identity-provider group you want to grant access to. For each mapping:

  1. Enter the group name — the literal value your IdP sends in the groups claim (e.g. EID_APP, s406, Sales Reps). If you're unsure of your exact group values, ask your IT contact — these are often AD group names or internal codes.

  2. Select the Nuvo role(s) that group should grant:

    • Permission: Admin

    • Functions: Credit Approver, Credit Clerk, Sales Rep, Sales Manager, Accounts Payable, Accounts Receivable, Trade Reference, IT

  3. Save. Repeat for each group.

Each mapping is evaluated independently, so a user in multiple groups receives the union of all matching roles. No engineering involvement is needed.

Step 5 — Test and go live

  1. Have a user from one of the mapped groups go to the Nuvo login page and enter their work email.

  2. Nuvo recognizes the SSO domain and redirects them to your identity provider to authenticate.

  3. They're returned to Nuvo signed in, with the roles your mappings granted.

Once a test login works, SSO is live for your organization.

Troubleshooting

  • "Unable to find SSO configuration for this email"
    The user's email domain isn't linked to your WorkOS Organization. Confirm the domain is verified and that the Organization ID is entered under Configure SSO.
    ​

  • "This domain is already in use"
    The email domain is already linked to another company in Nuvo. Each domain can belong to only one company — contact Nuvo support.
    ​

  • Login fails / "SSO email mismatch"
    Usually a missing or mis-mapped claim. Re-check the Required Attribute Claims for your protocol — especially that emailaddress / email and the unique-ID claim are sent and that the returned email matches the user's Nuvo email.
    ​

  • A user can log in but has no access (or the wrong access)
    Check your Role Mappings. If no rule matches the user's groups, they receive no roles by default. Confirm your IdP is sending the groups claim and that a mapping references the exact group value.
    ​

  • I removed someone from a group but they can still log in
    Expected — Nuvo only reads groups on a user's first login, so later group changes don't propagate. To revoke access, deactivate or delete the user in your identity provider (this syncs via SCIM). To change a role for an already-active user, contact Nuvo support.
    ​

  • A removed employee still has access
    Confirm Directory Sync (SCIM) is enabled in WorkOS and that your IdP is pushing deactivation/deletion events. Revocation runs automatically once those events flow.

Related Articles
Troubleshooting SSO authentication
Did this answer your question?