Skip to main content

Single Sign-On (SSO)

Beta — Enterprise plan

Single sign-on is in beta and available on the Enterprise plan. Behavior may change as we gather feedback. Contact Support before rolling it out to a large group, and tell us about anything unexpected.

Single sign-on lets people sign in to a CareLaunch site with an account they already have, instead of a separate CareLaunch password:

  • Google — staff you invite sign in with their Google account.
  • Keycloak / OpenID Connect — people sign in through your organization's OIDC identity provider. For enrollment providers, patients signing in for the first time get a CareLaunch account automatically.
  • SAML 2.0 — patients sign in through your organization's SAML identity provider (patient accounts only; SAML is not available for staff accounts).

SSO can be configured per site (instance) or organization-wide (Enterprise). Each site can use a different provider, inherit the organization default, or use none.

Turning on SSO for a site​

  1. Go to Administration > Instances and open the site.
  2. Open Single sign-on under Access & sharing. (Organizations that are not on Enterprise see an Enterprise features page here instead.)
  3. Turn on Enable SSO, choose the Provider, and fill in its details:
    • Google — use CareLaunch's Google client, or enter your own Client ID and Client Secret.
    • Keycloak — enter the SSO Domain, Realm, Client ID and Client Secret from your provider. Optionally set an IDP Hint (kc_idp_hint) and Additional scopes. Use Test Connection to check them.
    • SAML 2.0 — if the card shows Prepare SAML sign-in pool, click it first. The site needs its own sign-in pool before CareLaunch can show the values for your identity provider. Then register CareLaunch as a SAML application in your identity provider using the Entity ID (Audience URI) and Reply URL (Assertion Consumer Service URL) shown on the card. Choose a Metadata source: enter your provider's metadata URL, or upload or paste its metadata XML. Under Attribute Mapping, enter the name of the SAML attribute your provider sends for each patient field (Email is required). Click Validate metadata to check the configuration. SAML SSO applies to patient accounts only.
  4. Click Save SSO configuration. SSO saves on its own and is not part of the page's unsaved-changes bar.

On most organizations SSO turns on straight away. On some, the site first gets its own sign-in — see below. The page shows a progress bar while this happens (about a minute). The settings are locked until it finishes, and SSO turns on by itself when it's done.

Once SSO is enabled, the sign-in page shows a "Continue with Google" or "Continue with SSO" button depending on the configured provider.

When a site gets its own sign-in​

Some organizations' sign-in can't be linked to Google or an outside provider directly. On those, turning on SSO gives the site its own sign-in, separate from the rest of the organization:

  • Existing accounts are not moved or changed. Everyone else keeps signing in exactly as before, on their usual sites.
  • Accounts from other sites can't sign in on this site, and the site's accounts can't sign in elsewhere.
  • Anyone signed in on this site when it switches over needs to sign in again.
  • From then on, people get an account on this site by being invited to it (see below), or by signing in through its SSO provider if that provider creates accounts.
note

On organizations like these, SSO can only be turned on for individual sites, not organization-wide. You'll see "This organization's sign-in must have SSO enabled per instance" if you try.

Organization-wide SSO (Enterprise)​

SSO can also be configured for the whole organization under Settings > Single Sign-On. Every site uses these settings unless it has its own: saving on a site's Single sign-on card creates settings for that site, and Delete SSO Configuration on that card returns the site to the organization's settings.

Inviting people to a site with SSO​

Google only signs in people who already have an account on the site. Invite each person first:

  1. Go to Administration > Users and click New.
  2. Enter their details. For Google sign-in, the Email Address must be their Google account's email.
  3. In Instance, choose the site they will sign in on.
  4. Choose their roles and click Save Changes.

They receive an invitation email that opens that site's sign-in. They can sign in with Google (or set a password from the invitation).

A staff email address can only be used for one account per organization. If the person already has a CareLaunch account on another site, invite them with a different email address.

The site's web address​

SSO returns people to the site's own web address after they sign in, so the site needs one of:

  • A CareLaunch subdomain (for example your-site.launch.care), or
  • A custom domain that is already serving CareLaunch — its DNS and certificate set up with Support. See Custom Domains.

If you add or change the site's address after turning on SSO, open the site's Single sign-on card and click Save SSO configuration again so the new address is accepted. If the site has no usable address, saving SSO tells you so.

Beta limitations​

  • An organization can set up one site's SSO at a time. If another site is being set up, you're asked to try again when it finishes.
  • There's no self-service way to move a site back to the organization's shared sign-in. Contact Support.
  • Some organization-wide user settings (such as the email confirmation setting) don't yet apply to sites with their own sign-in.

Troubleshooting​

The "Continue with Google" button doesn't appear​

  • Check that you're on the site's own web address — the button only appears on sites where SSO is turned on.
  • If the site was just set up, wait for the progress bar to finish, then reload the sign-in page.

Google sign-in says the account isn't recognized​

The person hasn't been invited to that site, or was invited with a different email address. Invite them to the site with their Google email.

Saving SSO fails with a message about the site's address​

The site has no web address SSO can return to. Give it a CareLaunch subdomain, or finish setting up its custom domain with Support, then save again.

The progress bar shows an error​

Fix what the message describes (or contact Support), then click Save SSO configuration on the site's Single sign-on card again. Setup continues from where it stopped.

Last updated: September 2026