> ## Documentation Index > Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt > Use this file to discover all available pages before exploring further. # SAML Single Sign-On > Let your staff sign in to the white-label app with your corporate identity provider (Okta, Microsoft Entra, Google Workspace) export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => { const baseUrl = "https://api.cadanapay.com"; const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : ""; const url = `${baseUrl}${path}${query}`; const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || ""); const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey; let curl = `curl -X ${method} '${url}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'`; if (includeTenantKey) { curl += ` \\\n -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`; } if (body) { const formatted = JSON.stringify(body, null, 2); curl += ` \\\n -H 'Content-Type: application/json' \\\n -d '${formatted}'`; } return
{curl} {reference &&
Try it in the playground →
}
; }; 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](/white-label/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 ```mermaid theme={null} sequenceDiagram participant U as User participant W as White-Label App participant C as Cadana participant I as Your Identity Provider U->>W: 1. Sign in with SSO W->>C: 2. Start SSO login C-->>U: 3. Redirect to your identity provider U->>I: 4. Authenticate (+ your MFA) I-->>C: 5. SAML assertion (email) C->>C: 6. Match email to a Cadana user C-->>W: 7. Redirect back, session established W-->>U: 8. Access granted ``` 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: | Value | What it is | Example | | :- | :- | :- | | **ACS URL** (Reply URL, Single sign-on URL) | Where your provider posts the SAML assertion | `https://cadana-yourplatform.auth.eu-west-1.amazoncognito.com/saml2/idpresponse` | | **Entity ID** (Audience URI, Identifier) | Cadana's service-provider identifier for your platform | `urn:amazon:cognito:sp:eu-west-1_AbCdEfGhI` | 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`. Enterprise applications → New application → Create your own application → Integrate any other application. Under Single sign-on → SAML set the Identifier to the Entity ID and the Reply URL to the ACS URL. The default claim `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` is used as the email. Apps → Web and mobile apps → Add custom SAML app. Set the ACS URL and Entity ID. Under Attribute mapping add Primary email → `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: | Setting | Description | Example | | :- | :- | :- | | **Metadata URL** | Your provider's SAML metadata document for the Cadana application | `https://yourcompany.okta.com/app/abc123/sso/saml/metadata` | | **Email attribute** | The attribute name in the assertion that carries the email, if it is not the provider default | `email` | 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`](/api-reference/workforce/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: ``` https://payroll.yourcompany.com/login?sso=1&redirect=/employeeView/time-tracking ``` 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 | Topic | Behaviour | | :- | :- | | **Password login** | Still available to users who have a Cadana password. SSO is an additional way in, not a replacement. | | **Multi-factor authentication** | Enforced by your identity provider. Cadana does not ask for a second factor on SSO logins. | | **Session length** | Same as every Cadana session. When it expires the user signs in again through SSO. | | **Removing access** | Unassign the user from the application in your identity provider, or offboard them in Cadana. Either stops new SSO logins. | | **Changing a user's email** | Change it in Cadana and in your provider. The next SSO login links the new email automatically. | | **Changing identity provider** | Contact your account manager. Users are linked to the new provider at their next sign-in. | *** ## Troubleshooting | What the user sees | Cause | Fix | | :- | :- | :- | | *There is no Cadana account linked to that identity* | No Cadana user has the asserted email on your platform | Create or invite the user, or correct the email on either side | | *Your identity provider could not sign you in* | Your provider rejected the login, or the Cadana application is not assigned to the user | Check the user's assignment and your provider's sign-in logs | | *That sign-in link has expired* | More than 10 minutes passed between starting the login and returning | Start again from the login page | | *This login was started in another browser* | The user opened the post-login link in a different browser or device than the one they started in | Start again in the browser they will use | *** ## Next Steps Sign users in from your own product with a JWT exchange Serve the white-label app from your own domain Create Person and User records Customize the white-label app for your brand This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.