Configure DEX to expose additional Active Directory fields by modifying client configurations and identity provider mappings to pass attributes like department or job role to applications.

In production, applications often require more than basic user identity attributes (e.g., username, email). Active Directory (AD) stores rich metadata, but DEX doesn’t expose these fields by default. This guide walks through field-tested steps to extend DEX configurations for secure, reliable attribute propagation.

Context: Why This Matters

Applications may need AD attributes like department, jobTitle, or custom extensions for authorization, logging, or user experience. Without explicit configuration, DEX omits these fields, forcing workarounds like secondary lookups or redundant user stores.

Workflow: Configure DEX for Additional AD Fields

1. Identify Target AD Attributes

   • Use ldapsearch or PowerShell to list available attributes in your AD instance. Example:

     ldapsearch -x -b "dc=example,dc=com" "(objectclass=person)" department jobTitle
     

   • Note: Some attributes (e.g., departmentNumber) may require specific permissions or LDAP filters.

2. Update DEX Connector Configuration
   Modify the AD connector in your DEX configuration to include desired attributes. Example snippet:

   connectors:
     - type: sAML
       id: ad-connector
       name: Active Directory
       sso_url: https://adfs.example.com/adfs/ls/
       client_id: dex-client
       client_secret: <secret>
       # Add attributes to expose
       attributes:
         department: department
         jobTitle: jobTitle
         jobRole: customJobRole  # Custom attribute mapping
   

3. Map Attributes to Client Claims
   In the DEX client configuration, specify which attributes to forward to the application:

   clients:
     - id: my-app
       name: My Application
       redirect_uris:
         - https://my-app.example.com/callback
       # Request specific attributes
       requested_scopes: ["openid", "email", "department", "jobTitle"]
       requested_id_tokens: ["department", "jobRole"]
   

4. Restart DEX
   Apply configuration changes and restart the DEX pod:

   kubectl rollout restart deployment -n dex dex-core
   

5. Validate Token Claims
   Use kubectl describe secret or a JWT decoder to verify attributes in issued tokens:

   kubectl get secret -n my-app dex-oauth-token | jq -r '.data' | base64 -d | jq
   

Policy Example: Custom Attribute Mapping

To expose a custom AD attribute like extensionAttribute1:

connectors:
  - type: sAML
    id: ad-connector
    attributes:
      customAttribute: extensionAttribute1  # Maps AD attribute to claim name
clients:
  - id: my-app
    requested_id_tokens:
      - customAttribute

Tooling

• dex-cli: Test configurations locally before deploying.
• OpenShift Container Platform (OCP): Use built-in DEX integrations (e.g., ClusterOAuthIdentityProvider).
• LDAP Debugging: Tools like ldapsearch or Azure AD Graph Explorer to validate attribute availability.
• JWT Decoders: Verify token claims with jwt.io or jq.

Tradeoffs and Caveats

• Performance: Fetching large or nested attributes may increase latency. Test in staging.
• Permission Requirements: DEX service account must have AD read access for all requested attributes.
• Attribute Naming: Mismatched attribute names between AD and DEX can cause silent failures.
• Security: Exposing sensitive attributes (e.g., employeeID) requires careful authorization controls downstream.

Troubleshooting

• Missing Attributes in Tokens:
  • Check DEX logs for LDAP query errors:

    kubectl logs -n dex dex-core | grep "LDAP query"
    

  • Validate attribute names in AD using ldapsearch.
• Permission Denied Errors:
  • Ensure the DEX service account has read access to the AD attributes.
• Attribute Not in Token:
  • Confirm the client configuration explicitly requests the attribute via requested_id_tokens.

Prevention

• Test in Staging: Use a non-production AD instance or test user with limited attributes.
• Monitor Logs: Set up alerts for DEX LDAP query failures or token generation errors.
• Document Attribute Contracts: Maintain a list of supported attributes and their mappings for future reference.

This approach balances operational simplicity with production reliability. Avoid overloading DEX with unnecessary attributes—keep configurations minimal and auditable.

Source thread: How can I configure DEX to convey additional AD fields to the requesting application?