Skip to main content
SAML SSO connects your corporate identity provider to your Cadana platform. Your users click Sign in with SSO on the white-label app, authenticate with the provider they already use every day, and land in Cadana signed in. No Cadana password, no token exchange on your side. This is the right choice when the people using Cadana are your own employees or admins and you already run Okta, Microsoft Entra ID, Google Workspace, OneLogin or any other SAML 2.0 identity provider. If you want to sign users in from your own product with a JWT you mint yourself, use Custom Authentication instead. Both can be enabled on the same platform.
SAML SSO is available to platforms on a dedicated Cadana identity pool, which every platform created since the pool-per-platform rollout has. Contact your account manager if you are unsure.

​
How It Works

  1. User opens your white-label app and chooses Sign in with SSO
  2. Cadana sends them to your identity provider
  3. They authenticate there, including any MFA your provider enforces
  4. Your provider returns a SAML assertion with the user’s email
  5. Cadana matches the email to an existing Cadana user on your platform and starts their session
Everything after step 7 is a normal Cadana session: refresh, logout and session expiry behave exactly as they do for password logins.

​
Before You Start

Ask your account manager for the two values below. They are fixed for your platform and available before anything is set up on either side, so this is the first thing to do.

​
Step 1: Create the Cadana Application in Your Identity Provider

Create a new SAML 2.0 application in your identity provider and give it the two values you received: Then make sure the assertion carries the user’s email address as an attribute. Cadana matches users by email, so this attribute must contain the same address the user has on their Cadana account.
Applications → Create App Integration → SAML 2.0. Set the Single sign-on URL to the ACS URL and the Audience URI to the Entity ID. Under Attribute Statements add email → user.email.
Assign the application to the users or groups who should be able to sign in to Cadana.

​
Step 2: Send Cadana Your Provider Details

Send your account manager: If your provider does not publish a metadata URL that Cadana can fetch, send the metadata XML file instead.
SAML settings are configured by your Cadana account manager. Self-service configuration in the Dashboard is coming soon.
Once configured, Cadana tells you SSO is live and the Sign in with SSO option appears on your white-label app’s login page.

​
Step 3: Make Sure Each User Exists in Cadana

SAML SSO signs in users who already have a Cadana account on your platform. It never creates accounts. Create your users as you do today, through the Dashboard or with POST /v1/users/invite. If users will only ever sign in through SSO, set suppressWelcomeEmail to true so they are not asked to set a Cadana password. The email on the Cadana user must match the email your identity provider asserts, character for character apart from letter case. Linking is automatic. The first time a user signs in through SSO, Cadana matches the asserted email to their account and links the two. Users who existed before SSO was enabled and users created afterwards are treated the same way.
A user who authenticates at your identity provider but has no Cadana account, or whose Cadana email differs from the asserted one, is refused with the message There is no Cadana account linked to that identity. No account is created for them.

​
Step 4: Sign In

Users open your white-label app and choose Sign in with SSO. To take a user who is already signed in to your own app straight into Cadana, link to the white-label login page with sso=1. The app starts the SSO flow at once; because the user already has a session with your identity provider there is no prompt, and they land signed in. Add redirect to choose the page:
The redirect must be a path inside the app. External URLs are ignored. Without sso=1 the login page is shown with the SSO button. Logins always start from the white-label app. If you want a tile for Cadana in your identity provider’s app launcher, point it at your white-label login page (for example https://payroll.yourcompany.com/login): the user clicks the SSO button there and, because they are already signed in with you, lands in Cadana without seeing another prompt. An assertion sent to Cadana without that first step is rejected.

​
What to Expect

​
Troubleshooting

​
Next Steps

Custom Authentication

Sign users in from your own product with a JWT exchange

Custom Domain

Serve the white-label app from your own domain

Onboard Workers

Create Person and User records

White-Label UI Overview

Customize the white-label app for your brand