SAML Guide for Identity Providers
This guide is for the identity provider (IdP) team connecting members to a clinic's CareLaunch site. Your members sign in to that site with the account they already have with you. You register CareLaunch as a SAML 2.0 service provider application; the clinic turns the connection on in CareLaunch (see Setting Up SAML Single Sign-On for Patients).
At a glance
| Item | CareLaunch's requirement |
|---|---|
| Protocol | SAML 2.0, with CareLaunch as the service provider (SP) |
| Who signs in | Patients (your members) only, not clinic staff |
| Sign-in flow | Your member portal links to CareLaunch's sign-in start URL. CareLaunch sends you a sign-in request and you answer it, so a member already signed in with you goes straight through. Assertions CareLaunch didn't request (unsolicited, IdP-initiated) are refused. |
| Sign-in request to you | HTTP-Redirect binding to your https sign-on endpoint |
| Response to CareLaunch | HTTP-POST to CareLaunch's Reply URL |
| Signing | Assertions must be signed |
| Encryption | Optional. If the clinic turns on encrypted assertions, encrypt every assertion with CareLaunch's encryption certificate; unencrypted ones are then refused. Otherwise send them unencrypted (the connection is https). |
| NameID | Persistent, stable member ID; never an SSN |
| Required attribute | |
| Single logout | Not supported |
| Client ID or secret | None: the trust is your metadata and signing certificate |
| SP certificate | Only for encryption. CareLaunch doesn't sign its sign-in requests, so leave request-signing fields empty. If encryption is on, load CareLaunch's encryption certificate as the SP encryption certificate. |
Values CareLaunch gives you
The clinic copies these from its CareLaunch site's Single sign-on page and sends them to you. Each site has its own sign-in start URL, so a test site and a production site are two separate applications on your side. Sites that share one CareLaunch sign-in pool show the same Entity ID and Reply URL; if your IdP needs a unique Entity ID per application, ask the clinic to check with CareLaunch Support.
| Value | Other names |
|---|---|
| Entity ID | Audience URI, SP Entity ID, Identifier |
| Reply URL | Assertion Consumer Service (ACS) URL, Single sign-on URL |
| Sign-in start URL (your portal link) | Sign on URL, portal or app tile link |
| Encryption certificate (only if encryption is on) | SP encryption certificate, assertion encryption key |
The Entity ID looks like urn:amazon:cognito:sp:us-east-1_XXXXXXXXX, and the Reply URL ends in /saml2/idpresponse. Enter both by hand in your SAML application, or ask the clinic for CareLaunch's SP metadata file, which it downloads from its Single sign-on page. The file has no certificate in it unless the site requires encrypted assertions; then it includes CareLaunch's encryption certificate. The clinic can also send that certificate on its own as a .crt file.
Link your member portal or app tile to the sign-in start URL. That's how members sign in from your side: CareLaunch sends a sign-in request to your sign-on endpoint, and your IdP answers it. Leave the default RelayState empty, and don't post assertions to the Reply URL without a request, because CareLaunch refuses them.
What we need from you
Send these to the clinic for each application (test and production):
- Your IdP metadata: a metadata URL (https, reachable from the public internet; preferred, because certificate changes are picked up on their own) or the metadata XML file (UTF-8, up to 128 KB). It must describe one IdP, with an https sign-on endpoint and at least one signing certificate that is valid today. Never send a private key.
- The attribute names your assertion uses for email and any of the optional fields listed below. Names are case-sensitive.
- The NameID you'll send (a per-person ID, persistent format), and confirmation that your IdP answers CareLaunch's sign-in request.
- A test member with an email address, assigned to the test application, so the clinic can run a real sign-in.
- A contact on your team for certificate changes and sign-in problems.
NameID and attributes
NameID: send 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 member's account to it on first sign-in and recognizes them by it afterwards. If it changes, that member can't sign in until CareLaunch Support clears the old binding. Never use a Social Security number or any other government ID, in the NameID or any attribute.
| Field | Required | Format CareLaunch accepts |
|---|---|---|
| Yes | A valid email address, unique to the member. It may differ from the NameID. CareLaunch treats it as verified. | |
| First name | No | Text |
| Last name | No | Text |
| Date of birth | No | YYYY-MM-DD (an ISO 8601 timestamp also works). Other formats such as MM/DD/YYYY are ignored. |
| Phone number | No | 10 to 15 digits; punctuation is removed and a leading + is kept |
| Gender | No | male, female, other or unknown (or m, f, unk); other values are ignored |
| Address | No | One line of text, or an OIDC-style address object (street_address, locality, region, postal_code) |
CareLaunch updates the member's record from these values at every sign-in. A value in the wrong format doesn't block sign-in; it's just not saved. Other attributes, such as a client, group or plan identifier, are ignored.
Who may sign in
CareLaunch lets in anyone you send with a valid, signed assertion that includes an email. It doesn't check eligibility itself, so:
- Restrict access on your side, for example by assigning the CareLaunch application only to eligible members, or only to subscribers if dependents shouldn't have access.
- Dependents sign in with their own account at your IdP, their own NameID and their own email. Two people who share one email can't both have a CareLaunch account.
- Removing access: unassign the member at your IdP. They can't start a new sign-in after that. A CareLaunch session they already have open isn't ended by this; the clinic can deactivate the account in CareLaunch if access must stop at once.
Testing, going live and certificate changes
- Set up the test application with the test site's values, and send the clinic your metadata and attribute names.
- The clinic enters them on its CareLaunch site and turns sign-in on.
- Together, run a sign-in with your test member: start from your test portal link to the test site's sign-in start URL (or the site's sign-in page and Continue with SSO), sign in at your IdP, and confirm the member lands in their CareLaunch portal with the right name and details.
- Sign out and sign in again as the same member. They should reach the same record, not a new one.
- Repeat with the production application and the production site's values.
Encryption: if you encrypt assertions, the clinic turns encryption on and sends you the certificate before step 3. CareLaunch refuses unencrypted assertions from then on. The certificate is per site, and a site gets a new one if its sign-in is set up again, so encrypt with the one the clinic sends for that site.
Certificate rotation: if you gave a metadata URL, publish the old and new signing certificates side by side for at least 6 hours before retiring the old one. CareLaunch rereads the URL about every 6 hours. If you gave an XML file, send the clinic the new file before the current certificate expires, because an uploaded file never updates on its own.
Common problems
| What the member sees | Likely cause on your side |
|---|---|
| An error right after signing in at your IdP | Entity ID or Reply URL entered wrong, assertion unsigned or expired, a metadata URL that isn't reachable from the internet, or (with encryption on) an assertion not encrypted with the site's current certificate |
| Sign-in fails when your portal sends the member straight to CareLaunch | Your IdP posted an assertion CareLaunch didn't request; point the portal link at the sign-in start URL instead and leave RelayState empty |
| "Your account couldn't be set up from your organization's sign-in" | No email in the assertion, or the attribute name doesn't match what the clinic entered |
| "This email address is already used by a different account" | The member's NameID changed, or two members share one email |
| Signed in, but a detail is missing from their record | Attribute name mismatch, or a value in a format CareLaunch doesn't accept (for example a date of birth not in YYYY-MM-DD) |
For anything else, contact the clinic, or reach CareLaunch directly at support@carelaunch.health.
Last updated: November 2026