Skip to main content

SSO

Overview​

For SSO (Single Sign-On) we use the OAuth2 'authorization code' flow.

We often call this 'platform SSO', as we make use of the CX platform's OAuth2 support when available, but it can also be used with any OAuth2 provider, like Azure Entra ID SSO

Platform SSO Flow​

The following sequence diagram describes the platform SSO flow:

Flow Steps​

  1. Initiate SSO: Agent requests SSO authentication via /platform/sso
  2. Read Configuration: Deepdesk reads Auth URL and Client ID from platform config
  3. Authorization Request: Deepdesk redirects to platform's authorization endpoint
  4. Agent Authentication: Platform presents login page to agent
  5. Authorization Code: Platform returns authorization code to Deepdesk
  6. Token Exchange: Deepdesk exchanges authorization code for access token using Client ID, Client Secret
  7. User Information: Deepdesk retrieves user information from platform
  8. User Creation/Login: Deepdesk creates or logs in the user
  9. JWT Creation: Deepdesk creates account JWT token
  10. Session Establishment: Deepdesk returns session and access token cookie to agent

User Journey​

  1. Sign-In Initiation: The agent is logged into the CX platform and sees an overlay above the input field with a button "Sign in to Deepdesk"

  2. OAuth Flow: When the agent clicks the link, Deepdesk performs the OAuth flow with the platform (as detailed in the sequence diagram above)

  3. Automatic Login: Upon successful OAuth authentication, the user is automatically logged in to Deepdesk

  4. Return to Platform:

    • The agent returns to the CX platform
    • After refreshing, the agent sees Deepdesk suggestions and can start using the platform

Determining User Identity​

When a user signs in via SSO, we need to determine whether they already exist in Deepdesk. The following diagram shows the steps involved in this process:

For SSO using OIDC, we follow these steps to determine the user:

  • First, extract the user info from the OIDC token:
    • id: User ID from configured key
    • email: Email from configured key
    • first_name: From given_name
    • last_name: From family_name or name
    • roles: From token payload (if available)
  • Then look for an existing user based on this info:
    • First look for an identity record with matching external ID
    • If found, return the associated user
    • If no identity found, search by case-insensitive username
    • Username is derived from (in order):
      • Explicit username
      • Email
      • External ID
  • If no user is found, create a new user with the extracted info

Onboarding Service for Central Callbacks​

For certain OAuth providers (like Salesforce), we maintain a single global OAuth application registration that is shared across all tenant accounts. This approach requires a central callback URL since the OAuth provider can only redirect to pre-registered URIs.

The onboarding service (https://onboarding.deepdesk.com) handles this central callback mechanism:

  1. Receives Authorization Code: The OAuth provider redirects to https://onboarding.deepdesk.com/oauth/callback/ with the authorization code
  2. Determines Target Account: The service identifies which tenant account initiated the SSO flow using state parameters
  3. Forwards to Tenant: The service redirects the user to the appropriate tenant's SSO endpoint with the authorization code
  4. Completes Flow: The tenant account completes the OAuth flow as normal

This central routing allows us to maintain a single OAuth application registration while supporting multiple tenant accounts, reducing administrative overhead for providers that don't support multiple callback URLs or tenant-specific applications.

Extended SSO Flow with Central Callbacks​

The following sequence diagram shows how the SSO flow works when using the central onboarding service callback:

Implementation​

For technical implementation details, see:

See Also​

  • OAuth2 Roles - Automatic role assignment using OIDC claims
  • Magic Link - Email-based passwordless authentication