Use this page to diagnose and fix common problems during SAML SSO setup and login. For setup instructions, start with Custom SAML.
| 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. |
| 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. |
| ”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 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. |
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. |
| 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. |
| 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. |
| 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. |
| 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. |
- 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.
- For Google Workspace, see the Google Workspace SAML guide.