Skip to main content

Setting Up SAML Single Sign-On for Patients

Beta — Enterprise plan

SAML single sign-on is in beta and available on the Enterprise plan. Contact Support before rolling it out to a large group, and tell us about anything unexpected.

With SAML 2.0 single sign-on, patients sign in to your CareLaunch site with the account they already have at your identity provider (IdP), with no separate CareLaunch password. SAML is for patient accounts only; staff keep signing in as they do today.

  • First sign-in: CareLaunch creates the patient's account and patient record from what your IdP sends, then opens their portal.
  • Later sign-ins: CareLaunch recognizes the patient by their NameID and updates their record with any details your IdP sends.
  • Where it applies: each site (instance) has its own SAML connection and its own sign-in start URL, so a test site and a production site are two separate registrations in your IdP.

CareLaunch's sign-in service is the SAML service provider. It checks the signature, audience and expiry of every assertion. There is no client ID or client secret to exchange.

If you work at the identity provider, see SAML Guide for Identity Providers.

Before you start​

  • Plan: single sign-on is an Enterprise feature. Other plans see an Enterprise features page in its place.
  • Access: a CareLaunch organization admin opens the site's settings. Someone at your IdP registers the CareLaunch application.
  • Site address: the site needs a CareLaunch subdomain or a custom domain that already serves CareLaunch. SSO returns patients to that address. See Custom Domains.
  • Every patient has their own email address. CareLaunch keys each patient account on email, so two people who share one email can't both sign in.
  • Patients can start from your member portal. Link your portal or app tile to the site's sign-in start URL. CareLaunch sends the sign-in request to your IdP, and a member who's already signed in there comes straight back.
WhoDoes what
Clinic adminOpens the site's Single sign-on page, sends CareLaunch's values to the IdP, enters the IdP's metadata and attribute names, turns SSO on
IdP administratorRegisters CareLaunch as a SAML application, chooses the NameID and attributes, sends the metadata, assigns the members who may sign in

What CareLaunch gives your identity provider​

The site's Single sign-on page shows these values with a copy button beside each. They are fixed for that site. The sign-in start URL is always different for each site. Sites that share your organization's sign-in pool show the same Entity ID and Reply URL, so ask CareLaunch Support if your IdP needs a separate Entity ID for each site.

Value on the pageOther names your IdP may useFormat
Entity IDAudience URI, SP Entity ID, Identifierurn:amazon:cognito:sp:<pool id>
Reply URLAssertion Consumer Service (ACS) URL, Single sign-on URLhttps://<prefix>.auth.us-east-1.amazoncognito.com/saml2/idpresponse
Sign-in start URL (your portal link)Sign on URL (Microsoft Entra ID), app tile linkhttps://<site address>/sso-start, one per address the site is served on

Link your member portal or app tile to the sign-in start URL. It opens CareLaunch, which sends a sign-in request to your IdP. A member already signed in there comes straight back to the same site, so to them it's one click from your portal. Leave your IdP's default RelayState empty.

The page shows the values only after the site's sign-in pool is ready. If it shows Prepare SAML sign-in pool, do that first (step 3 below); the values that appear afterwards don't change when you save.

If your IdP asks for a service provider metadata file instead of typed values, click Download metadata under the Entity ID and Reply URL. It saves carelaunch-saml-metadata.xml with both values in it. CareLaunch doesn't sign its sign-in requests, so the file has no certificate unless the site requires encrypted assertions; then it also holds CareLaunch's encryption certificate (see Encrypted assertions).

What your identity provider gives CareLaunch​

Metadata​

Send one of these:

  • Metadata URL (recommended): an https address. CareLaunch's sign-in service rereads it about every 6 hours, so certificate changes are picked up on their own. The URL must be reachable from the public internet.
  • Metadata XML file: UTF-8, up to 128 KB. It doesn't update on its own (see Certificates and changes).

The metadata must describe exactly one IdP, with an https sign-on endpoint and at least one signing certificate that is valid today. CareLaunch never needs a private key or a standalone certificate file.

Signing and NameID​

  • Sign the assertions. CareLaunch refuses unsigned assertions. Encrypting them as well is optional (see Encrypted assertions).
  • NameID: use a stable ID that belongs to one person, is never reassigned and isn't shared between a subscriber and their dependents, in persistent format. CareLaunch binds the patient's account to it on first sign-in. If it changes later, that patient can't sign in until CareLaunch Support clears the binding.
  • Never use a Social Security number or any other government ID as the NameID or in any attribute.

Attributes​

On the Single sign-on page you type the exact attribute name your IdP sends for each field. Names are case-sensitive.

FieldRequiredFormat CareLaunch accepts
EmailYesA valid email address. It's trusted as verified. It may differ from the NameID.
First nameNoText
Last nameNoText
Date of birthNoYYYY-MM-DD only (an ISO timestamp also works). Any other format, such as MM/DD/YYYY, is dropped.
Phone numberNo10 to 15 digits; punctuation is removed and a leading + is kept
GenderNomale, female, other or unknown (also m, f, unk); other values are dropped
AddressNoOne line of text, or an OIDC-style address object

A field that's dropped doesn't block sign-in; the patient record is simply saved without it. Any other attributes your IdP sends, such as a client or group identifier, are ignored.

Who may sign in​

CareLaunch signs in anyone your IdP sends with a valid assertion and email. Limit access in your IdP, for example by assigning the CareLaunch application only to eligible members. Dependents sign in with their own IdP account and email, not under the subscriber's.

Creating the site​

Skip this if the site patients will sign in to already exists. Each site has its own SAML connection, so create one site for testing and one for production if your IdP has a test environment.

  1. In CareLaunch, go to Administration > Instances and click New.
  2. Enter a Name, and a Patient-Facing Name if patients should see a different one, then click Create.
  3. Under Access & sharing, open Domain and set the site's web address. SSO sends patients back to this address, so set it before you turn on SAML.
  4. Set up the rest of the site (branding, registration, portal) as you would for any site.

Turning on SAML for a site​

  1. In CareLaunch, go to Administration > Instances and open the site.
  2. Under Access & sharing, open Single sign-on. Under Identity Provider, set Provider to SAML 2.0.
  3. If the page shows Prepare SAML sign-in pool, click it. A progress bar runs for about a minute and the settings lock until it finishes. You can leave the page meanwhile. Existing sign-in keeps working.
  4. Under 1. Copy these into your identity provider, copy the Entity ID, the Reply URL and, for your member portal or app tile, the Sign-in start URL. Send them to your IdP administrator, who registers CareLaunch as a SAML application with them. If the IdP wants a metadata file instead, click Download metadata and send that file with the sign-in start URL.
  5. Under 2. Paste your identity provider's metadata, choose Metadata URL and enter the IdP's metadata address, or choose Metadata XML file and upload or paste the metadata.
  6. Under 3. Map your identity provider's attributes, type the IdP's attribute name for Email and for any other fields it sends.
  7. Under Connection Test, click Validate metadata. It shows the IdP's entity ID, its sign-in endpoint and each signing certificate with its expiry date and SHA-256 fingerprint. This checks the metadata only, not a real sign-in.
  8. Turn on Enable SSO at the top of the page, then click Save SSO configuration. If the save is refused, the message says why, for example metadata without a valid signing certificate.

The site's sign-in page now shows Continue with SSO. To turn SAML off, turn off Enable SSO and save; other sign-in options keep working. A site that has its own sign-in pool can't turn SSO off from this page yet; contact CareLaunch Support. Delete SSO Configuration removes the site's own settings, and the site falls back to the organization's.

If you later add a custom domain or change the site's address, contact CareLaunch Support so SSO accepts the new address. Then give the IdP the new sign-in start URL.

Encrypted assertions (optional)​

Turn this on only if your IdP encrypts its assertions, or requires that it does.

  1. Under 1. Copy these into your identity provider, turn on Require encrypted assertions and click Save SSO configuration.
  2. Click Download encryption certificate. It saves carelaunch-saml-encryption.crt. Send it to your IdP administrator, who loads it as the SP encryption certificate. Download metadata now includes the same certificate, so you can send the metadata file instead.
  3. Run the test sign-in below once the IdP is encrypting.

While this is on, CareLaunch refuses any assertion that isn't encrypted with that certificate. So on a site patients already use, sign-in stops working from the moment you save until the IdP encrypts. Set it up before go-live, or agree a time with the IdP. Assertions must still be signed.

The certificate belongs to this site's sign-in. If the site is moved to its own sign-in pool, or its SSO configuration is deleted and set up again, it gets a new certificate, and the IdP needs the new one.

What isn't supported​

Not supportedWhat to do instead
Sign-ins your IdP sends without a request from CareLaunch (unsolicited, IdP-initiated)Link your portal or tile to the sign-in start URL. Members still start from your portal.
Single logoutSigning out of CareLaunch leaves the IdP session as it is
Staff sign-in over SAMLStaff use their usual sign-in; SAML never links to a staff or admin account
Patients without an email addressThe IdP must send an email for every patient who signs in
Routing by an attribute such as a client or group IDEach site has its own connection; register one CareLaunch application per site

Testing the connection​

After saving, run one real sign-in with a test member before you tell patients about it. Validate metadata alone doesn't prove sign-in works.

  1. Open the site's sign-in page in a private browser window and click Continue with SSO, or open the sign-in start URL.
  2. Sign in at your IdP as a test member who has an email address and is assigned to the CareLaunch application.
  3. Stay in the same tab. The test member should land in their CareLaunch patient portal.
  4. In CareLaunch, check that the test patient's record shows the name, date of birth and other fields your IdP sent.
  5. Sign out, then sign in again as the same member. They should reach the same portal and record, not a new one.

If you have a test site and a production site, repeat this on each. Each one is its own registration in your IdP.

Certificates and changes​

  • Metadata URL: when your IdP rotates its signing certificate, publish the old and new certificates side by side for at least 6 hours before retiring the old one. CareLaunch picks up the new certificate within about 6 hours.
  • Uploaded XML: it never refreshes on its own. Upload and save the new metadata before the current signing certificate expires. Validate metadata shows each certificate's expiry date and flags any that expire within 30 days.
  • Switching between URL and uploaded XML replaces the previous metadata.
  • Don't change a patient's NameID at your IdP. A changed NameID blocks that patient's sign-in until CareLaunch Support clears it.

Troubleshooting​

What the patient seesLikely causeFix
An error right after the IdP, or "Invalid or expired authentication session"Entity ID or Reply URL entered wrong at the IdP, unsigned or expired assertion, or a metadata URL the sign-in service can't reachRecheck both values at the IdP. If the metadata URL isn't public, upload the XML instead. Then click Save SSO configuration again.
An error right after the IdP, after turning on Require encrypted assertionsThe IdP isn't encrypting yet, or is using an old certificateDownload the encryption certificate again and have the IdP load it
Sign-in fails when your IdP sends the member straight to CareLaunchThe IdP sent an assertion CareLaunch didn't request (unsolicited sign-ins aren't accepted)Point the portal link or tile at the sign-in start URL, and leave RelayState empty
"Your account couldn't be set up from your organization's sign-in"Usually the assertion had no email, or the Email attribute name doesn't match. Less often, the email already belongs to a staff accountCheck the attribute name (case-sensitive) and that the member has an email
"This email address is already used by a different account"The member's NameID changed, or two members share one emailKeep NameIDs stable and emails unique; contact CareLaunch Support to clear the binding
"Sign-in isn't set up correctly for this site yet"A setting on CareLaunch's side is missingContact CareLaunch Support
"Your sign-in expired or was started in another tab or browser"The sign-in moved between tabs or took too longStart again and stay in one tab
Signed in, but a field is missing from the recordAttribute name doesn't match, or the value's format was dropped (for example a date of birth not in YYYY-MM-DD)Fix the name or the format at the IdP; the next sign-in fills it in
The Continue with SSO button doesn't showNot on the site's own address, or SSO isn't turned onOpen the site at its own address; check Enable SSO is on and saved
Signed in, but the portal shows no patient recordCareLaunch couldn't save the record on this sign-in. The patient stays signed in.Sign out and in again; each sign-in retries. If it keeps happening, contact CareLaunch Support.

Last updated: November 2026