Errors and troubleshooting
Build handling around the stable code, not the human-readable message. Do not blindly retry 4xx responses; most require correcting identity, configuration, or signing logic.
| Code | HTTP | Cause | What to do |
|---|---:|---|---|
| SSO_REQUEST_INVALID | 400 | Form field missing/empty | Submit strings for clientId, payload, and signature. |
| SSO_PAYLOAD_INVALID | 400 | Payload is not Base64URL JSON | Encode UTF-8 JSON once; inspect locally without logging production data. |
| SSO_IDENTITY_REQUIRED | 400 | sub or email absent | Load both from trusted authenticated user state. |
| SSO_CONFIGURATION_INVALID | 400 | Invalid origin/path administration | Use HTTPS origins and safe relative paths. |
| SSO_INTEGRATION_UNAVAILABLE | 401 | Credential missing/revoked or tenant inactive | Confirm environment and tenant status; contact admin. |
| SSO_SIGNATURE_INVALID | 401 | Wrong secret/encoding or changed payload | Sign exact encoded payload with active secret. |
| SSO_ASSERTION_EXPIRED | 401 | Expired, too long, or iat >60s ahead | Generate immediately, use seconds, synchronize clocks. |
| SSO_ORIGIN_NOT_ALLOWED | 403 | Browser Origin not registered | Compare scheme, hostname, and port exactly. |
| SSO_REDIRECT_NOT_ALLOWED | 403 | Destination origin invalid/unregistered | Sign a configured Nanaade workspace origin. |
| SSO_MEMBERSHIP_REQUIRED | 403 | No active matching membership | Invite/activate the person in the credential's tenant. |
| SSO_ASSERTION_REPLAYED | 409 | Nonce already consumed/missing | Generate a fresh random nonce for every launch. |
| SSO_SUBJECT_MISMATCH | 409 | Membership bound to another subject | Correct the source identity; do not overwrite binding. |
| SSO_REPLAY_STORE_UNAVAILABLE | 503 | Production nonce store unavailable | Wait for recovery; do not bypass replay protection. |
| FEATURE_NOT_LICENSED | 403 | Module/add-on not granted | Tenant admin reviews licensing; do not loop SSO. |
Administrative credential operations may also report SSO_CREDENTIAL_EXISTS, SSO_CREDENTIAL_NOT_FOUND, or SSO_ENCRYPTION_NOT_CONFIGURED. These are Nanaade administrator/operations concerns, not errors your public portal should attempt to repair.
Diagnose a signature failure
Verify in this order:
- Client ID and secret come from the same environment/credential issue.
- The secret has no accidental whitespace or quotes.
- Payload is
base64url(UTF8(JSON.stringify(assertion))). - HMAC message is the encoded payload string.
- Digest output uses Base64URL, not hexadecimal or standard Base64.
- The payload is not modified after signing.
Diagnose an origin failure
In browser developer tools, inspect the request's Origin header. Compare only the exact scheme, host, and port to Nanaade configuration. A page URL path is irrelevant; a proxy that rewrites hosts may not be.
Diagnose a membership failure
Confirm the client ID belongs to the expected tenant, membership is active, normalized assertion email matches first binding, and the stable subject has not changed. A successful login to your own portal does not prove Nanaade membership.
Contacting support
Provide request ID, UTC timestamp, stable error code, client ID (or last characters), environment, expected destination, and whether the failure affects all users. Never provide the secret, full assertion, signature, session cookie, or user password.