Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

Install Wellness Coach SSO with OpenID Connect (OIDC)

Wellness Coach supports single sign-on via OpenID Connect (OIDC) as an alternative to SAML. OIDC setup is significantly simpler than SAML: there are no certificates or metadata XML files to exchange — you register one app in your identity provider (IdP) and paste three values into the Wellness Coach Admin Portal.

Wellness Coach uses the OIDC Authorization Code flow with PKCE and works with any standards-compliant OIDC provider, including Okta, Microsoft Entra ID (Azure AD), Google Workspace, and PingFederate.

After setup, your employees sign in to Wellness Coach with their corporate credentials. Accounts are created automatically on first sign-in (just-in-time provisioning). Automated provisioning via SCIM is also supported and configured separately (see the existing SSO/SCIM setup guide).

What You Will Need

Item 

Where to Get It

 

Admin access to your IdP

Your organization's IdP admin console

Wellness Coach Redirect URI

Wellness Coach Admin Portal > Settings > SSO Configuration (OIDC)

Wellness Coach Initiate Login URI (optional, for the IdP tile)

Same page

Enterprise ID (corporate_id)

Same page — used in the Initiate Login URI
 

Note: Contact your Wellness Coach account manager if you do not see OIDC settings in your admin portal, or to have your organization switched from SAML to OIDC.

Step 1: Register the Wellness Coach App in Your IdP

Create an OIDC Web application (confidential client) in your identity provider with these settings:

Setting

 

Value

 

Application type

Web (confidential client)

Grant type

Authorization Code (with PKCE)

Sign-in redirect URI

{https://auth.wellnesscoach.live}/sso/oidc/callback (copy the exact value from the Admin Portal)

Initiate login URI (optional)

{https://auth.wellnesscoach.live}/sso/oidc/start/{your corporate_id}

Scopes

openid, profile, email

ID token signing algorithm

RS256 (default in most IdPs)

Client authentication

Client secret (post or basic — both supported)

Important: The redirect URI must match exactly (HTTPS, no trailing slash, no wildcards). Copy it from the Admin Portal rather than typing it.

Note: The Initiate Login URI is what makes the Wellness Coach tile in your IdP dashboard work (IdP-initiated sign-in). It plays the role the SAML "Default Relay State" plays in our SAML app: it tells Wellness Coach which enterprise the sign-in belongs to.

Provider-specific notes

  • Okta: Applications > Create App Integration > OIDC – OpenID Connect > Web Application. Assign users/groups under the Assignments tab as usual. (An Okta OIN catalog listing for OIDC is planned; until then use a custom app integration.)
  • Microsoft Entra ID (Azure AD): Microsoft Entra ID > App registrations > New registration > add the Redirect URI under Web. Create the client secret under Certificates & secrets. Under API permissions, ensure openid, profile, email are granted. If your tenant does not emit the email claim by default, add it under Token configuration > Add optional claim > ID > email.
  • Google Workspace: Google Cloud Console > APIs & Services > Credentials > Create OAuth client ID > Web application.
  • PingFederate: Your Ping administrator creates an OAuth client with the settings above (Authorization Code + PKCE, RS256). Confirm the required claims (email, given_name, family_name) are released to the client in the access/ID token policy.

Step 2: Collect the Three Values

After registering the app, copy from your IdP:

 

Value

 

Example

 

Issuer URL

https://yourcompany.okta.com or https://login.microsoftonline.com/{tenant-id}/v2.0

Client ID

0oa1b2c3d4...

Client Secret

shown once at creation — copy it immediately

Tip: The Issuer URL is the base of your IdP's discovery document — Wellness Coach fetches {issuer}/.well-known/openid-configuration automatically, so no other endpoints or certificates are needed.

Step 3: Enter the Values in Wellness Coach

  1. Sign in to the Wellness Coach Admin Portal as an enterprise administrator.
  2. Navigate to Settings > SSO Configuration.
  3. Select OIDC as the SSO protocol.
  4. Paste the Issuer URL, Client ID, and Client Secret.
  5. Click Save.

That's it — there is no metadata upload, certificate exchange, or renewal calendar. Your IdP's signing keys are fetched and rotated automatically.

Security note: Your client secret is stored encrypted and is never displayed again after saving. To rotate it, generate a new secret in your IdP and paste the new value here.

Step 4: Assign Users and Test

  1. In your IdP, assign the users or groups who should have access to Wellness Coach.
  2. Open a new incognito/private browser window.
  3. SP-initiated test: go to the Wellness Coach sign-in page, enter a corporate email address — you are redirected to your IdP and back, signed in. If you were already signed in to your IdP, this completes without a password prompt.
  4. IdP-initiated test (if you configured the Initiate Login URI): from your IdP dashboard, click the Wellness Coach tile — you land in Wellness Coach signed in.

First-time users are provisioned automatically from the claims in the ID token (email, first name, last name).

How It Compares to Our SAML Setup

 

 

SAML

 

OIDC

 

Trust setup

Metadata XML + certificate exchange

Issuer URL + Client ID + Secret

Certificate renewals

Manual, expiry outages possible

None — keys rotate automatically

Enterprise identifier

Relay State (corporate_id)

Initiate Login URI (contains corporate_id)

IdP dashboard tile

Supported

Supported

SCIM provisioning

Supported

Supported (unchanged)
 

Organizations currently on SAML can switch by completing this guide and asking Wellness Coach support to flip the protocol — the change is server-side and requires no employee action; SAML config is kept as a rollback.

Troubleshooting

Symptom

 

Likely Cause

 

Fix

 

redirect_uri_mismatch error at the IdP

Redirect URI typo or trailing slash

Copy the exact URI from the Admin Portal into your IdP app

"Sign-in link expired, please try again"

The sign-in attempt sat longer than 10 minutes, or the link was reused

Start the sign-in again from the Wellness Coach login page

invalid_client during sign-in

Wrong client secret, or secret expired/rotated in the IdP

Generate a new secret in the IdP and update it in the Admin Portal

"A valid email was not found"

IdP does not release the email claim

Grant the email scope/claim to the app (see Entra note in Step 1)

Tile click shows an error page

Initiate Login URI missing the corporate_id

Re-copy the full Initiate Login URI from the Admin Portal

"Email mismatch" confirmation screen

User entered a different email than their IdP account asserts

Expected safety check — the user confirms, or signs in with the matching email

Works in browser, fails in mobile app

Old app version

Update to the latest Wellness Coach mobile app

Support

If you encounter issues not covered above, contact Wellness Coach support:

When contacting support, please include: your organization name and corporate_id, which IdP you are using (Okta, Entra ID, Google, PingFederate, other), the error message or a screenshot, and the email address of an affected user.