Skip to content
Patient Copilot Help Center

Setting Up Single Sign-On (SSO) on Patient Copilot

Patient Copilot supports Single Sign-On (SSO) using the OpenID Connect (OIDC) protocol. With SSO, agencies can allow users to log in to Patient Copilot with their organizational credentials, improving security and simplifying access. Currently, Patient Copilot supports OIDC only. SAML is not yet supported, but it is part of the future roadmap. ## ## Navigation and Access - Go to Labs page and enable Single Sign On (SSO) feature flag for your agency - ⚠️ Only needed before 3rd November, after that the feature will be enabled by default - Navigate to: Company Settings → Single Sign-On (SSO) - All agency admins can view and configure SSO. - You’ll see an “Enable SSO” CTA to initiate the setup flow. ## Prerequisites Before enabling SSO, two conditions must be met: 1. Your agency must be on the plan. 2. A Whitelabel domain must already be configured. ## Setup Flow ### Step 1: Client ID & Secret - Method of Authentication: Locked to OIDC (SAML will be supported in the future). - Client ID: The identifier issued by your IdP - Secret: A secure key generated by your IdP, used by Patient Copilot to prove its identity when making requests. - ℹ️ See FAQs ### Step 2: OIDC Configuration You can configure this automatically or manually: 1. Automatic Discovery (recommended) - Select Yes for “Use OIDC Config URL.” - Enter the OIDC Config URL from your IdP (usually: https:///.well-known/openid-configuration). 2. - Enter the following endpoints from your IdP: - User Info Endpoint - Scopes: Define what data Patient Copilot can retrieve. At minimum, openid is required. Adding profile and email is recommended. - - If not, it should follow this pattern: https:///login/sso - This Redirect URL must be whitelisted in your IdP configuration. - ⚠️ Editing the Redirect URL is not advisable unless correcting it to match the correct pattern. - ℹ️ See FAQs ### Step 3: User Details Mapping We need to link the user information from your IdP to Patient Copilot so the same user is correctly recognized across both systems. - Remote ID Field (required): The unique user ID from your IdP (e.g. sub in OIDC, oid in Azure). Ensures consistent identification of the same user across platforms. - ID Field (optional): The Patient Copilot user ID. Use if you want to map directly to existing Patient Copilot users. - Email Field: The user’s email address field in your IdP (e.g. email, userPrincipalName). Helps confirm and map user identities. - Please make sure that this field is unique to each user in your system. - This is what we will use to update user email in our data. - Email Verified Field (required): Ensures the email has been validated by your IdP. Prevents unverified or spoofed accounts from accessing Patient Copilot. - ℹ️ See FAQs ### Step 4: Review & Finish - Double-check all entries. - After completing the setup, you’ll see three collapsible sections: 1. SSO Configuration – Displays the configuration you entered. 2. Test Status – Allows you to run an automated test to validate the setup. Until a test passes successfully, you cannot enable SSO. 3. Additional Settings – Includes toggles to enable SSO for the agency and optionally hide other login methods (Email and Google). - Proceed to testing. ## Testing and Enabling SSO - After configuring SSO, testing the config is mandatory. - Unless a successful test is carried out, SSO Toggle cannot be turned on. - - In the test section, click on “Start Test” button to initiate a new Test - Or, Click on the three dotted menu from top right, click on “Test Configuration” option. - This will mimic SSO Login flow, take the tester to IdP, prompt you to login. - Once done, this will redirect you back to the Company Settings SSO tab with updated test status. - If successful, you can proceed to enabling SSO. If failed, you will see some error message to prompt what could be wrong. A list of common errors has been attached. - If there are any issues in the IdP Config, you will see the errors with your IdP. - NOTE: if the SSO Config is updated after performing a test, all the tests will be marked as “EXPIRED”. The test will no longer be considered valid, all your SSO toggles will get reset. This will require you to perform a new Test to enable SSO for your agency again. ℹ️ Troubleshooting Common Errors ## Editing or Deleting an Existing Configuration - Editing an SSO config invalidates prior test results and disables SSO by default. You must re-test and re-enable. - The Hide other login options toggle will not work until SSO is enabled. - Deleting an SSO config (from the three-dotted menu): - Resets additional settings. - Disables SSO for all users. ## Provider-Specific Guides ### Auth0 - Create a Regular Web Application in Auth0.

  • Copy Client ID and Secret into Patient Copilot.
  • Add Patient Copilot Redirect URL to Auth0 Allowed Callback URLs.
  • Config endpoint → https://YOUR_DOMAIN/.well-known/openid-configuration
  • Scopes → openid profile email
  • Mapping: Remote ID → sub, Email → email, Email Verified → email_verified ### Azure Active Directory (Entra ID) - Azure Portal → App registrations → New registration.
  • Add Patient Copilot Redirect URI.
  • Copy Application (Client) ID → Patient Copilot Client ID.
  • Create Client Secret → Patient Copilot Secret.
  • Copy OpenID metadata document URL from Endpoints → Patient Copilot Config field.
  • Add permissions: openid, profile, email.
  • Mapping: Remote ID → sub, Email → userPrincipalName, Email Verified → email ### Okta - Okta Admin → Applications → Create App Integration.
  • Select OIDC - OpenID Connect, type = Web Application.
  • Add Patient Copilot Redirect URL under Login redirect URIs.
  • Copy Client ID and Secret → Patient Copilot.
  • Use Okta metadata URL: https:///.well-known/openid-configuration
  • Assign groups/users.
  • Mapping: Remote ID → sub, Email → email, Email Verified → email_verified ## Current Limitations - Currently supports login only. - New users cannot sign up with SSO — they must already exist in Patient Copilot. - ℹ️ [How to Add SSO ready Users to Highlevel?](#How-do-I-add-users-from-my-SSO-identity-provider’s-(IDP)-user-database-to-Patient Copilot?) ## Troubleshooting Common Errors

    Error Message

    Cause

    How to Fix

    “Something went wrong, please try again.”

    Patient Copilot couldn’t fetch user details from your IdP. May be incorrect endpoints or temporary IdP downtime.

    Verify OIDC Config URL/endpoints, confirm IdP app is active, retry later.

    “Email is not verified, please contact your admin.”

    The email_verified attribute is missing or false.

    Ensure your IdP includes email_verified = true in the ID token.

    “remoteIdField is not configured properly, please contact your admin.”

    The Remote ID (e.g. sub, oid) is missing or unmapped.

    Update your config with a valid unique identifier field.

    “emailField or idField is not configured properly, please contact your admin.”

    Either Email or ID Field mapping is invalid.

    Provide a valid Email Field (e.g. email, userPrincipalName) or ID Field.

    “No user found with this email.”

    The IdP user does not exist in Patient Copilot.

    Make sure the user exists within Patient Copilot and that you have added externalUserId for the existing users.

    “You are not authorized to access this account. Please contact your admin.”

    The user is missing a valid sub-account association.

    Ensure the user is linked to a subaccount in Patient Copilot.

    “Failed to initiate SSO test.”

    The backend could not start the test flow.

    Retry. If it persists, email support with your relationship number.

    ## FAQs ### How do I add users from my SSO identity provider’s (IDP) user database to Patient Copilot? SSO in Patient Copilot currently supports login only — it does not automatically create new users. To ensure your users can log in via SSO, you’ll need to add them to Patient Copilot before they attempt to sign in. #### Steps to add users 1. Create a Private Integration Token with the Create or Edit Users scope enabled. 2. Use the Create Users API or Update Users API for SSO to add or update users in Patient Copilot. 3. When creating users, set the parameter externalUserId to match the user’s unique ID from your IdP. #### Why this matters - Patient Copilot matches users based on their externalUserId (Remote ID). - If a user’s email changes in your IdP, but not in Patient Copilot, login may fail because the system won’t find a matching email. - However, if externalUserId (or SSO Remote ID) is configured, Patient Copilot will still recognize the user and automatically update their email the next time they log in. #### Behind the scenes (for context) When a user logs in via SSO: - Patient Copilot first looks for a user with a matching SSO Remote ID. - If none is found, it searches by email + company ID. - If still not found, login fails. When creating or updating users with the Create Users API / Update Users API, you can also pass platformLanguage to persist the user’s UI language at provisioning time. This reduces manual per-user setup. ℹ️ To avoid this, always include the SSO Remote ID when creating or updating users via API — especially if your users’ emails are likely to change in your IdP. ### Mandatory Fields - Client ID: Tells Patient Copilot which app in your IdP to connect to. - Secret: Confirms that requests to your IdP are coming from Patient Copilot. - Auth Method (OIDC): Authentication protocol (locked to OIDC). ### OIDC Configuration - OpenID Config URL: Supplies all endpoints automatically. - Authorization URL / Token Endpoint / User Info Endpoint: Manual entry option. - Scopes: At minimum openid; recommended openid profile email. - - If missing: https:///login/sso - Must be whitelisted in IdP. Do not edit unless correcting the format. ### User Details Mapping - Remote ID Field: Uniquely identifies the user across both platforms (sub/oid). - ID Field: Optional — Patient Copilot user ID for direct mapping. - Email Field: Maps user email from IdP. - Email Verified Field: Ensures the email is trusted; required for security. ### Updating User Email in the IdP - Patient Copilot relies on the externalUserId (Remote ID). - If a user’s email is updated in the IdP, Patient Copilot will automatically update it on the next login. ### I Got Redirected to Login Screen After Starting SSO Test - This is absolutely normal. - This happens when the user testing is visiting the WL domain for the first time and has never logged in before - Or, had logged out from the domain. - This will not impact your test status. The test has been executed as it should. - If you perform the test again after logging in, you will be able to see the entire flow ### Controlling Who Can Configure or Enable SSO - Current behavior: All agency admins can view, configure, enable, or disable SSO in Patient Copilot. - Future roadmap: Granular permissions will allow super admins to control which agency admins can manage SSO. ## Scopes Explained Scopes determine what information Patient Copilot can request from your IdP. They are critical for proper user mapping and authentication.

    Scope

    What it does

    How Patient Copilot uses it

    Example

    openid (mandatory)

    Returns the user’s unique identifier (sub).

    Links the user to their Remote ID.

    Required for all OIDC logins.

    profile

    Returns basic profile info such as name, given_name, family_name.

    Can enrich user data in Patient Copilot (e.g. display name).

    Helpful if you want names auto-synced, not just email.

    email

    Returns the user’s email and email_verified flag.

    Maps to Patient Copilot’s Email Field and ensures trusted login.

    Allows Patient Copilot to automatically update a user’s email if changed in IdP.

    groups / roles (provider-dependent)

    Returns group/role membership.

    Could be used for role-based access or subaccount mapping (future).

    If configured in Okta/Azure, lets you enforce “only members of group X can access Patient Copilot.”

    offline_access (optional)

    Returns a refresh token for long-lived sessions.

    Not supported in Patient Copilot

    Not supported in Patient Copilot

    Was this article helpful? That’s Great! Thank you for your feedback Sorry! We couldn’t be helpful Thank you for your feedback Feedback sent We appreciate your effort and will try to fix the article