Single Sign-On (SSO)

Integrate RapiDesq with your organization's identity provider using OpenID Connect (OIDC) or SAML 2.0. This guide covers end-to-end SSO configuration including domain verification, role mapping, just-in-time provisioning, and enforcement with per-user exemptions. Single sign-on is available on the Enterprise plan.

Overview

Single Sign-On allows your team to authenticate with RapiDesq using the same credentials they use for every other corporate application. Instead of managing a separate set of passwords, users sign in through your organization's identity provider (IdP) and are granted access to RapiDesq automatically.

SSO in RapiDesq provides the following capabilities:

RapiDesq supports two industry-standard protocols:

Compatible identity providers include Okta, Azure AD (Microsoft Entra ID), Google Workspace, Auth0, Keycloak, OneLogin, PingFederate, and any other provider that implements the OIDC or SAML 2.0 specifications.

Note — SSO is an Enterprise feature. If you don't see the SSO page in your admin navigation, contact your account manager to enable SSO for your organization.

Prerequisites

Before you begin configuring SSO, confirm that you have the following:

The SSO page (Admin > SSO) is organized into a Login policy section and three tabs: Identity Providers, Domain Mappings, and Role Mappings.

The Single Sign-On admin page showing the login policy controls and the Identity Providers tab The SSO page: login policy at the top, with tabs for identity providers, domain mappings, and role mappings.

Configuring OIDC

OpenID Connect is the recommended protocol for SSO integration. OIDC is simpler to configure than SAML and uses modern REST-based flows. If your identity provider supports both OIDC and SAML, choose OIDC.

Step 1: Register an application in your IdP

Create a new OIDC (or OAuth 2.0 / OpenID Connect) application in your identity provider. The exact steps depend on your IdP:

Step 2: Configure the redirect URI

In your IdP's application settings, set the redirect URI (also called the callback URL or sign-in redirect URI) to RapiDesq's OIDC callback endpoint. The callback is served at the path /api/v1/auth/sso/oidc/callback on your RapiDesq account's API host. This is the endpoint your IdP sends users back to after authentication.

Step 3: Copy your Client ID and Client Secret

After creating the application in your IdP, it will provide you with a Client ID and a Client Secret. Copy both values; you will need them in the next step.

Warning — Treat the Client Secret as a sensitive credential. Do not share it over unencrypted channels or store it in plaintext outside of RapiDesq's SSO configuration. Some IdPs only display the Client Secret once at creation time, so copy it before leaving the page.

Step 4: Configure scopes in your IdP

Ensure that the following OIDC scopes are enabled for the application in your IdP:

If your IdP uses a custom scope or claim for group memberships (used for role mapping), add that scope as well. For example, Okta uses a groups claim, and Azure AD uses a groups optional claim.

Step 5: Create the provider in RapiDesq

In Admin > SSO, on the Identity Providers tab, click Create Provider. The creation wizard walks through Basic Info, protocol configuration, and a final Review step. Enter:

PKCE support

RapiDesq supports PKCE, an additional security layer for the authorization code flow. To enable it, check Use PKCE (Recommended) in the OIDC configuration. Most modern identity providers support and encourage PKCE; ensure that your IdP's application registration also allows or requires it.

Step 6: Verify the sign-in flow

After saving the provider and configuring a verified domain mapping (see below), test the full round-trip by signing in through your IdP in a private browser window. See Testing SSO for the recommended procedure.

Configuring SAML

If your identity provider requires SAML 2.0 or your organization has existing SAML infrastructure, follow these steps to configure SAML-based SSO.

Step 1: Get RapiDesq's Service Provider (SP) details

RapiDesq acts as the SAML Service Provider (SP). Your IdP needs RapiDesq's SP details to establish the trust relationship.

  1. Navigate to Admin > SSO and open the Identity Providers tab.
  2. The Service Provider (SP) Configuration panel shows the values to provide to your IdP:
    • Entity ID (Audience URI) — Also known as Audience URI or Audience Restriction in some IdPs.
    • ACS URL (Reply URL) — Also known as Reply URL, Assertion Consumer Service URL, or Single Sign-On URL.
  3. You can copy these values individually, or click Download Metadata to download the SP metadata XML file and upload it to your IdP — the easiest method, because it includes all required configuration automatically.

Step 2: Create a SAML application in your IdP

In your identity provider, create a new SAML 2.0 application:

When configuring the application, provide the Entity ID and ACS URL from Step 1, or upload the downloaded SP metadata file.

Step 3: Configure attribute mapping in your IdP

Configure your IdP to include the following attributes in the SAML assertion. RapiDesq uses these to identify and provision users:

SAML Attribute Description Required
email or NameID The user's email address. Used as the primary identifier. Yes
firstName / givenName The user's first name. Recommended
lastName / surname The user's last name. Recommended
groups or roles The user's group or role memberships in the IdP. Used for role mapping. Recommended

Step 4: Create the provider in RapiDesq

On the Identity Providers tab, click Create Provider, enter a Provider Name, and select SAML 2.0 as the protocol. You can import your IdP's configuration in one of two ways:

After importing, review the populated fields and make any necessary adjustments. You can also enter the values manually:

Step 5: Configure signing options

Two signing options control the security posture of the SAML exchange:

Tip — Importing from your IdP's metadata (file or URL) is less error-prone than manual entry, and it captures the signing certificate exactly as the IdP publishes it. If your IdP rotates its signing certificate, re-import the metadata to pick up the new certificate.

Domain Mappings & Verification

Domain mappings provide a seamless login experience. When a user enters their email address on the RapiDesq login page, the system checks the domain portion (the part after the @) against your verified domain mappings. If a match is found, the user is automatically redirected to the mapped identity provider without any additional steps.

Adding a domain mapping

  1. Navigate to Admin > SSO and open the Domain Mappings tab. (At least one identity provider must exist before you can add a mapping.)
  2. Click Add Domain Mapping.
  3. Enter the email domain you want to register (for example, example.com). Do not include the @ symbol.
  4. Select the Identity Provider the domain should map to.
  5. Choose a Verification Method (see below) and save. The mapping starts in a Pending Verification state.

Verifying domain ownership

Domain verification proves that your organization owns the domain. This prevents unauthorized parties from claiming your domain and redirecting your users to a malicious IdP. Three verification methods are available:

After completing the step for your chosen method, click Verify. RapiDesq checks for the record, tag, or file and marks the mapping Verified on success. If verification fails, the page shows what was checked, what was expected, and what was found, so you can correct the record.

Note — DNS changes can take up to 48 hours to propagate depending on your DNS provider and TTL settings. If verification fails immediately after adding the record, wait and retry. Meta tag verification may also take a few minutes to succeed after adding the tag.

Multiple domains

Organizations with multiple email domains (for example, yourcompany.com, yourcompany.co.uk, and subsidiary.com) can add a mapping for each and point them at the same identity provider. Each domain must be verified independently.

Users with non-SSO domains

Users whose email domains are not mapped for SSO continue to use standard password-based login (subject to your login policy — see Enforcing SSO). This is common for external collaborators, contractors, or partners who do not authenticate through your corporate IdP.

Role Mapping

Role mappings define how roles from your identity provider map to RapiDesq roles. When a user signs in via SSO and their account is provisioned, their IdP roles are matched against these mappings to determine the RapiDesq role they receive. This eliminates the need to manually configure each user.

RapiDesq reads role information from the standard role and group claims in the IdP response — for OIDC this includes the roles and groups claims (including Keycloak-style realm and client role claims); for SAML, the group/role attributes in the assertion.

Configuring role mappings

Role mappings are configured per identity provider:

  1. On the Identity Providers tab, click Role Mappings on the provider's row. This opens the Role Mappings tab for that provider.
  2. Click Add Mapping.
  3. Configure the mapping:
    • External Role (from IdP) — The role or group name exactly as it appears in your IdP. For example: admin, supervisor, support-user.
    • Internal Role — The RapiDesq role to assign when the external role matches:
      • Admin — Administrative access including tenant configuration and settings.
      • Supervisor — Team management, queue oversight, reporting, and user supervision.
      • User — Handle conversations, manage tickets, and interact with contacts.
      • Internal User — Internal collaboration features such as team chat, without customer-facing capabilities.
    • Priority — A numeric value (default 0). When a user matches multiple mapping rules, higher priority mappings take precedence.
  4. Click Create.

To change the external role of an existing mapping, delete the mapping and recreate it; the internal role and priority can be edited in place.

Example mappings

External Role (from IdP) Internal Role Priority
rapidesq-admins Admin 100
support-supervisors Supervisor 80
support-users User 60
all-employees Internal User 10

In this example, a user who belongs to both rapidesq-admins and all-employees would be assigned the Admin role because it has the higher priority (100 vs 10).

Default role

Users who sign in via SSO without matching any mapping — including tenants with no role mappings configured at all — are assigned the User role by default. The Role Mappings tab shows a warning when no mappings are configured so this default doesn't surprise you.

Warning — Role mappings determine the role assigned when an SSO account is provisioned. Set up your mappings before rolling SSO out broadly, so first-time sign-ins receive the correct role rather than the User default.

Just-In-Time (JIT) User Provisioning

Just-In-Time provisioning automatically creates user accounts in RapiDesq the first time an SSO user signs in. This eliminates the manual step of inviting or creating users ahead of time.

How JIT provisioning works

  1. A user navigates to the RapiDesq login page and enters their email address.
  2. The domain portion of the email matches a verified domain mapping, and the user is redirected to the mapped IdP.
  3. The user authenticates with the IdP.
  4. The IdP sends an assertion (SAML) or ID token (OIDC) back to RapiDesq with the user's claims. RapiDesq validates that the email domain returned by the IdP matches the provider's verified domain mapping.
  5. RapiDesq checks whether a user account exists for this identity. If not, a new account is created automatically:
    • Email is set from the email claim.
    • Name is populated from the given_name, family_name, and name claims (OIDC) or the first/last name attributes (SAML).
    • Role is assigned based on the role mapping rules. If no mapping matches, the User role is used.
  6. The user is logged in and has immediate access to RapiDesq based on their assigned role.

Existing accounts and account linking

If a user already has a RapiDesq account with a password and then signs in via SSO with the same email address, RapiDesq does not silently merge the identities. The user is asked to confirm the link by entering their existing RapiDesq password. This prevents account takeover through a misconfigured or malicious IdP. Accounts that were originally created by SSO link automatically.

Subsequent logins

On each subsequent login, RapiDesq refreshes the user's first and last name from the IdP claims, so name changes in your directory are reflected in RapiDesq. Role changes are applied through RapiDesq's user management — update the user's role in Admin > User Management if their responsibilities change after provisioning.

Note — JIT provisioning only creates accounts when users actively authenticate. It does not pre-create accounts for all users in your IdP directory. If you need to provision users in advance (for example, to assign them to teams before their first login), you can still invite users manually through Admin > User Management.

Testing SSO

Thoroughly test your SSO configuration before rolling it out to your entire organization. Follow these steps:

1. Test in a private browser window

Open an incognito or private browser window (this ensures no existing sessions interfere with the test):

  1. Navigate to your RapiDesq login page.
  2. Enter an email address with your verified SSO domain.
  3. Verify that you are redirected to your identity provider's login page.
  4. Authenticate with your IdP credentials.
  5. Verify that you are returned to RapiDesq and logged in successfully.
  6. Check that your role and permissions are correct by navigating to your profile or checking available menu items.

2. Test JIT provisioning

Create a test user in your IdP who does not yet have an account in RapiDesq. Have them sign in via SSO and verify:

3. Test role mapping

Test with new users who belong to different IdP groups to verify that each mapping produces the correct RapiDesq role:

4. Keep a backup admin session

While testing, always keep an active admin session open in your regular (non-incognito) browser. If something goes wrong with the SSO configuration, you can use this session to make corrections without needing to authenticate via SSO.

Warning — Never enable SSO enforcement until you have successfully completed all the testing steps above.

Enforcing SSO

After testing is complete and SSO is working reliably, you can require SSO so that password-based login is blocked. RapiDesq provides enforcement at two levels: a per-domain requirement and a tenant-wide login policy.

Per-domain enforcement

Each domain mapping has a Require SSO option. When enabled, users with that email domain must authenticate via SSO; password login is blocked for them. Domains without the requirement show SSO as Optional, meaning users are routed to SSO automatically but can still use a password where the login policy allows it.

Tenant login policy

The Login policy section at the top of the SSO page controls whether users in your tenant must sign in via SSO. Three settings are available:

Owner accounts are always exempt from SSO enforcement to prevent lockouts: if your IdP is misconfigured or experiences an outage, owners can still sign in with a password and adjust the policy.

Switching to Require SSO for all users is deliberately high-friction: a confirmation dialog warns that every non-owner user will be blocked from password login, and you must type REQUIRE to confirm.

Per-user exemptions

When using Require SSO with exceptions, the Per-user exemptions list controls who may continue to sign in with a password. Add users by searching by email or name. Use exemptions sparingly — they are intended for service accounts and edge cases, not as a general escape hatch.

Warning — Before requiring SSO, confirm that at least one owner account can sign in successfully. Owners are your break-glass recovery path if the IdP becomes unavailable.

Managing Multiple Providers

You can configure more than one identity provider — useful during an IdP migration or for organizations with multiple directories. Each provider can be enabled or disabled independently, and one provider can be designated the Primary Provider using Set as Primary. Domain mappings determine which provider each email domain routes to.

Tips & Best Practices