SSO Setup Troubleshooting Guide

Common error: "Required String parameter 'RelayState' is not present"

Despite the label in the XY Sense platform saying RelayState is optional, this error typically points to a misconfiguration elsewhere in the SAML setup rather than a missing RelayState value itself.

Check the Reply URL / ACS URL

This is the most common cause. In your Identity Provider (Azure AD or equivalent), verify that the Reply URL / Assertion Consumer Service (ACS) URL is populated correctly and matches exactly what XY Sense expects. Refer to Step 7 of the SAML 2.0 SSO for Azure AD setup article.

Check the Identifier and SAML base configuration

Confirm the Identifier (Entity ID) in your IDP matches the XY Sense configuration. A mismatch here can trigger unexpected errors.

Check claim name and email mapping

Verify that the claim name and email attribute are correctly mapped in your IDP configuration. XY Sense uses these to identify and provision users.

Claim name and email attribute are without namespace - we have seen organisations put namespaces before these attributes. e.g. <namespace>:name, <namespace>:email

Confirm the SSO type being used

XY Sense supports SAML 2.0 and OpenID Connect. Make sure your IDP setup matches the protocol configured on the XY Sense side.

 Check admin access on the new SSO account

Once SSO is working, the new SSO-linked account may not automatically inherit admin permissions. This needs to be manually granted in XY Sense under Admin > Users.

If locked out after enabling SSO

If a user can no longer access their original account because SSO is redirecting all logins, try resetting the password via email login. Contact XY Sense support to temporarily grant admin access to the new SSO account while the original account access is resolved.

Launching from Entra My App
If you are trying to launch from Entra My App, this is currently not supported, you will need to direct your users to app.xysense.io to login and launch the SSO flow.