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.

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.

Prerequisites

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

Note — If you do not have DNS access, you can still configure SSO without domain-based auto-detection. Users will use a direct SSO login link instead of being automatically routed by email domain.

Configuring OIDC

OpenID Connect is the recommended protocol for SSO integration. OIDC is simpler to configure than SAML, uses modern REST-based flows, and supports automatic endpoint discovery. 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 the value shown in RapiDesq.

To find your redirect URI:

  1. In RapiDesq, navigate to Admin > Security > Single Sign-On.
  2. Select OIDC as the protocol.
  3. Copy the Redirect URI displayed on the page.

Paste this URI into your IdP's redirect/callback URL field. This is the endpoint that your IdP will send 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 GroupMember.Read.All or a groups optional claim.

Step 5: Enter OIDC settings in RapiDesq

Back in RapiDesq's SSO configuration page, enter the following:

RapiDesq automatically discovers all required OIDC endpoints (authorization, token, userinfo, and JWKS) by fetching your issuer's /.well-known/openid-configuration document. You do not need to enter these endpoint URLs manually.

Auto-Discovery — When you enter the Issuer URL, RapiDesq fetches {issuer}/.well-known/openid-configuration and automatically configures the authorization endpoint, token endpoint, userinfo endpoint, and JSON Web Key Set (JWKS) URI. If the discovery document cannot be fetched, double-check that the Issuer URL is correct and accessible from the internet.

PKCE Support

RapiDesq supports PKCE (Proof Key for Code Exchange), an extension to the OAuth 2.0 authorization code flow that provides an additional layer of security. When PKCE is enabled, RapiDesq generates a cryptographic code challenge for each authentication request, which prevents authorization code interception attacks.

PKCE is recommended when:

To enable PKCE, check the Enable PKCE option in the OIDC configuration section. Ensure that your IdP's application registration also allows or requires PKCE. In Okta, this is enabled by default. In Azure AD, set the application's Allow public client flows if needed, though confidential clients with PKCE typically work without additional configuration.

Step 6: Test the connection

Click the Test Connection button. RapiDesq will open a new window, redirect you to your IdP, and attempt a full authentication round-trip. If the test succeeds, you will see a confirmation message. If it fails, check the error details and verify your Issuer URL, Client ID, Client Secret, and redirect URI.

Once the test passes, click Save to activate the OIDC configuration.

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) metadata

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

  1. Navigate to Admin > Security > Single Sign-On.
  2. Select SAML 2.0 as the protocol.
  3. You have two options:
    • Download SP metadata XML — Download the full metadata file and upload it to your IdP. This is the easiest method because it includes all required configuration automatically.
    • Copy individual values — Copy the Assertion Consumer Service (ACS) URL and SP Entity ID and enter them manually in your IdP. Use this method if your IdP does not support metadata file upload.

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 following values from RapiDesq (or upload the 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: Configure certificate and signing

SAML assertions can be digitally signed and optionally encrypted to ensure integrity and confidentiality:

Most IdPs handle certificate configuration automatically when you upload RapiDesq's SP metadata. If you are configuring manually, ensure that the signing certificate from your IdP is included in the metadata you provide to RapiDesq.

Step 5: Provide IdP metadata to RapiDesq

Back in RapiDesq's SSO configuration page, provide your IdP's metadata in one of two ways:

The metadata contains your IdP's Entity ID, Single Sign-On endpoint URL, and signing certificate. RapiDesq parses all of this automatically.

Step 6: Test the connection

Click the Test Connection button. RapiDesq will initiate a SAML authentication request, redirect you to your IdP, and validate the assertion returned. If the test succeeds, you will see a confirmation with the attributes received from the assertion. If it fails, check the error details for issues such as mismatched Entity IDs, invalid ACS URLs, or certificate problems.

Once the test passes, click Save to activate the SAML configuration.

Tip — Prefer providing the IdP Metadata URL instead of uploading a static XML file. When your IdP rotates its signing certificate, the metadata URL ensures RapiDesq picks up the new certificate automatically, avoiding authentication failures during rotation.

Domain Registration & Verification

Domain-based auto-detection provides 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 registered SSO domains. If a match is found, the user is automatically redirected to the correct identity provider without any additional steps.

Registering a domain

  1. Navigate to Admin > Security > Single Sign-On > Domains.
  2. Click Add Domain.
  3. Enter the email domain you want to register (for example, yourcompany.com). Do not include the @ symbol.
  4. Click Save. The domain will be added in an Unverified 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.

  1. After adding the domain, RapiDesq generates a unique DNS TXT record value (for example, rapidesq-verification=abc123def456).
  2. Log in to your DNS provider (such as Cloudflare, Route 53, GoDaddy, or your internal DNS management system).
  3. Add a new TXT record for your domain:
    • Host/Name: @ or leave blank (depending on your DNS provider)
    • Type: TXT
    • Value: The verification string provided by RapiDesq
  4. Return to RapiDesq and click Verify. RapiDesq performs a DNS lookup to confirm the TXT record exists.
Note — DNS changes can take time to propagate, typically between a few minutes and up to 48 hours depending on your DNS provider and TTL settings. If verification fails immediately, wait and retry.

Multiple domains

Organizations with multiple email domains (for example, yourcompany.com, yourcompany.co.uk, and subsidiary.com) can register all of them and link them to the same SSO configuration. Each domain must be verified independently.

Users with non-SSO domains

Users whose email domains are not registered for SSO continue to use standard password-based login. This is common for external collaborators, contractors, or partners who do not authenticate through your corporate IdP. Domain registration only affects users with matching email domains; all other users are unaffected.

Role Mapping

Role mapping lets you automatically assign RapiDesq roles to SSO users based on their group memberships, roles, or other claims in your identity provider. This eliminates the need to manually configure permissions for each user.

Configuring role mappings

  1. Navigate to Admin > Security > Single Sign-On > Role Mapping.
  2. Click Add Mapping.
  3. Configure the mapping:
    • IdP Claim/Group — The value from your IdP that identifies a group or role. This is the value sent in the groups, roles, or custom claim. For example: admin, support-agents, supervisors.
    • RapiDesq Role — The role to assign when the claim matches. Available roles:
      • TENANT_ADMIN — Full administrative access including security settings, billing, and tenant configuration.
      • SUPERVISOR — Team management, queue oversight, reporting, and agent supervision.
      • AGENT — Handle conversations, manage tickets, and interact with contacts.
      • INTERNAL_USER — Internal collaboration features such as internal chat, without customer-facing capabilities.
    • Priority — A numeric priority value. When a user matches multiple mapping rules (for example, a user who belongs to both the admin and support-agents groups), the mapping with the highest priority wins.
  4. Click Save.

Example mappings

IdP Group/Claim RapiDesq Role Priority
rapidesq-admins TENANT_ADMIN 100
support-supervisors SUPERVISOR 80
support-agents AGENT 60
all-employees INTERNAL_USER 10

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

Default role

You can configure a default role that applies to any SSO user who does not match any mapping rule. This ensures that every user who authenticates via SSO receives at least a baseline set of permissions, even if their IdP groups are not covered by your mapping configuration.

To set the default role, select a role in the Default Role dropdown at the top of the Role Mapping page.

Warning — Choose the default role carefully. If JIT provisioning is enabled, any user who authenticates via SSO for the first time will be created with this role if they do not match any specific mapping. Setting the default role to TENANT_ADMIN would grant full administrative access to unmatched users.

Role re-evaluation on login

Role mapping is re-evaluated on every login. If a user's group memberships change in your IdP (for example, an agent is promoted to supervisor and added to the support-supervisors group), the updated role is applied the next time the user signs in to RapiDesq. There is no need to manually update roles in RapiDesq; changes in your IdP are reflected automatically.

Tip — Use group-based role mapping to fully automate user provisioning. When you add someone to the appropriate group in your IdP, they will be assigned the correct role in RapiDesq on their next login. Combine this with JIT provisioning so that new employees are set up in RapiDesq automatically on their first sign-in.

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 SSO domain, and the user is redirected to the 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.
  5. RapiDesq checks whether a user account exists for this email. If not, a new account is created automatically:
    • Email is set from the email claim.
    • Name is populated from the name, given_name, and family_name claims (OIDC) or the firstName and lastName attributes (SAML).
    • Role is assigned based on the role mapping rules. If no mapping matches, the default role is used.
  6. The user is logged in and has immediate access to RapiDesq based on their assigned role.

Subsequent logins

On each subsequent login, RapiDesq updates the user's profile from the IdP claims. If the user's name or other profile attributes change in the IdP, those changes are reflected in RapiDesq on the next sign-in. Similarly, role assignments are re-evaluated against the current role mapping rules on every login.

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 or queues before their first login), you can still invite users manually through Admin > Team Management.

Testing SSO

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

1. Test the connection

In the SSO configuration page, click Test Connection. This performs a complete authentication round-trip with your IdP and reports whether the connection succeeded or failed. Address any errors before proceeding.

2. 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 registered 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.

3. 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:

4. Test role mapping

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

5. 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. Always maintain at least one local admin account with password-based login as a recovery mechanism.

Enforcing SSO

After testing is complete and SSO is working reliably, you can enforce SSO for all users on registered domains. Enforcement means that password-based login is disabled for those users, and they must authenticate through the IdP.

Enabling enforcement

  1. Navigate to Admin > Security > Single Sign-On.
  2. In the Enforcement section, toggle Require SSO for registered domains to enabled.
  3. Click Save.

What enforcement changes

Backup admin accounts

It is critical to maintain at least one admin account that uses a non-SSO email domain (or has SSO enforcement exempted) as a break-glass recovery mechanism. If your IdP experiences an outage, this account allows you to sign in and disable SSO enforcement until the IdP is restored.

Warning — Before enabling enforcement, confirm that your backup admin account can sign in with password-based login using a non-SSO email domain. If all admin accounts are on SSO-enforced domains and your IdP goes down, you will be locked out.

Tips & Best Practices

Tip — For large organizations, consider rolling out SSO in phases: start with a pilot group using domain-based auto-detection but without enforcement, verify that JIT provisioning and role mapping work correctly, and then enable enforcement once you are confident in the configuration.