> For the complete documentation index, see [llms.txt](https://docs.madrix.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.madrix.dev/troubleshooting/sso-and-login.md).

# SSO and login

SSO, login loop, callback error, or expired session.

### When to use

* Looping login.
* SSO returns error after authenticating at the IdP.
* User authenticates but does not have access to the project.

### Quick checklist (2 min)

1. Test in an incognito/private window.
2. Clear cookies for the domain.
3. Confirm the user is in the correct tenant/organization.

### Diagnosis

#### 1) Permissions vs authentication

* **Authenticated** but does not see resources: usually permission/group related.
* **Not authenticated**: usually SSO/callback configuration.

#### 2) Callback and redirect URI

* Confirm if the `redirect/callback URL` from the IdP matches exactly what is configured.
* Check for differences in http/https or domain.

#### 3) Clock skew and expiration

* Do tokens expire quickly?
* Do errors vary by user/machine?

### How to resolve (patterns)

* **Loop**: clear cookies and review domain/callback.
* **403 after login**: adjust groups/roles and claim mapping.
* **Error only in one browser**: extension blocking cookies/3rd-party.

### When to escalate

* All users in an org fail.
* Reproducible callback error.
* Recent change in IdP (certificate/metadata) causing widespread breakage.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}