Failure Scenarios

This page documents common SSO and identity-related failures, their causes, and how to resolve them.

Authentication Failures

Blocked Domain

Error: Domain not permitted for this organization

Cause: User's email domain is not in the allowed list.

Resolution:

1. Go to Admin → Organization Settings → Allowed Domains
2. Add the user's domain to the whitelist
3. Or disable domain restrictions if open registration is desired

Allowed domains: acme.com, acme-corp.com
Blocked attempt: user@competitor.com

Cross-Tenant Attempt

Error: Access denied: tenant mismatch

Cause: User from Entra Tenant A trying to access organization configured for Tenant B.

Resolution:

• Verify the user is signing in with the correct Microsoft account
• Check that the Enterprise Application is configured in the correct Azure tenant
• For guest access, ensure proper invitation was sent

IdP Configuration Error

Error: SSO configuration error: invalid redirect URI

Cause: Mismatch between DZDesk configuration and IdP settings.

Resolution:

Provider	Check
Azure Entra	Verify Redirect URI in App Registration matches DZDesk
Google	Check Authorized redirect URIs in OAuth credentials

Token Expired

Error: Session expired, please sign in again

Cause: SSO token lifetime exceeded.

Resolution:

• User simply needs to re-authenticate
• Consider adjusting token lifetime in IdP settings

Authorization Failures

Role Not Assigned

Error: Access denied: insufficient permissions

Cause: User authenticated but has no role in DZDesk.

Resolution:

1. Check SSO Role Mapping configuration
2. Verify user is member of mapped groups in IdP
3. Manually assign role in Admin → Users if needed

Group Claim Missing

Error: Unable to determine user role from SSO

Cause: Group claims not included in SSO token.

Azure Entra Fix:

Enterprise App → Single Sign-On → Attributes & Claims
→ Add group claim → Select "Groups assigned to the application"

Google Fix:

• Enable "Include group membership" in OAuth consent screen
• Ensure Google Admin Console allows group access

VIP Flag Not Applied

Error: User from VIP domain not marked as VIP

Cause: VIP domain rules not matching.

Resolution:

1. Check Admin → VIP Settings → Domain Rules
2. Verify exact domain match (case-sensitive)
3. Ensure VIP rules are enabled for SSO users

Organization Failures

Organization Not Found

Error: No organization found for domain: example.com

Cause: First-time user from a domain with no existing organization.

Resolution:

• User needs to create a new organization (if allowed)
• Or receive an invitation from an existing organization

Organization Creation Blocked

Error: Organization creation not permitted for this domain

Cause: Public email domain or restricted domain.

Domain Type	Can Create Org?
Corporate (acme.com)	✅ Yes
Gmail (@gmail.com)	❌ No
Outlook (@outlook.com)	❌ No
Restricted domain	❌ No

Duplicate Organization

Error: Organization already exists for this tenant/domain

Cause: Attempting to create second organization for same Entra tenant or Google domain.

Resolution:

• Contact existing organization admin for an invitation
• Or use a different identity provider

Network & Connectivity Failures

IdP Unreachable

Error: Unable to connect to identity provider

Cause: Network issues between DZDesk and IdP.

Resolution:

1. Check IdP status page (Azure Status / Google Workspace Status)
2. Verify firewall rules allow outbound HTTPS
3. Test IdP connectivity from DZDesk server

Certificate Error

Error: SSL certificate verification failed

Cause: Certificate chain issue with IdP endpoint.

Resolution:

• Verify system root certificates are up to date
• Check for proxy/firewall SSL inspection issues

Recovery Procedures

User Locked Out

If a user cannot authenticate:

1. Check IdP status - Verify IdP is operational
2. Review audit logs - Admin → Audit Logs → Filter by user
3. Check SSO configuration - Verify settings haven't changed
4. Manual account recovery - Admin can reset user session

Bulk Authentication Failure

If multiple users affected:

1. Check IdP incident - Review provider status page
2. Verify SSO certificate - Certificates may have rotated
3. Review recent changes - Check if any configuration was modified
4. Enable fallback - Temporarily allow local authentication if configured

Organization Access Lost

If no admins can access organization:

1. Contact DZDesk Support with proof of domain ownership
2. Provide verification:
   • DNS TXT record verification
   • Company email from verified domain
3. Support will:
   • Verify ownership
   • Reset admin access
   • Restore organization

Error Code Reference

Code	Description	Action
SSO_001	Invalid redirect URI	Update IdP configuration
SSO_002	Token signature invalid	Check signing certificate
SSO_003	Token expired	Re-authenticate
SSO_004	Missing required claim	Update IdP claim mapping
AUTH_001	Domain not allowed	Whitelist domain or invite user
AUTH_002	Tenant mismatch	Verify correct SSO account
AUTH_003	User not found	Send invitation first
ORG_001	Organization not found	Create org or get invitation
ORG_002	Creation blocked	Use corporate email domain
ROLE_001	No role assigned	Configure role mapping