This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Connectors

Documentation about configuration of Dex connectors

1: Authentication Through LDAP
2: Authentication Through GitHub
3: Authentication through SAML 2.0
4: Authentication Through GitLab
5: Authentication Through an OpenID Connect Provider
6: Authentication Through an OAuth 2.0 Provider
7: Authentication Through Google
8: Authentication Through LinkedIn
9: Authentication Through Microsoft
10: Authenticating Proxy
11: Authentication Through Bitbucket Cloud
12: Authentication Through the builtin connector
13: Authentication using OpenShift
14: Authentication Through Atlassian Crowd
15: Authentication Through Gitea
16: Authentication Through OpenStack Keystone

When a user logs in through Dex, the user’s identity is usually stored in another user-management system: a LDAP directory, a GitHub org, etc. Dex acts as a shim between a client app and the upstream identity provider. The client only needs to understand OpenID Connect to query Dex, while Dex implements an array of protocols for querying other user-management systems.

A “connector” is a strategy used by Dex for authenticating a user against another identity provider. Dex implements connectors that target specific platforms such as GitHub, LinkedIn, and Microsoft as well as established protocols like LDAP and SAML.

Depending on the connectors limitations in protocols can prevent Dex from issuing refresh tokens or returning group membership claims. For example, because SAML doesn’t provide a non-interactive way to refresh assertions, if a user logs in through the SAML connector Dex won’t issue a refresh token to its client. Refresh token support is required for clients that require offline access, such as kubectl.

Dex implements the following connectors:

Name	supports refresh tokens	supports groups claim	supports preferred_username claim	status	notes
LDAP	yes	yes	yes	stable
GitHub	yes	yes	yes	stable
SAML 2.0	no	yes	no	stable
GitLab	yes	yes	yes	beta
OpenID Connect	yes	yes	yes	beta	Includes Salesforce, Azure, etc.
OAuth 2.0	no	yes	yes	alpha
Google	yes	yes	yes	alpha
LinkedIn	yes	no	no	beta
Microsoft	yes	yes	no	beta
AuthProxy	no	no	no	alpha	Authentication proxies such as Apache2 mod_auth, etc.
Bitbucket Cloud	yes	yes	no	alpha
OpenShift	no	yes	no	stable
Atlassian Crowd	yes	yes	yes *	beta	preferred_username claim must be configured through config
Gitea	yes	no	yes	alpha
OpenStack Keystone	yes	yes	no	alpha

Stable, beta, and alpha are defined as:

Stable: well tested, in active use, and will not change in backward incompatible ways.
Beta: tested and unlikely to change in backward incompatible ways.
Alpha: may be untested by core maintainers and is subject to change in backward incompatible ways.

All changes or deprecations of connector features will be announced in the release notes.

1 - Authentication Through LDAP

Overview

The LDAP connector allows email/password based authentication, backed by a LDAP directory.

The connector executes two primary queries:

Finding the user based on the end user’s credentials.
Searching for groups using the user entry.

Getting started

The dex repo contains a basic LDAP setup using OpenLDAP.

First start the LDAP server using docker-compose. This will run the OpenLDAP daemon in a Docker container, and seed it with an initial set of users.

cd examples/ldap
docker-compose up

This container is expected to print several warning messages which are normal. Once the server is up, run dex in another terminal.

./bin/dex serve examples/ldap/config-ldap.yaml

Then run the OAuth client in another terminal.

./bin/example-app

Go to http://localhost:5555, login and enter the username and password of the LDAP user: janedoe@example.com/foo. Add the “groups” scope as part of the initial redirect to add group information from the LDAP server.

Security considerations

Dex attempts to bind with the backing LDAP server using the end user’s plain text password. Though some LDAP implementations allow passing hashed passwords, dex doesn’t support hashing and instead strongly recommends that all administrators just use TLS. This can often be achieved by using port 636 instead of 389, and administrators that choose 389 are actively leaking passwords.

Dex currently allows insecure connections because the project is still verifying that dex works with the wide variety of LDAP implementations. However, dex may remove this transport option, and users who configure LDAP login using 389 are not covered by any compatibility guarantees with future releases.

Configuration

User entries are expected to have an email attribute (configurable through emailAttr), and a display name attribute (configurable through nameAttr). *Attr attributes could be set to “DN” in situations where it is needed but not available elsewhere, and if “DN” attribute does not exist in the record.

For the purposes of configuring this connector, “DN” is case-sensitive and should always be capitalised.

The following is an example config file that can be used by the LDAP connector to authenticate a user.

connectors:
- type: ldap
  # Required field for connector id.
  id: ldap
  # Required field for connector name.
  name: LDAP
  config:
    # Host and optional port of the LDAP server in the form "host:port".
    # If the port is not supplied, it will be guessed based on "insecureNoSSL",
    # and "startTLS" flags. 389 for insecure or StartTLS connections, 636
    # otherwise.
    host: ldap.example.com:636

    # Following field is required if the LDAP host is not using TLS (port 389).
    # Because this option inherently leaks passwords to anyone on the same network
    # as dex, THIS OPTION MAY BE REMOVED WITHOUT WARNING IN A FUTURE RELEASE.
    #
    # insecureNoSSL: true

    # If a custom certificate isn't provide, this option can be used to turn on
    # TLS certificate checks. As noted, it is insecure and shouldn't be used outside
    # of explorative phases.
    #
    # insecureSkipVerify: true

    # When connecting to the server, connect using the ldap:// protocol then issue
    # a StartTLS command. If unspecified, connections will use the ldaps:// protocol
    #
    # startTLS: true

    # Path to a trusted root certificate file. Default: use the host's root CA.
    rootCA: /etc/dex/ldap.ca

    # A raw certificate file can also be provided inline.
    # rootCAData: ( base64 encoded PEM file )

    # The DN and password for an application service account. The connector uses
    # these credentials to search for users and groups. Not required if the LDAP
    # server provides access for anonymous auth.
    # Please note that if the bind password contains a `$`, it has to be saved in an
    # environment variable which should be given as the value to `bindPW`.
    bindDN: uid=serviceaccount,cn=users,dc=example,dc=com
    bindPW: password

    # The attribute to display in the provided password prompt. If unset, will
    # display "Username"
    usernamePrompt: SSO Username

    # User search maps a username and password entered by a user to a LDAP entry.
    userSearch:
      # BaseDN to start the search from. It will translate to the query
      # "(&(objectClass=person)(uid=<username>))".
      baseDN: cn=users,dc=example,dc=com
      # Optional filter to apply when searching the directory.
      filter: "(objectClass=person)"

      # username attribute used for comparing user entries. This will be translated
      # and combined with the other filter as "(<attr>=<username>)".
      username: uid
      # The following three fields are direct mappings of attributes on the user entry.
      # String representation of the user.
      idAttr: uid
      # Required. Attribute to map to Email.
      emailAttr: mail
      # Maps to display name of users. No default value.
      nameAttr: name
      # Maps to preferred username of users. No default value.
      preferredUsernameAttr: uid

    # Group search queries for groups given a user entry.
    groupSearch:
      # BaseDN to start the search from. It will translate to the query
      # "(&(objectClass=group)(member=<user uid>))".
      baseDN: cn=groups,dc=freeipa,dc=example,dc=com
      # Optional filter to apply when searching the directory.
      filter: "(objectClass=group)"

      # Following list contains field pairs that are used to match a user to a group. It adds an additional
      # requirement to the filter that an attribute in the group must match the user's
      # attribute value.
      userMatchers:
      - userAttr: uid
        groupAttr: member

      # Represents group name.
      nameAttr: name

The LDAP connector first initializes a connection to the LDAP directory using the bindDN and bindPW. It then tries to search for the given username and bind as that user to verify their password. Searches that return multiple entries are considered ambiguous and will return an error.

Example: Mapping a schema to a search config

Writing a search configuration often involves mapping an existing LDAP schema to the various options dex provides. To query an existing LDAP schema install the OpenLDAP tool ldapsearch. For rpm based distros run:

sudo dnf install openldap-clients

For apt-get:

sudo apt-get install ldap-utils

For smaller user directories it may be practical to dump the entire contents and search by hand.

ldapsearch -x -H ldap://ldap.example.org -b 'dc=example,dc=org' | less

First, find a user entry. User entries declare users who can login to LDAP connector using username and password.

dn: uid=jdoe,cn=users,cn=compat,dc=example,dc=org
cn: Jane Doe
objectClass: posixAccount
objectClass: ipaOverrideTarget
objectClass: top
gidNumber: 200015
gecos: Jane Doe
uidNumber: 200015
loginShell: /bin/bash
homeDirectory: /home/jdoe
mail: jane.doe@example.com
uid: janedoe

Compose a user search which returns this user.

userSearch:
  # The directory directly above the user entry.
  baseDN: cn=users,cn=compat,dc=example,dc=org
  filter: "(objectClass=posixAccount)"

  # Expect user to enter "janedoe" when logging in.
  username: uid

  # Use the full DN as an ID.
  idAttr: DN

  # When an email address is not available, use another value unique to the user, like uid.
  emailAttr: mail
  nameAttr: gecos

Second, find a group entry.

dn: cn=developers,cn=groups,cn=compat,dc=example,dc=org
memberUid: janedoe
memberUid: johndoe
gidNumber: 200115
objectClass: posixGroup
objectClass: ipaOverrideTarget
objectClass: top
cn: developers

Group searches must match a user attribute to a group attribute. In this example, the search returns users whose uid is found in the group’s list of memberUid attributes.

groupSearch:
  # The directory directly above the group entry.
  baseDN: cn=groups,cn=compat,dc=example,dc=org
  filter: "(objectClass=posixGroup)"

  # The group search needs to match the "uid" attribute on
  # the user with the "memberUid" attribute on the group.
  userMatchers:
  - userAttr: uid
    groupAttr: memberUid

  # Unique name of the group.
  nameAttr: cn

To extract group specific information the DN can be used in the userAttr field.

# Top level object example.coma in LDIF file.
dn: dc=example,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
dc: example

The following is an example of a group query would match any entry with member=:

groupSearch:
  # BaseDN to start the search from. It will translate to the query
  # "(&(objectClass=group)(member=<user DN>))".
  baseDN: cn=groups,cn=compat,dc=example,dc=com
  # Optional filter to apply when searching the directory.
  filter: "(objectClass=group)"

  userMatchers:
  - userAttr: DN # Use "DN" here not "uid"
    groupAttr: member

  nameAttr: name

There are cases when different types (objectClass) of groups use different attributes to keep a list of members. Below is an example of group query for such case:

groupSearch:
  baseDN: cn=groups,cn=compat,dc=example,dc=com
  # Optional filter to search for different group types
  filter: "(|(objectClass=posixGroup)(objectClass=group))"

  # Use multiple user matchers so Dex will know which attribute names should be used to search for group members
  userMatchers:
  - userAttr: uid
    groupAttr: memberUid
  - userAttr: DN
    groupAttr: member

  nameAttr: name

Example: Searching a FreeIPA server with groups

The following configuration will allow the LDAP connector to search a FreeIPA directory using an LDAP filter.

connectors:
- type: ldap
  id: ldap
  name: LDAP
  config:
    # host and port of the LDAP server in form "host:port".
    host: freeipa.example.com:636
    # freeIPA server's CA
    rootCA: ca.crt
    userSearch:
      # Would translate to the query "(&(objectClass=posixAccount)(uid=<username>))".
      baseDN: cn=users,dc=freeipa,dc=example,dc=com
      filter: "(objectClass=posixAccount)"
      username: uid
      idAttr: uid
      # Required. Attribute to map to Email.
      emailAttr: mail
      # Entity attribute to map to display name of users.
    groupSearch:
      # Would translate to the query "(&(objectClass=group)(member=<user uid>))".
      baseDN: cn=groups,dc=freeipa,dc=example,dc=com
      filter: "(objectClass=group)"
      userMatchers:
      - userAttr: uid
        groupAttr: member
      nameAttr: name

If the search finds an entry, it will attempt to use the provided password to bind as that user entry.

Example: Searching a Active Directory server with groups

The following configuration will allow the LDAP connector to search a Active Directory using an LDAP filter.

connectors:
- type: ldap
  name: ActiveDirectory
  id: ad
  config:
    host: ad.example.com:636

    insecureNoSSL: false
    insecureSkipVerify: true

    bindDN: cn=Administrator,cn=users,dc=example,dc=com
    bindPW: admin0!

    usernamePrompt: Email Address

    userSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=person)"
      username: userPrincipalName
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

    groupSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=group)"
      userMatchers:
      - userAttr: DN
        groupAttr: member
      nameAttr: cn

2 - Authentication Through GitHub

Overview

One of the login options for dex uses the GitHub OAuth2 flow to identify the end user through their GitHub account.

When a client redeems a refresh token through dex, dex will re-query GitHub to update user information in the ID Token. To do this, dex stores a readonly GitHub access token in its backing datastore. Users that reject dex’s access through GitHub will also revoke all dex clients which authenticated them through GitHub.

Caveats

A user must explicitly request an organization give dex resource access. Dex will not have the correct permissions to determine if the user is in that organization otherwise, and the user will not be able to log in. This request mechanism is a feature of the GitHub API.

Configuration

Register a new application with GitHub ensuring the callback URL is (dex issuer)/callback. For example if dex is listening at the non-root path https://auth.example.com/dex the callback would be https://auth.example.com/dex/callback.

The following is an example of a configuration for examples/config-dev.yaml:

connectors:
- type: github
  # Required field for connector id.
  id: github
  # Required field for connector name.
  name: GitHub
  config:
    # Credentials can be string literals or pulled from the environment.
    clientID: $GITHUB_CLIENT_ID
    clientSecret: $GITHUB_CLIENT_SECRET
    redirectURI: http://127.0.0.1:5556/dex/callback

    # Legacy 'org' field.
    #  - A user MUST be a member of the following org to authenticate with dex.
    #  - Both 'org' and 'orgs' can NOT be used simultaneously.
    #org: my-organization

    # List of org and team names.
    #  - If specified, a user MUST be a member of at least ONE of these orgs
    #    and teams (if set) to authenticate with dex.
    #  - Dex queries the following organizations for group information if the
    #    "groups" scope is requested. Group claims are formatted as "(org):(team)".
    #    For example if a user is part of the "engineering" team of the "coreos" org,
    #    the group claim would include "coreos:engineering".
    #  - If teams are specified, dex only returns group claims for those teams.
    orgs:
    - name: my-organization
    - name: my-organization-with-teams
      teams:
      - red-team
      - blue-team

    # Flag which indicates that all the user's orgs and teams should be loaded.
    # Only works if neither 'org' nor 'orgs' are specified in the config.
    loadAllGroups: false

    # How the team names are formatted.
    #  - Options: 'name' (default), 'slug', 'both'.
    #  - Examples:
    #    - 'name': 'acme:Site Reliability Engineers'
    #    - 'slug': 'acme:site-reliability-engineers'
    #    - 'both': 'acme:Site Reliability Engineers', 'acme:site-reliability-engineers'
    teamNameField: slug

    # Flag which will switch from using the internal GitHub id to the users handle (@mention) as the user id.
    # It is possible for a user to change their own username, but it is very rare for them to do so
    useLoginAsID: false

    # A preferred email domain to use when returning the user's email.
    #  - If the user has a PUBLIC email, it is ALWAYS returned in the email claim,
    #    so this field would have NO effect (this may change in the future).
    #  - By default, if the user does NOT have a public email, their primary email is returned.
    #  - When 'preferredEmailDomain' is set, the first email matching this domain is returned,
    #    we fall back to the primary email if no match is found.
    #  - To allow multiple subdomains, you may specify a wildcard like "*.example.com"
    #    which will match "aaaa.example.com" and "bbbb.example.com", but NOT "example.com".
    #  - To return the user's no-reply email, set this field to "users.noreply.github.com",
    #    this is a mostly static email that GitHub assigns to the user. These emails
    #    are formatted like 'ID+USERNAME@users.noreply.github.com' for newer accounts
    #    and 'USERNAME@users.noreply.github.com' for older accounts.
    #preferredEmailDomain: "example.com"

GitHub Enterprise

Users can use their GitHub Enterprise account to login to dex. The following configuration can be used to enable a GitHub Enterprise connector on dex:

connectors:
- type: github
  # Required field for connector id.
  id: github
  # Required field for connector name.
  name: GitHub
  config:
    # Required fields. Dex must be pre-registered with GitHub Enterprise
    # to get the following values.
    # Credentials can be string literals or pulled from the environment.
    clientID: $GITHUB_CLIENT_ID
    clientSecret: $GITHUB_CLIENT_SECRET
    redirectURI: http://127.0.0.1:5556/dex/callback

    # List of org and team names.
    #  - If specified, a user MUST be a member of at least ONE of these orgs
    #    and teams (if set) to authenticate with dex.
    #  - Dex queries the following organizations for group information if the
    #    "groups" scope is requested. Group claims are formatted as "(org):(team)".
    #    For example if a user is part of the "engineering" team of the "coreos" org,
    #    the group claim would include "coreos:engineering".
    #  - If teams are specified, dex only returns group claims for those teams.
    orgs:
    - name: my-organization
    - name: my-organization-with-teams
      teams:
      - red-team
      - blue-team

    # Flag which indicates that all the user's orgs and teams should be loaded.
    # Only works if neither 'org' nor 'orgs' are specified in the config.
    loadAllGroups: false

    # How the team names are formatted
    #  - Options: 'name' (default), 'slug', 'both'.
    #  - Examples:
    #    - 'name': 'acme:Site Reliability Engineers'
    #    - 'slug': 'acme:site-reliability-engineers'
    #    - 'both': 'acme:Site Reliability Engineers', 'acme:site-reliability-engineers'
    teamNameField: slug

    # Required ONLY for GitHub Enterprise.
    # This is the Hostname of the GitHub Enterprise account listed on the
    # management console. Ensure this domain is routable on your network.
    hostName: git.example.com

    # ONLY for GitHub Enterprise. Optional field.
    # Used to support self-signed or untrusted CA root certificates.
    rootCA: /etc/dex/ca.crt

Generate TLS assets

Running Dex with HTTPS enabled requires a valid SSL certificate, and the API server needs to trust the certificate of the signing CA using the --oidc-ca-file flag.

For our example use case, the TLS assets can be created using the following command:

$ ./examples/k8s/gencert.sh

This will generate several files under the ssl directory, the important ones being cert.pem ,key.pem and ca.pem. The generated SSL certificate is for ‘dex.example.com’, although you could change this by editing gencert.sh if required.

Run example client app with GitHub config

./bin/example-app --issuer-root-ca examples/k8s/ssl/ca.pem

Open browser to http://127.0.0.1:5555
Click Login
Select Log in with GitHub and grant access to dex to view your profile

3 - Authentication through SAML 2.0

WARNING

The SAML connector is unmaintained, likely vulnerable to authentication bypass vulnerabilities, and is under consideration for deprecation (see #1884). Please consider switching to OpenID Connect, OAuth2, or LDAP for identity providers that support these protocols. If you have domain expertise in SAML/XMLDSig and would like to volunteer to maintain the connector please comment on the discussion.

Overview

The SAML provider allows authentication through the SAML 2.0 HTTP POST binding. The connector maps attribute values in the SAML assertion to user info, such as username, email, and groups.

The connector uses the value of the NameID element as the user’s unique identifier which dex assumes is both unique and never changes. Use the nameIDPolicyFormat to ensure this is set to a value which satisfies these requirements.

Unlike some clients which will process unprompted AuthnResponses, dex must send the initial AuthnRequest and validates the response’s InResponseTo value.

Caveats

The connector doesn’t support refresh tokens since the SAML 2.0 protocol doesn’t provide a way to requery a provider without interaction. If the “offline_access” scope is requested, it will be ignored.

The connector doesn’t support signed AuthnRequests or encrypted attributes.

Group Filtering

The SAML Connector supports providing a whitelist of SAML Groups to filter access based on, and when the groupsattr is set with a scope including groups, Dex will check for membership based on configured groups in the allowedGroups config setting for the SAML connector.

If filterGroups is set to true, any groups not part of allowedGroups will be excluded.

Configuration

connectors:
- type: saml
  # Required field for connector id.
  id: saml
  # Required field for connector name.
  name: SAML
  config:
    # SSO URL used for POST value.
    ssoURL: https://saml.example.com/sso

    # CA to use when validating the signature of the SAML response.
    ca: /path/to/ca.pem

    # Dex's callback URL.
    #
    # If the response assertion status value contains a Destination element, it
    # must match this value exactly.
    #
    # This is also used as the expected audience for AudienceRestriction elements
    # if entityIssuer isn't specified.
    redirectURI: https://dex.example.com/callback

    # Name of attributes in the returned assertions to map to ID token claims.
    usernameAttr: name
    emailAttr: email
    groupsAttr: groups # optional

    # List of groups to filter access based on membership
    # allowedGroups
    #   - Admins

    # CA's can also be provided inline as a base64'd blob.
    #
    # caData: ( RAW base64'd PEM encoded CA )

    # To skip signature validation, uncomment the following field. This should
    # only be used during testing and may be removed in the future.
    #
    # insecureSkipSignatureValidation: true

    # Optional: Manually specify dex's Issuer value.
    #
    # When provided dex will include this as the Issuer value during AuthnRequest.
    # It will also override the redirectURI as the required audience when evaluating
    # AudienceRestriction elements in the response.
    entityIssuer: https://dex.example.com/callback

    # Optional: Issuer value expected in the SAML response.
    ssoIssuer: https://saml.example.com/sso

    # Optional: Delimiter for splitting groups returned as a single string.
    #
    # By default, multiple groups are assumed to be represented as multiple
    # attributes with the same name.
    #
    # If "groupsDelim" is provided groups are assumed to be represented as a
    # single attribute and the delimiter is used to split the attribute's value
    # into multiple groups.
    groupsDelim: ", "

    # Optional: Requested format of the NameID.
    #
    # The NameID value is is mapped to the user ID of the user. This can be an
    # abbreviated form of the full URI with just the last component. For example,
    # if this value is set to "emailAddress" the format will resolve to:
    #
    #     urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    #
    # If no value is specified, this value defaults to:
    #
    #     urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    #
    nameIDPolicyFormat: persistent

A minimal working configuration might look like:

connectors:
- type: saml
  id: okta
  name: Okta
  config:
    ssoURL: https://dev-111102.oktapreview.com/app/foo/exk91cb99lKkKSYoy0h7/sso/saml
    ca: /etc/dex/saml-ca.pem
    redirectURI: http://127.0.0.1:5556/dex/callback
    usernameAttr: name
    emailAttr: email
    groupsAttr: groups

4 - Authentication Through GitLab

Overview

GitLab is a web-based Git repository manager with wiki and issue tracking features, using an open source license, developed by GitLab Inc. One of the login options for dex uses the GitLab OAuth2 flow to identify the end user through their GitLab account. You can use this option with gitlab.com, GitLab community or enterprise edition.

When a client redeems a refresh token through dex, dex will re-query GitLab to update user information in the ID Token. To do this, dex stores a readonly GitLab access token in its backing datastore. Users that reject dex’s access through GitLab will also revoke all dex clients which authenticated them through GitLab.

Configuration

Register a new application via User Settings -> Applications ensuring the callback URL is (dex issuer)/callback. For example if dex is listening at the non-root path https://auth.example.com/dex the callback would be https://auth.example.com/dex/callback.

The application requires the user to grant the read_user and openid scopes. The latter is required only if group membership is a desired claim.

The following is an example of a configuration for examples/config-dev.yaml:

connectors:
  - type: gitlab
    # Required field for connector id.
    id: gitlab
    # Required field for connector name.
    name: GitLab
    config:
      # optional, default = https://gitlab.com
      baseURL: https://gitlab.com
      # Credentials can be string literals or pulled from the environment.
      clientID: $GITLAB_APPLICATION_ID
      clientSecret: $GITLAB_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/callback
      # Optional groups whitelist, communicated through the "groups" scope.
      # If `groups` is omitted, all of the user's GitLab groups are returned when the groups scope is present.
      # If `groups` is provided, this acts as a whitelist - only the user's GitLab groups that are in the configured `groups` below will go into the groups claim.  Conversely, if the user is not in any of the configured `groups`, the user will not be authenticated.
      groups:
      - my-group
      # flag which will switch from using the internal GitLab id to the users handle (@mention) as the user id.
      # It is possible for a user to change their own user name but it is very rare for them to do so
      useLoginAsID: false
      # Flag to include user group permissions in the user groups.
      # For example, if the user has maintainer access to a GitLab group named "project/group1", 
      # the user's groups will reflect two entries: "project/group1" and "project/group1:maintainer".
      getGroupsPermission: false

5 - Authentication Through an OpenID Connect Provider

Overview

Dex is able to use another OpenID Connect provider as an authentication source. When logging in, dex will redirect to the upstream provider and perform the necessary OAuth2 flows to determine the end users email, username, etc. More details on the OpenID Connect protocol can be found in An overview of OpenID Connect.

Prominent examples of OpenID Connect providers include Google Accounts, Salesforce, and Azure AD v2 (not v1).

Configuration

connectors:
- type: oidc
  id: google
  name: Google
  config:
    # Canonical URL of the provider, also used for configuration discovery.
    # This value MUST match the value returned in the provider config discovery.
    #
    # See: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig
    issuer: https://accounts.google.com

    # Connector config values starting with a "$" will read from the environment.
    clientID: $GOOGLE_CLIENT_ID
    clientSecret: $GOOGLE_CLIENT_SECRET

    # Dex's issuer URL + "/callback"
    redirectURI: http://127.0.0.1:5556/callback


    # Some providers require passing client_secret via POST parameters instead
    # of basic auth, despite the OAuth2 RFC discouraging it. Many of these
    # cases are caught internally, but some may need to uncomment the
    # following field.
    #
    # basicAuthUnsupported: true
    
    # List of additional scopes to request in token response
    # Default is profile and email
    # Full list at https://dexidp.io/docs/custom-scopes-claims-clients/
    # scopes:
    #  - profile
    #  - email
    #  - groups

    # Some providers return claims without "email_verified", when they had no usage of emails verification in enrollment process
    # or if they are acting as a proxy for another IDP etc AWS Cognito with an upstream SAML IDP
    # This can be overridden with the below option
    # insecureSkipEmailVerified: true 

    # Groups claims (like the rest of oidc claims through dex) only refresh when the id token is refreshed
    # meaning the regular refresh flow doesn't update the groups claim. As such by default the oidc connector
    # doesn't allow groups claims. If you are okay with having potentially stale group claims you can use
    # this option to enable groups claims through the oidc connector on a per-connector basis.
    # This can be overridden with the below option
    # insecureEnableGroups: true

    # When enabled, the OpenID Connector will query the UserInfo endpoint for additional claims. UserInfo claims
    # take priority over claims returned by the IDToken. This option should be used when the IDToken doesn't contain
    # all the claims requested.
    # https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
    # getUserInfo: true

    # The set claim is used as user id.
    # Claims list at https://openid.net/specs/openid-connect-core-1_0.html#Claims
    # Default: sub
    # userIDKey: nickname

    # The set claim is used as user name.
    # Default: name
    # userNameKey: nickname

    # The acr_values variable specifies the Authentication Context Class Values within
    # the Authentication Request that the Authorization Server is being requested to process
    # from this Client.
    # acrValues: 
    #  - <value>
    #  - <value>

    # For offline_access, the prompt parameter is set by default to "prompt=consent". 
    # However this is not supported by all OIDC providers, some of them support different
    # value for prompt, like "prompt=login" or "prompt=none"
    # promptType: consent

    # Some providers return non-standard claims (eg. mail).
    # Use claimMapping to map those claims to standard claims:
    # https://openid.net/specs/openid-connect-core-1_0.html#Claims
    # claimMapping can only map a non-standard claim to a standard one if it's not returned in the id_token.
    claimMapping:
      # The set claim is used as preferred username.
      # Default: preferred_username
      # preferred_username: other_user_name

      # The set claim is used as email.
      # Default: email
      # email: mail

      # The set claim is used as groups.
      # Default: groups
      # groups: "cognito:groups"

    # overrideClaimMapping will be used to override the options defined in claimMappings.
    # i.e. if there are 'email' and `preferred_email` claims available, by default Dex will always use the `email` claim independent of the claimMapping.email.
    # This setting allows you to override the default behavior of Dex and enforce the mappings defined in `claimMapping`.
    overrideClaimMapping: false

    # The section to override options discovered automatically from
    # the providers' discovery URL (.well-known/openid-configuration).
    providerDiscoveryOverrides:
      # tokenURL provides a way to user overwrite the token URL
      # from the .well-known/openid-configuration 'token_endpoint'.
      # tokenURL: ""
      #
      # authURL provides a way to user overwrite the authorization URL
      # from the .well-known/openid-configuration 'authorization_endpoint'.   
      # authURL: ""

6 - Authentication Through an OAuth 2.0 Provider

Overview

Dex users can make use of this connector to work with standards-compliant OAuth 2.0 authorization providers, in case those authorization providers are not already in the Dex connectors list.

Configuration

The following is an example of a configuration for using OAuth connector with Reddit.

connectors:
- type: oauth
  # ID of OAuth 2.0 provider
  id: reddit 
  # Name of OAuth 2.0 provider
  name: reddit
  config:
    # Connector config values starting with a "$" will read from the environment.
    clientID: $REDDIT_CLIENT_ID
    clientSecret: $REDDIT_CLIENT_SECRET
    redirectURI: http://127.0.0.1:5556/callback

    tokenURL: https://www.reddit.com/api/v1/access_token
    authorizationURL: https://www.reddit.com/api/v1/authorize
    userInfoURL: https://www.reddit.com/api/v1/me
 
    # Optional: Specify whether to communicate to Auth provider without
    # validating SSL certificates
    # insecureSkipVerify: false

    # Optional: The location of file containing SSL certificates to communicate
    # to Auth provider
    # rootCAs:
    # - /etc/ssl/reddit.pem

    # Optional: List of scopes to request Auth provider for access user account
    # scopes:
    #  - identity

    # Optional: Configurable keys for user ID look up
    # Default: id
    # userIDKey:

    # Auth providers return non-standard user identity profile
    # Use claimMapping to map those user informations to standard claims:
    claimMapping:
      # Optional: Configurable keys for user name look up
      # Default: user_name
      # userNameKey:

      # Optional: Configurable keys for preferred username look up
      # Default: preferred_username
      # preferredUsernameKey:

      # Optional: Configurable keys for user groups look up
      # Default: groups
      # groupsKey:

      # Optional: Configurable keys for email look up
      # Default: email
      # emailKey:

      # Optional: Configurable keys for email verified look up
      # Default: email_verified
      # emailVerifiedKey:

7 - Authentication Through Google

Overview

Dex is able to use Google’s OpenID Connect provider as an authentication source.

The connector uses the same authentication flow as the OpenID Connect provider but adds Google specific features such as Hosted domain support and reading groups using a service account.

Configuration

connectors:
- type: google
  id: google
  name: Google
  config:

    # Connector config values starting with a "$" will read from the environment.
    clientID: $GOOGLE_CLIENT_ID
    clientSecret: $GOOGLE_CLIENT_SECRET

    # Dex's issuer URL + "/callback"
    redirectURI: http://127.0.0.1:5556/callback

    # Set the value of `prompt` query parameter in the authorization request
    # The default value is "consent" when not set.
    # promptType: consent

    # Google supports whitelisting allowed domains when using G Suite
    # (Google Apps). The following field can be set to a list of domains
    # that can log in:
    #
    # hostedDomains:
    #  - example.com

    # The Google connector supports whitelisting allowed groups when using G Suite
    # (Google Apps). The following field can be set to a list of groups
    # that can log in:
    #
    # groups:
    #  - admins@example.com

    # Google does not support the OpenID Connect groups claim and only supports
    # fetching a user's group membership with a service account.
    # This service account requires an authentication JSON file and the email
    # of a G Suite admin to impersonate:
    #
    #serviceAccountFilePath: googleAuth.json
    #domainToAdminEmail:
    #  *: super-user@example.com
    #  my-domain.com: super-user@my-domain.com

Fetching groups from Google

To allow Dex to fetch group information from Google, you will need to configure a service account for Dex to use. This account needs Domain-Wide Delegation and permission to access the https://www.googleapis.com/auth/admin.directory.group.readonly API scope.

To get group fetching set up:

Follow the instructions to set up a service account with Domain-Wide Delegation

During service account creation, a JSON key file will be created that contains authentication information for the service account. This needs storing in a location accessible by Dex and you will set the serviceAccountFilePath to point at it.
When delegating the API scopes to the service account, delegate the https://www.googleapis.com/auth/admin.directory.group.readonly scope and only this scope. If you delegate more scopes to the service account, it will not be able to access the API.

Enable the Admin SDK
Add the serviceAccountFilePath and domainToAdminEmail configuration options to your Dex config.

serviceAccountFilePath should point to the location of the service account JSON key file
domainToAdminEmail should map the base domain to the email address of a Google Workspace user with a minimum of the Groups Reader (BETA) Role assigned. The service account you created earlier will impersonate this user when making calls to the admin API. A valid user should be able to retrieve a list of groups when testing the API.

Dex will set prompt=consent by default when redirecting users to Google’s authorization endpoint. This will force users to see the consent screen every time they log in.

To change this behavior, you can set the promptType field in config file to any OIDC-supported value. To skip the consent screen for every authorization request, set promptType to "" (empty string) to fall back to Google’s default behavior.

8 - Authentication Through LinkedIn

Overview

One of the login options for dex uses the LinkedIn OAuth2 flow to identify the end user through their LinkedIn account.

When a client redeems a refresh token through dex, dex will re-query LinkedIn to update user information in the ID Token. To do this, dex stores a readonly LinkedIn access token in its backing datastore. Users that reject dex’s access through LinkedIn will also revoke all dex clients which authenticated them through LinkedIn.

Configuration

Register a new application via My Apps -> Create Application ensuring the callback URL is (dex issuer)/callback. For example if dex is listening at the non-root path https://auth.example.com/dex the callback would be https://auth.example.com/dex/callback.

The following is an example of a configuration for examples/config-dev.yaml:

connectors:
  - type: linkedin
    # Required field for connector id.
    id: linkedin
    # Required field for connector name.
    name: LinkedIn
    config:
      # Credentials can be string literals or pulled from the environment.
      clientID: $LINKEDIN_APPLICATION_ID
      clientSecret: $LINKEDIN_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/callback

9 - Authentication Through Microsoft

Overview

One of the login options for dex uses the Microsoft OAuth2 flow to identify the end user through their Microsoft account.

When a client redeems a refresh token through dex, dex will re-query Microsoft to update user information in the ID Token. To do this, dex stores a readonly Microsoft access and refresh tokens in its backing datastore. Users that reject dex’s access through Microsoft will also revoke all dex clients which authenticated them through Microsoft.

Caveats

groups claim in dex is only supported when tenant is specified in Microsoft connector config. Furthermore, tenant must also be configured to either <tenant uuid> or <tenant name> (see Configuration). In order for dex to be able to list groups on behalf of logged in user, an explicit organization administrator consent is required. To obtain the consent do the following:

when registering dex application on https://apps.dev.microsoft.com add an explicit Directory.Read.All permission to the list of Delegated Permissions
open the following link in your browser and log in under organization administrator account:

https://login.microsoftonline.com/<tenant>/adminconsent?client_id=<dex client id>

Configuration

Register a new application on https://apps.dev.microsoft.com via Add an app ensuring the callback URL is (dex issuer)/callback. For example if dex is listening at the non-root path https://auth.example.com/dex the callback would be https://auth.example.com/dex/callback.

The following is an example of a configuration for examples/config-dev.yaml:

connectors:
  - type: microsoft
    # Required field for connector id.
    id: microsoft
    # Required field for connector name.
    name: Microsoft
    config:
      # Credentials can be string literals or pulled from the environment.
      clientID: $MICROSOFT_APPLICATION_ID
      clientSecret: $MICROSOFT_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/callback

tenant configuration parameter controls what kinds of accounts may be authenticated in dex. By default, all types of Microsoft accounts (consumers and organizations) can authenticate in dex via Microsoft. To change this, set the tenant parameter to one of the following:

common- both personal and business/school accounts can authenticate in dex via Microsoft (default)
consumers - only personal accounts can authenticate in dex
organizations - only business/school accounts can authenticate in dex
<tenant uuid> or <tenant name> - only accounts belonging to specific tenant identified by either <tenant uuid> or <tenant name> can authenticate in dex

For example, the following snippet configures dex to only allow business/school accounts:

connectors:
  - type: microsoft
    # Required field for connector id.
    id: microsoft
    # Required field for connector name.
    name: Microsoft
    config:
      # Credentials can be string literals or pulled from the environment.
      clientID: $MICROSOFT_APPLICATION_ID
      clientSecret: $MICROSOFT_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/callback
      tenant: organizations

domainHint configuration parameter allows for a more streamlined login experience when the email domain is common to all users of the connector. By default, users with multiple Microsoft sessions will be prompted to choose which account they want to use for login. When domainHint is configured, Microsoft will select the session with matching email without the interactive prompt.

For example: user John Doe has 2 active Microsoft sessions:

John.Doe@live.com (consumer)
John.Doe@example.com (organization)

If Example Organization configures the domainHint parameter with its organization’s email suffix, John will not be prompted to select an account from the active sessions. Instead, the matching organization session is selected automatically.

scopes configuration parameter controls what the initial scope(s) of the identity token that dex requests from Microsoft. To change this initial set, configure the scopes parameter to be a list of one or more valid scopes (as defined in Microsoft Documentation).

The default scope (if one is not specified in the connector’s configuration) is user.read.

The scope list requested may also be appended by specifying groups or requesting a new token through the use of a refresh token.

For example, the following snippet configures dex to request an OpenID token with only getting the email address associated with the account and nothing else:

connectors:
  - type: microsoft
    # Required field for connector id.
    id: microsoft
    # Required field for connector name.
    name: Microsoft
    config:
      # Credentials can be string literals or pulled from the environment.
      clientID: $MICROSOFT_APPLICATION_ID
      clientSecret: $MICROSOFT_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/callback
      tenant: example.onmicrosoft.com
      domainHint: example.com
      scopes:
        - openid
        - email

Groups

When the groups claim is present in a request to dex and tenant is configured, dex will query Microsoft API to obtain a list of groups the user is a member of. onlySecurityGroups configuration option restricts the list to include only security groups. By default all groups (security, Office 365, mailing lists) are included.

Please note that tenant must be configured to either <tenant uuid> or <tenant name> for this to work. For more details on tenant configuration, see Configuration.

By default, dex resolve groups ids to groups names, to keep groups ids, you can specify the configuration option groupNameFormat: id.

It is possible to require a user to be a member of a particular group in order to be successfully authenticated in dex. For example, with the following configuration file only the users who are members of at least one of the listed groups will be able to successfully authenticate in dex:

connectors:
  - type: microsoft
    # Required field for connector id.
    id: microsoft
    # Required field for connector name.
    name: Microsoft
    config:
      # Credentials can be string literals or pulled from the environment.
      clientID: $MICROSOFT_APPLICATION_ID
      clientSecret: $MICROSOFT_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/callback
      tenant: myorg.onmicrosoft.com
      groups:
        - developers
        - devops

Also, useGroupsAsWhitelist configuration option, can restrict the groups claims to include only the user’s groups that are in the configured groups.

You can use the emailToLowercase (boolean) configuration option to streamline UPNs (user email) from Active Directory before putting them into an id token. Without this option, it can be tough to match the email claim because a client application doesn’t know whether an email address has been added with capital- or lowercase letters. For example, it is hard to bind Roles in Kubernetes using email as a user name (–oidc-username-claim=email flag) because user names are case sensitive.

connectors:
  - type: microsoft
    # Required field for connector id.
    id: microsoft
    # Required field for connector name.
    name: Microsoft
    config:
      # Credentials can be string literals or pulled from the environment.
      clientID: $MICROSOFT_APPLICATION_ID
      clientSecret: $MICROSOFT_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/callback
      tenant: myorg.onmicrosoft.com
      groups:
        - developers
        - devops
      # All relevant E-Mail Addresses delivered by AD will transformed to
      # lowercase if config is TRUE
      emailToLowercase: true

10 - Authenticating Proxy

NOTE: This connector is experimental and may change in the future.

Overview

The authproxy connector returns identities based on authentication which your front-end web server performs. Dex consumes the X-Remote-User header set by the proxy, which is then used as the user’s email address.

It also consumes the X-Remote-Group header to use as the user’s group.

Header’s names can be configured via the userHeader and groupHeader config.

Additional static groups can also be defined in the connector’s configuration.

The proxy MUST remove any X-Remote-* headers set by the client, for any URL path, before the request is forwarded to dex.

The connector does not support refresh tokens.

Configuration

The authproxy connector is used by proxies to implement login strategies not supported by dex. For example, a proxy could handle a different OAuth2 strategy such as Slack:

connectors:
# Slack login implemented by an authenticating proxy, not by dex.
- type: authproxy
  id: slack
  name: Slack

The proxy only needs to authenticate the user when they attempt to visit the callback URL path:

( dex issuer URL )/callback/( connector id )?( url query )

For example, if dex is running at https://auth.example.com/dex and the connector ID is slack, the callback URL would look like:

https://auth.example.com/dex/callback/slack?state=xdg3z6quhrhwaueo5iysvliqf

The proxy should login the user then return them to the exact URL (including the query), setting X-Remote-User to the user’s email before proxying the request to dex.

Configuration example - Apache 2

The following is an example config file that can be used by the external connector to authenticate a user.

connectors:
- type: authproxy
  id: myBasicAuth
  name: HTTP Basic Auth
  config:
    userHeader: X-Forwarded-User # default is X-Remote-User
    groupHeader: X-Forwarded-Group # default is X-Remote-Group
    staticGroups:
    - default

The authproxy connector assumes that you configured your front-end web server such that it performs authentication for the /dex/callback/myBasicAuth location and provides the result in the HTTP headers.

In this example, the configured headers are X-Forwarded-User for the user’s mail and X-Forwarded-Group for the user’s group. Dex authproxy connector will return a list of groups containing both configured staticGroups and return the group header.

The following configuration will work for Apache 2.4.10+:

<Location /dex/>
    ProxyPass "http://localhost:5556/dex/"
    ProxyPassReverse "http://localhost:5556/dex/"

    # Strip the X-Remote-User header from all requests except for the ones
    # where we override it.
    RequestHeader unset X-Remote-User
</Location>

<Location /dex/callback/myBasicAuth>
    AuthType Basic
    AuthName "db.debian.org webPassword"
    AuthBasicProvider file
    AuthUserFile "/etc/apache2/debian-web-pw.htpasswd"
    Require valid-user

    # Defense in depth: clear the Authorization header so that
    # Debian Web Passwords never even reach dex.
    RequestHeader unset Authorization

    # Requires Apache 2.4.10+
    RequestHeader set X-Remote-User expr=%{REMOTE_USER}@debian.org

    ProxyPass "http://localhost:5556/dex/callback/myBasicAuth"
    ProxyPassReverse "http://localhost:5556/dex/callback/myBasicAuth"
</Location>

Full Apache2 setup

After installing your Linux distribution’s Apache2 package, place the following virtual host configuration in e.g. /etc/apache2/sites-available/sso.conf:

<VirtualHost sso.example.net>
    ServerName sso.example.net

    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined

    <Location /dex/>
        ProxyPass "http://localhost:5556/dex/"
        ProxyPassReverse "http://localhost:5556/dex/"

        # Strip the X-Remote-User header from all requests except for the ones
        # where we override it.
        RequestHeader unset X-Remote-User
    </Location>

    <Location /dex/callback/myBasicAuth>
        AuthType Basic
        AuthName "db.debian.org webPassword"
        AuthBasicProvider file
        AuthUserFile "/etc/apache2/debian-web-pw.htpasswd"
        Require valid-user

        # Defense in depth: clear the Authorization header so that
        # Debian Web Passwords never even reach dex.
        RequestHeader unset Authorization

        # Requires Apache 2.4.10+
        RequestHeader set X-Remote-User expr=%{REMOTE_USER}@debian.org

        ProxyPass "http://localhost:5556/dex/callback/myBasicAuth"
        ProxyPassReverse "http://localhost:5556/dex/callback/myBasicAuth"
    </Location>
</VirtualHost>

Then, enable it using a2ensite sso.conf, followed by a restart of Apache2.

11 - Authentication Through Bitbucket Cloud

Overview

One of the login options for dex uses the Bitbucket OAuth2 flow to identify the end user through their Bitbucket account.

When a client redeems a refresh token through dex, dex will re-query Bitbucket to update user information in the ID Token. To do this, dex stores a readonly Bitbucket access token in its backing datastore. Users that reject dex’s access through Bitbucket will also revoke all dex clients which authenticated them through Bitbucket.

Configuration

Register a new OAuth consumer with Bitbucket ensuring the callback URL is (dex issuer)/callback. For example if dex is listening at the non-root path https://auth.example.com/dex the callback would be https://auth.example.com/dex/callback.

There are several permissions required for an OAuth consumer to use it with Dex:

Account: Read - required for extracting base information (email, username)
Workspace membership: Read - only necessary to get user’s teams

The following is an example of a configuration for examples/config-dev.yaml:

connectors:
- type: bitbucket-cloud
  # Required field for connector id.
  id: bitbucket-cloud
  # Required field for connector name.
  name: Bitbucket Cloud
  config:
    # Credentials can be string literals or pulled from the environment.
    clientID: $BITBUCKET_CLIENT_ID
    clientSecret: $BITBUCKET_CLIENT_SECRET
    redirectURI: http://127.0.0.1:5556/dex/callback
    # Optional teams whitelist, communicated through the "groups" scope.
    # If `teams` is omitted, all of the user's Bitbucket teams are returned when the groups scope is present.
    # If `teams` is provided, this acts as a whitelist - only the user's Bitbucket teams that are in the configured `teams` below will go into the groups claim.  Conversely, if the user is not in any of the configured `teams`, the user will not be authenticated.
    teams:
    - my-team
    # Optional parameter to include team groups.
    # If enabled, the groups claim of dex id_token will looks like this:
    # ["my_team", "my_team/administrators", "my_team/members"]
    includeTeamGroups: true

12 - Authentication Through the builtin connector

Overview

Dex comes with a built-in local connector, acting as a “virtual” identity provider within Dex’s ecosystem, securely storing login credentials in the specified storage. This local connector simplifies authentication workflows by managing and storing user credentials directly within Dex’s infrastructure.

Configuration

The local connector can be utilized by adding the following flag to the configuration.

enablePasswordDB: true

Creating Users

Once the local connector is enabled, users can be added in two ways: statically within the configuration file or dynamically through the gRPC API.

Static configuration (config file)

staticPasswords:
  - email: "admin@example.com"
    # bcrypt hash of the string "password": $(echo password | htpasswd -BinC 10 admin | cut -d: -f2)
    hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
    username: "admin"
    userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"

To specify users within the configuration file, the staticPasswords option can be used. It contains a list of predefined users, each defined by the following entities:

email: The email address of the user (used as the main identifier).
hash: The bcrypt hash of the user’s password.
username: The username associated with the user.
userID: The unique identifier (ID) of the user.

Dynamic configuration (API)

Users can be dynamically managed via the gRPC API, offering a versatile method to handle user-related operations within the system. This functionality enables seamless additions, updates, and removals of users, providing a flexible approach to user management. For comprehensive information and detailed procedures, please refer to the specific API documentation.

Obtaining a token

Let’s explore a sample configuration in dex that involves a public and private client along with a static user. Both local users and password grants are enabled, allowing the exchange of a token for user credentials.

issuer: http://localhost:8080/dex
storage:  # .. storage configuration
# Setup clients
staticClients:
  - id: public-client
    public: true
    name: 'Public Client'
    redirectURIs:
      - 'https://example.com/oidc/callback'
  - id: private-client
    secret: app-secret
    name: 'Private Client'
    redirectURIs:
      - 'https://example.com/oidc/callback'
# Set up an test user
staticPasswords:
  - email: "admin@example.com"
    # bcrypt hash of the string "password": $(echo password | htpasswd -BinC 10 admin | cut -d: -f2)
    hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
    username: "admin"
    userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"

# Enable local users
enablePasswordDB: true
# Allow password grants with local users
oauth2:
  passwordConnector: local

Depending on whether you use a public or a private client you need to either include the just clientId or the clientId and clientPassword in the authorization header.

Public Client

curl -L -X POST 'http://localhost:8080/dex/token' \
-H 'Authorization: Basic cHVibGljLWNsaWVudAo=' \ # base64 encoded: public-client
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=openid profile' \
--data-urlencode 'username=admin@example.com' \
--data-urlencode 'password=admin'

Private Client

curl -L -X POST 'http://localhost:8080/dex/token' \
-H 'Authorization: Basic cHJpdmF0ZS1jbGllbnQ6YXBwLXNlY3JldAo=' \ # base64 encoded: private-client:app-secret
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=openid' \
--data-urlencode 'username=admin@example.com' \
--data-urlencode 'password=admin'

13 - Authentication using OpenShift

Overview

Dex can make use of users and groups defined within OpenShift by querying the platform provided OAuth server.

Configuration

Creating an OAuth Client

Two forms of OAuth Clients can be utilized:

Using a Service Account as an OAuth Client (Recommended)
Registering An Additional OAuth Client

Using a Service Account as an OAuth Client

OpenShift Service Accounts can be used as a constrained form of OAuth client. Making use of a Service Account to represent an OAuth Client is the recommended option as it does not require elevated privileged within the OpenShift cluster. Create a new Service Account or make use of an existing Service Account.

Patch the Service Account to add an annotation for location of the Redirect URI

oc patch serviceaccount <name> --type='json' -p='[{"op": "add", "path": "/metadata/annotations/serviceaccounts.openshift.io~1oauth-redirecturi.dex", "value":"https://<dex_url>/callback"}]'

The Client ID for a Service Account representing an OAuth Client takes the form system:serviceaccount:<namespace>:<service_account_name>

The Client Secret for a Service Account representing an OAuth Client is the long lived OAuth Token that is configued for the Service Account. Execute the following command to retrieve the OAuth Token.

oc serviceaccounts get-token <name>

Registering An Additional OAuth Client

Instead of using a constrained form of Service Account to represent an OAuth Client, an additional OAuthClient resource can be created.

Create a new OAuthClient resource similar to the following:

kind: OAuthClient
apiVersion: oauth.openshift.io/v1
metadata:
 name: dex
# The value that should be utilized as the `client_secret`
secret: "<clientSecret>" 
# List of valid addresses for the callback. Ensure one of the values that are provided is `(dex issuer)/callback` 
redirectURIs:
 - "https:///<dex_url>/callback" 
grantMethod: prompt

Dex Configuration

The following is an example of a configuration for examples/config-dev.yaml:

connectors:
  - type: openshift
    # Required field for connector id.
    id: openshift
    # Required field for connector name.
    name: OpenShift
    config:
      # OpenShift API
      issuer: https://api.mycluster.example.com:6443
      # Credentials can be string literals or pulled from the environment.
      clientID: $OPENSHIFT_OAUTH_CLIENT_ID
      clientSecret: $OPENSHIFT_OAUTH_CLIENT_SECRET
      redirectURI: http://127.0.0.1:5556/dex/
      # Optional: Specify whether to communicate to OpenShift without validating SSL certificates
      insecureCA: false
      # Optional: The location of file containing SSL certificates to communicate to OpenShift
      rootCA: /etc/ssl/openshift.pem
      # Optional list of required groups a user must be a member of
      groups:
        - users

14 - Authentication Through Atlassian Crowd

Overview

Atlassian Crowd is a centralized identity management solution providing single sign-on and user identity.

Current connector uses request to Crowd REST API endpoints:

/user - to get user-info
/session - to authenticate the user

Offline Access scope support provided with a new request to user authentication and user info endpoints.

Configuration

To start using the Atlassian Crowd connector, firstly you need to register an application in your Crowd like specified in the docs.

The following is an example of a configuration for dex examples/config-dev.yaml:

connectors:
- type: atlassian-crowd
  # Required field for connector id.
  id: crowd
  # Required field for connector name.
  name: Crowd
  config:
    # Required field to connect to Crowd.
    baseURL: https://crowd.example.com/crowd
    # Credentials can be string literals or pulled from the environment.
    clientID: $ATLASSIAN_CROWD_APPLICATION_ID
    clientSecret: $ATLASSIAN_CROWD_CLIENT_SECRET
    # Optional groups whitelist, communicated through the "groups" scope.
    # If `groups` is omitted, all of the user's Crowd groups are returned when the groups scope is present.
    # If `groups` is provided, this acts as a whitelist - only the user's Crowd groups that are in the configured `groups` below will go into the groups claim.  
    # Conversely, if the user is not in any of the configured `groups`, the user will not be authenticated.
    groups:
    - my-group
    # Prompt for username field.
    usernamePrompt: Login
    # Optionally set preferred_username claim.
    # If `preferredUsernameField` is omitted or contains an invalid option, the `preferred_username` claim will be empty.
    # If `preferredUsernameField` is set, the `preferred_username` claim will be set to the chosen Crowd user attribute value.
    # Possible choices are: "key", "name", "email"
    preferredUsernameField: name

15 - Authentication Through Gitea

Overview

One of the login options for dex uses the Gitea OAuth2 flow to identify the end user through their Gitea account.

When a client redeems a refresh token through dex, dex will re-query Gitea to update user information in the ID Token. To do this, dex stores a readonly Gitea access token in its backing datastore. Users that reject dex’s access through Gitea will also revoke all dex clients which authenticated them through Gitea.

Configuration

Register a new OAuth consumer with Gitea ensuring the callback URL is (dex issuer)/callback. For example if dex is listening at the non-root path https://auth.example.com/dex the callback would be https://auth.example.com/dex/callback.

The following is an example of a configuration for examples/config-dev.yaml:

connectors:
- type: gitea
  # Required field for connector id.
  id: gitea
  # Required field for connector name.
  name: Gitea
  config:
    # Credentials can be string literals or pulled from the environment.
    clientID: $GITEA_CLIENT_ID
    clientSecret: $GITEA_CLIENT_SECRET
    redirectURI: http://127.0.0.1:5556/dex/callback
    # optional, default = https://gitea.com
    baseURL: https://gitea.com

16 - Authentication Through OpenStack Keystone

Overview

Keystone is an OpenStack service that provides API client authentication, service discovery, and distributed multi-tenant authorization.

OpenStack Keystone connector supports offline_access and groups scopes. To use this connector, create a domain and user with an admin role, then specify the credentials in the configuration file (see the example below).

OpenStack Keystone exposes the Identity API v3 to work with dex.

Configuration

The following is an example of an OpenStack Keystone configuration for dex:

connectors:
  - type: keystone
    # Required field for connector id.
    id: keystone
    # Required field for connector name.
    name: Keystone
    config:
      # Required, without v3 suffix.
      keystoneHost: http://example:5000
      # Required, admin user credentials to connect to keystone.
      domain: default
      keystoneUsername: demo 
      keystonePassword: DEMO_PASS

Connectors

1 - Authentication Through LDAP

Overview

Getting started

Security considerations

Configuration

Example: Mapping a schema to a search config

Example: Searching a FreeIPA server with groups

Example: Searching a Active Directory server with groups

2 - Authentication Through GitHub

Overview

Caveats

Configuration

GitHub Enterprise

Generate TLS assets

Run example client app with GitHub config

3 - Authentication through SAML 2.0

WARNING

Overview

Caveats

Group Filtering

Configuration

4 - Authentication Through GitLab

Overview

Configuration

5 - Authentication Through an OpenID Connect Provider

Overview

Configuration

6 - Authentication Through an OAuth 2.0 Provider

Overview

Configuration

7 - Authentication Through Google

Overview

Configuration

Fetching groups from Google

Consent Screen

8 - Authentication Through LinkedIn

Overview

Configuration

9 - Authentication Through Microsoft

Overview

Caveats

Configuration

Groups

10 - Authenticating Proxy

Overview

Configuration

Configuration example - Apache 2

Full Apache2 setup

11 - Authentication Through Bitbucket Cloud

Overview

Configuration

12 - Authentication Through the builtin connector

Overview

Configuration

Creating Users

Static configuration (config file)

Dynamic configuration (API)

Obtaining a token

13 - Authentication using OpenShift

Overview

Configuration

Creating an OAuth Client

Using a Service Account as an OAuth Client

Registering An Additional OAuth Client

Dex Configuration

14 - Authentication Through Atlassian Crowd

Overview

Configuration

15 - Authentication Through Gitea

Overview

Configuration

16 - Authentication Through OpenStack Keystone

Overview

Configuration