Dex Federated OpenID Connect Provider

Dex is integrating [CEL (Common Expression Language)][cel-spec] as a first-class expression engine to handle policy evaluation, claim mapping, and token customization. This integration allows operators to define complex rules declaratively via expressions rather than requiring new Go code or configuration fields for every new requirement.

Key capabilities being introduced include:

• Authentication Policies: Control who can log in (e.g., restricting connectors to specific clients, enforcing group membership, or denying logins based on email domains).
• Token Policies: Customize issued tokens (e.g., adding extra claims to ID tokens, restricting scopes per client, or modifying aud claims).
• Advanced Claim Mapping: Replace ad-hoc OIDC connector configuration (like ClaimMapping or FilterGroupClaims) with powerful, composable CEL expressions.
• Global and Per-Client Rules: Apply policies at a global level or specifically to individual OAuth2 clients.

Dex Enhancement Proposals (DEPs) are design documents used to propose major new features or significant changes to Dex. Use this process to describe, track, and document changes to the project.

Before starting

1. Search GitHub for existing issues, discussions, and DEPs to avoid duplication.
2. If no discussion exists, open a new discussion.
3. Discuss your proposed change with the community to ensure a formal DEP is necessary.

Writing the proposal

1. Fork the repository.
2. Copy the template located at docs/enhancements/_title-YYYY-MM-DD-#issue.md and rename it appropriately.
3. Complete all sections in the template, providing as much detail as possible.
4. Submit a Pull Request (PR) and engage in discussion with the Dex team.

Dex allows operators to mutate ID tokens or restrict token issuance using CEL in the tokenPolicy configuration. This can be applied globally or per-client.

• claims: Adds or overrides claims in the issued ID token. Each claim has a key (the claim name), a value (the CEL expression for the value), and an optional condition (the claim is only included if this expression is true).
• filter: Validates the token request. If the expression evaluates to false, the request is denied.

Note: Certain OIDC/OAuth2 claims (e.g., iss, sub, aud, exp, iat, nbf, jti, auth_time, nonce, at_hash, c_hash) are reserved and cannot be set or overridden via CEL.

tokenPolicy:
  # Global mutations
  claims:
    - key: "'role'"
      value: "identity.groups.exists(g, g == 'admin') ? 'admin' : 'user'"
    - key: "'idp'"
      value: "request.connector_id"
    - key: "'department'"
      value: "identity.extra['department']"
      condition: "'department' in identity.extra"

staticClients:
  - id: internal-api
    name: Internal API
    secret: ...
    redirectURIs: [...]
    tokenPolicy:
      claims:
        - key: "'custom-claim.company.com/team'"
          value: "identity.extra['team'].orValue('engineering')"
        - key: "'on_call'"
          value: "true"
          condition: "identity.groups.exists(g, g == 'ops')"
      # Restrict scopes
      filter:
        expression: "request.scopes.all(s, s in ['openid', 'email', 'profile'])"
        message: "'Unsupported scope requested'"

Operators can define global and per-client authentication policies in the Dex configuration using Common Expression Language (CEL). Each expression must evaluate to a bool. If an expression evaluates to true, the request is denied. Expressions are evaluated in order; the first match wins.

Global Policy: Applies to all authentication requests. Per-client Policy: Defined within a staticClient and applies only to that specific client.

# Global authentication policy
authPolicy:
  - expression: "!identity.email.endsWith('@example.com')"
    message: "'Login restricted to example.com domain'"
  - expression: "!identity.email_verified"
    message: "'Email must be verified'"

staticClients:
  - id: admin-app
    name: Admin Application
    secret: ...
    redirectURIs: [...]
    # Per-client policy
    authPolicy:
      - expression: "!(request.connector_id in ['okta', 'ldap'])"
        message: "'This application requires Okta or LDAP login'"
      - expression: "!('admin' in identity.groups)"
        message: "'Admin group membership required'"

In OIDC connectors, you can replace legacy claimMapping and claimModifications with claimMappingExpressions. This allows for powerful, logic-based mapping of upstream IdP claims to Dex identity fields.

Available variable: claims (a map(string, dyn) containing raw upstream claims).

connectors:
  - type: oidc
    id: corporate-idp
    name: Corporate IdP
    config:
      issuer: https://idp.example.com
      clientID: dex-client
      clientSecret: ...
      # CEL-based claim mapping
      claimMappingExpressions:
        username: "claims.preferred_username.orValue(claims.email)"
        email: "claims.email"
        groups: >
          claims.groups
            .filter(g, g.startsWith('dex:'))
            .map(g, g.trimPrefix('dex:'))
        emailVerified: "claims.email_verified.orValue(true)"
        extra:
          department: "claims.department.orValue('unknown')"
          cost_center: "claims.cost_center.orValue('')"

Auth Sessions (DEP 4560) allow for Single Sign-On (SSO) between clients by sharing authentication sessions. To use this feature, you must first enable it via an environment variable.

Enable the feature

Set the following environment variable: DEX_SESSIONS_ENABLED=true

Configure session settings

Use the sessions block in your config.yaml to manage cookie names and lifetimes. Note that security settings like HttpOnly, Secure, and SameSite are automatically set to secure defaults and are not configurable.

Configuration Options

# Enable via environment variable
# DEX_SESSIONS_ENABLED=true

# Configuration in config.yaml
sessions:
  cookieName: "dex_session"
  absoluteLifetime: "24h"
  validIfNotUsedFor: "1h"
  ssoSharedWithDefault: "none"
  rememberMeCheckedByDefault: false