# SAML SSO troubleshooting Source: https://developer.nylas.com/docs/dev-guide/dashboard-saml-sso/troubleshooting/ Use this page to diagnose and fix common problems during SAML SSO setup and login. For setup instructions, start with [Custom SAML](/docs/dev-guide/dashboard-saml-sso/connect-idp/). ## Domain verification | Symptom | Likely cause | What to do | |---|---|---| | "DNS record not found" after clicking Verify | The TXT record has not propagated yet, or the record was added with a typo | Wait a few minutes and try again. Double-check the record **name** (`_nylas-verify.yourdomain.com`) and **value** (must start with `nylas-domain-verify=`) in your DNS provider. | | Verify succeeds but domain still shows as pending | Browser cache showing stale state | Refresh the page. If still pending, re-open Organization settings > SAML SSO. | | "Domain claim not found" | The claim was deleted or expired before verification | Start the domain claim again from the **Verify your company domain** step. | | "SAML configuration still connected" warning after removing domains | SAML config exists but no verified domain remains | Click **Remove SAML configuration** on the domain step, or add and verify a domain again. Removing the last verified domain automatically deletes SAML config and disables SSO enforcement. | ## SAML login errors | Symptom | Likely cause | What to do | |---|---|---| | Login redirects to IdP and then back to the Nylas login page with no session | The SAML assertion was rejected | Check the error code shown. Common causes: invalid signature, expired assertion, or wrong audience. See rows below for each. | | "SAML is not configured for this organization" | No IdP metadata has been saved | Complete the **Connect your identity provider** step in the wizard. See [Custom SAML](/docs/dev-guide/dashboard-saml-sso/connect-idp/). | | "SAML is currently disabled" | The SAML configuration was disabled or removed | Re-enter IdP metadata in the wizard to re-enable SAML for the org. | | "Authentication failed" with no further detail | The assertion was rejected for a security reason | Enable more detailed error output in a staging environment, or check server logs for the specific error code (`SAML_INVALID_SIGNATURE`, `SAML_ASSERTION_EXPIRED`, etc.). | | Invalid signature error | Stale IdP certificate in Nylas, or wrong signed-response setting | See [Invalid signature](#invalid-signature) below. | | User gets "Account not found. Contact your administrator." | JIT provisioning is off and the user has no Dashboard account | Enable JIT provisioning in the **Manage user access** step of the wizard, or manually invite the user before they sign in. | ## Invalid signature An `SAML_INVALID_SIGNATURE` error means Nylas could not verify the assertion against the stored IdP certificate. | Cause | Fix | |---|---| | IdP certificate was rotated after initial setup | Download fresh metadata XML from your IdP and re-paste it in the Nylas wizard. | | Google Workspace: **Signed response** is turned ON | Open Google Admin Console > the SAML app > edit Service provider details. Turn **Signed response OFF**. Nylas validates only the Assertion, not the outer Response envelope. | | Wrong IdP metadata pasted | Confirm the metadata XML is from the correct IdP app. Paste fresh metadata to reset. | ## Role assignment | Symptom | Likely cause | What to do | |---|---|---| | User gets a different role than expected after SAML login | Group name mismatch in role mapping | Group name matching is case-insensitive but must be an exact match for the rest of the string. Check the group name sent by your IdP against the group names entered in the **Manage user access** step. | | User gets the default role instead of a mapped role | The `groups` attribute is missing from the SAML assertion | Add a `groups` attribute statement to your IdP SAML app. See [Custom SAML](/docs/dev-guide/dashboard-saml-sso/connect-idp/#required-saml-attributes). | | Existing member keeps their current role after SAML login | Group mappings are configured but the assertion has no `groups` attribute | Nylas only updates roles on login when group mappings exist **and** the assertion includes at least one group value. Without groups in the assertion, existing members keep their current role instead of falling back to the default role. | | No role mapping configured and users get unexpected roles | No group mapping set | All new SAML users receive the **Default role** configured in step 3 when no group mapping is set. Existing members keep their current role on subsequent logins. | ## SSO enforcement | Symptom | Likely cause | What to do | |---|---|---| | "Verify a company domain, configure SAML, and ensure at least one organization owner exists before enabling enforcement" | One or more prerequisites are missing | Confirm: at least one domain is verified, SAML config is saved, and at least one member has the Owner role. | | Modal shows members outside verified domains when enabling enforcement | Members whose email is not on a verified company domain | Review the list. Remove members who should not retain password or OAuth access, or click **Proceed anyway** to enable enforcement and manage access later on the Members page. | | Org owner cannot enable enforcement | Owner role missing | An organization must have at least one Owner before enforcement can be enabled. Check members under Organization settings > Members. | | Users on a claimed domain can still log in with a password after enforcement is on | User's email domain does not match the verified domain | Enforcement only applies to users whose email matches a verified domain. Users on other domains are not affected. | | An owner can still log in with a password even with enforcement on | Expected behavior | Organization owners are exempt from SSO enforcement as a break-glass safety mechanism. This is intentional. | ## Google Workspace | Symptom | Likely cause | What to do | |---|---|---| | "App not assigned" error from Google | The user is not assigned to the SAML app | Go to Admin Console > Apps > Web and mobile apps > the app > User access. Assign the user or their OU. | | Login loop after successful Google sign-in | IdP-initiated flow used instead of SP-initiated | Do not use Google's **Test SAML Login** button. Start from the Nylas login page, enter the work email, and click **Continue**. | | Login fails after Google certificate rotation | Stale IdP certificate in Nylas | Download fresh metadata XML from Google Admin Console and re-paste it in the Nylas wizard. | | "App not found" or redirect error | ACS URL or SP Entity ID mismatch | Confirm the ACS URL and SP Entity ID in your Google SAML app match the values shown in the Nylas Dashboard exactly. | ## Still stuck? - Confirm the email address, verified domain, and IdP user account all match exactly (case-insensitive domain, exact email prefix). - Try in a private or incognito window to rule out stale cookies. - For Okta, see the [Okta SAML guide](/docs/dev-guide/dashboard-saml-sso/okta/). - For Google Workspace, see the [Google Workspace SAML guide](/docs/dev-guide/dashboard-saml-sso/google-workspace/).