SSO Role Mapping

DZDesk supports automatic role assignment based on identity provider group membership. This enables organizations to manage user permissions centrally through their existing identity infrastructure.

Standard DZDesk Group Names

DZDesk uses a standard naming convention for groups that works across both Azure Entra ID and Google Workspace:

Group Name	DZDesk Role	Description
DZDesk-Admins	admin	Full system access, settings, user management
DZDesk-Managers	manager	Team management, reports, escalations
DZDesk-Agents	agent	Handle tickets, view assigned work
DZDesk-Viewers	viewer	Read-only access to reports and dashboards
DZDesk-Users	customer	Submit and track own tickets
DZDesk-EndUsers	customer	Alias for DZDesk-Users
DZDesk-VIP	(VIP flag)	Mark user as VIP (any role can be VIP)

Recommendation

Create these groups in your identity provider with these exact names. DZDesk will automatically recognize them without any additional configuration.

Role Priority

When a user belongs to multiple groups, DZDesk assigns the highest priority role:

admin > manager > agent > viewer > customer

For example, if a user is in both DZDesk-Agents and DZDesk-Managers, they receive the manager role.

Azure Entra ID Role Mapping

Using Standard Groups

1. Create groups in Azure AD with standard DZDesk names:

   • DZDesk-Admins
   • DZDesk-Managers
   • DZDesk-Agents
   • DZDesk-Viewers
   • DZDesk-VIP

2. Configure group claims in your Enterprise Application:

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

3. Assign users to groups in Azure AD

Using Custom Group IDs (Environment Variables)

For organizations with existing groups, configure group ID mappings via environment variables:

ENTRA_GROUP_ADMINS=<azure-group-id-for-admins>
ENTRA_GROUP_MANAGERS=<azure-group-id-for-managers>
ENTRA_GROUP_AGENTS=<azure-group-id-for-agents>
ENTRA_GROUP_VIEWERS=<azure-group-id-for-viewers>
ENTRA_GROUP_ENDUSERS=<azure-group-id-for-customers>

Token Claims Used

DZDesk reads the following claims from Azure AD tokens:

Claim	DZDesk Field	Description
email	email	User's email address
given_name	first_name	First name
family_name	last_name	Last name
oid	entra_id	Azure Object ID (unique per user)
tid	tenant_id	Azure Tenant ID (company identifier)
groups	role	Array of group IDs for role mapping
amr	mfa_verified	Authentication methods (MFA check)

Google Workspace Role Mapping

Using Standard Groups

1. Create groups in Google Admin Console with standard DZDesk names:

   • DZDesk-Admins
   • DZDesk-Managers
   • DZDesk-Agents
   • DZDesk-Viewers
   • DZDesk-VIP

2. Enable Admin SDK API for your Google Workspace

3. Grant domain-wide delegation for DZDesk service account (for group sync)

Using Custom Group Mappings

Organizations can configure custom Google group to role mappings stored in the company settings:

{
  "google_group_mappings": [
    {
      "google_group_id": "03abc123",
      "google_group_email": "it-admins@company.com",
      "google_group_name": "IT Administrators",
      "dzdesk_role": "admin"
    },
    {
      "google_group_email": "support-team@company.com",
      "dzdesk_role": "agent"
    }
  ]
}

OAuth Claims Used

DZDesk reads the following from Google OAuth:

Claim	DZDesk Field	Description
email	email	User's email address
given_name	first_name	First name
family_name	last_name	Last name
sub	google_id	Google's unique user ID
hd	google_workspace_domain	Hosted domain (company identifier)
picture	(avatar)	Profile picture URL

VIP Status

The DZDesk-VIP group is special:

• It doesn't assign a role, it sets the VIP flag
• VIP users get priority handling regardless of their role
• A user can be agent + VIP or customer + VIP

Default Role Behavior

Scenario	Assigned Role
First user from new organization	admin
User in no DZDesk groups	customer
User in multiple groups	Highest priority role
Invited user (no SSO groups)	Role from invitation

Role Sync Behavior

DZDesk updates roles from SSO groups on every login:

sequenceDiagram
    participant User
    participant DZDesk
    participant IdP as Identity Provider

    User->>IdP: Sign in
    IdP->>DZDesk: Token with groups
    DZDesk->>DZDesk: Extract groups from token
    DZDesk->>DZDesk: Determine role (priority-based)
    DZDesk->>DZDesk: Update user.role if changed
    DZDesk->>User: Session with updated role

info

Role changes take effect on the next login. If a user is removed from DZDesk-Admins in Azure/Google, they'll lose admin access when they sign in again.