dexidp/dex: an OIDC provider that defers to your existing identity systems

The problem dex solves: one OIDC endpoint in front of many identity backends

Most organizations do not have one place where identities live. They have an LDAP directory, a GitHub organization, a Google Workspace tenant, maybe an Active Directory forest, and a pile of internal apps that each need to know who is signing in. Without a broker, every app implements a different integration, and every new upstream provider becomes a change in every app.

Dex inverts that. The README describes it as an identity service that uses OpenID Connect to drive authentication for other apps, and as a portal to other identity providers through connectors. Clients write their authentication logic once, against dex, and dex handles the protocol for whichever backend the user actually belongs to. The intended audience is platform and infrastructure engineers, particularly the Kubernetes crowd: the repository topics include kubernetes, oidc and identity-provider, and the README documents running dex on a cluster to drive API server authentication through the OpenID Connect plugin.

It is not a user directory. Dex does not want to own your users. The README is explicit that a user's identity is usually stored in another user-management system, and dex acts as a shim between the client app and that system. If you are looking for a product where you create accounts, manage passwords and run the admin console, this is the wrong shape of tool.

How dex works: connectors, ID tokens and the capability table

The mechanism is a two-sided translation. On the client side, dex speaks OpenID Connect and OAuth 2.0. On the upstream side, it speaks whatever the connector implements. A connector is, in the README's wording, a strategy used by dex for authenticating a user against another identity provider.

The output of a successful login is an ID Token: a JSON Web Token signed by dex and returned as part of the OAuth2 response. The README shows the claim set, including iss, sub, aud, exp, iat, at_hash, email, email_verified, groups and name. Because those are standards-based claims and the token is signed by dex, downstream systems that already consume OIDC ID Tokens can use them as service-to-service credentials. The README names Kubernetes and AWS STS as two such consumers.

The part worth reading carefully is the connector table. Each connector is listed with whether it supports refresh tokens, whether it supports the groups claim, and whether it supports preferred_username. That is not decoration; it is the contract your clients inherit. The README gives the concrete example: because SAML does not provide a non-interactive way to refresh assertions, a user who logs in through the SAML connector will not receive a refresh token, and refresh token support is required for clients that need offline access, such as kubectl.

The table also carries maturity labels: stable (well tested, in active use, will not change in backward incompatible ways), beta (tested, unlikely to change incompatibly) and alpha (may be untested). LDAP, GitHub and SAML 2.0 are stable. GitLab, the generic OpenID Connect connector, LinkedIn, Microsoft, Atlassian Crowd and Gitea are beta. OAuth 2.0, Google, AuthProxy, Bitbucket Cloud, OpenShift and OpenStack Keystone are alpha. Note that Google, a connector many people would reach for first, is alpha here.

One line in that table deserves to be quoted rather than paraphrased: the SAML entry carries a warning that it is unmaintained and likely vulnerable to auth bypasses, pointing to discussion #1884. A stable label and an unmaintained warning on the same row is an uncomfortable combination, and it is the single strongest reason to check the connector you plan to use before you plan anything else.

Installing dex and running a first real login

The repository ships a Dockerfile and a docker-compose.yaml whose comment says it provides quick setups for testing different storage backend options. The compose file defines mysql (mysql:5.7), mysql8 (mysql:8.0), postgres (postgres:10.15), etcd (gcr.io/etcd-development/etcd:v3.5.0) and an ldap service based on osixia/openldap:1.4.0. Those are the storage and directory backends dex can be pointed at.

The Dockerfile stages a config file at /etc/dex/config.docker.yaml and creates /var/dex for data, and it builds the dex binary plus a docker-entrypoint binary. The entrypoint is why the image can be configured with environment variables rather than a hand-written file: the Dockerfile also stages gomplate (GOMPLATE_VERSION=v5.2.0) into the image, which renders the config template at container start.

If you build from source instead, the Makefile is the entry point. The build target depends on bin/dex, which runs go install against the cmd/dex package with version ldflags injected. The examples target builds two helper binaries, bin/example-app and bin/grpc-client.

make build

That produces bin/dex. The README's own sample configuration uses port 5556 for dex, visible in the example issuer URL http://127.0.0.1:5556/dex and in the sample ID Token's iss claim. A minimal config file names the issuer, the storage backend and a connector; config.yaml.dist and config.dev.yaml in the repository root are the reference starting points.

The fastest way to see a real login is to run dex alongside the example app. The Makefile builds the example app into bin/example-app, and the README's JWT sample shows the audience value example-app, which is the client ID that example app registers with.

make examples

After that, the login flow is: the example app redirects the browser to dex, dex redirects to the configured connector, the user authenticates upstream, and dex returns to the app with a signed ID Token. What you should see is the claim set from the README: an iss pointing at your dex issuer, an aud matching the client, an exp, and depending on the connector, email, groups and name. If groups is missing, that is the connector table talking, not a bug.

Where dex is the wrong tool

The most direct limitation is the SAML connector. The README labels it stable and simultaneously warns that it is unmaintained and likely vulnerable to auth bypasses. If SAML is your only upstream protocol, dex is not a safe default, and the warning is in the project's own documentation rather than in a third-party review.

Second, capability is unevenly distributed across connectors. Refresh tokens and the groups claim are per-connector properties. A client that needs offline access, such as kubectl, will not work through a connector that cannot refresh. The README states this for SAML specifically, and the table shows the same gap for the OAuth 2.0 and AuthProxy connectors. Planning a deployment around dex without reading that table is how you end up discovering the constraint in production.

Third, several of the connectors you might want are alpha: Google, OAuth 2.0, AuthProxy, Bitbucket Cloud, OpenShift and OpenStack Keystone. Alpha is defined in the README as possibly untested. That is a different risk posture from the stable rows, and it should shape which upstream you federate first.

Finally, dex does not replace an identity store. There is no user directory to populate. If your requirement is a self-contained IdP with its own accounts, dex will feel like half a product, because that half is deliberately absent.

Dex compared with Keycloak: broker versus full identity platform

The comparison people actually search for is Keycloak versus dex, and the difference is architectural rather than feature-by-feature. Keycloak is a full identity and access management platform: it owns users, it ships an administrative console, and it can be the system of record. Dex is a federated broker. It has no user directory to speak of, and it exists to translate between OIDC clients and upstream providers you already run.

That distinction decides most deployments. If your organization wants one place to create and manage accounts, dex is the wrong category. If your organization already has directories and SaaS identity providers and wants every internal app to integrate with OIDC exactly once, dex is the smaller, more focused fit, and the connector table is the whole product surface you need to evaluate.

The second practical difference is deployment shape. Dex runs natively on Kubernetes using Custom Resource Definitions, and the README documents using it to drive API server authentication through the OpenID Connect plugin, with clients such as kubelogin and kubectl acting on behalf of users. That Kubernetes-native path, plus the Go codebase and the Apache-2.0 licence, is what pulls infrastructure teams toward dex rather than a Java application server.

Maintenance, upgrades and what the Apache-2.0 licence means here

The repository is not archived, and the last push was on 2026-09-21. Releases are tagged and dated: v2.45.1 on 2026-03-03, v2.45.0 on 2026-02-23, and v2.44.0 on 2025-09-01. The gap between v2.44.0 and v2.45.0 is roughly six months, so the release cadence is not rapid, and a deployment plan should not assume frequent minor upgrades.

The stability labels in the connector table are the upgrade contract. Stable connectors are documented as not changing in backward incompatible ways; beta connectors are unlikely to; alpha connectors may be untested. Upgrading dex is therefore mostly a question of which connectors you enabled, because that is where incompatible change is most likely to appear.

On licensing: dex is Apache-2.0, and the repository carries a LICENSE file at the root. Apache-2.0 is a permissive licence with an explicit patent grant and a requirement to preserve notices, but this is a description of the licence identifier, not legal advice. If you are embedding dex in a product or redistributing a modified image, have counsel read the actual LICENSE file rather than relying on the identifier.

One operational cost worth naming: the Docker image renders its configuration through gomplate at startup, and the Dockerfile pins GOMPLATE_VERSION. That is a build-time dependency you inherit if you base your own image on theirs.

Editorial conclusion

Adopt dex when you have several upstream identity systems and want client apps to integrate with OIDC once instead of once per backend, and when you accept that connector capability, not dex itself, sets the ceiling on refresh tokens and group claims. Do not adopt it if you need a product with a built-in user directory, a self-service admin UI, or a maintained SAML connector: the README marks SAML as unmaintained and likely vulnerable to auth bypasses. Before committing, verify which connector you will use and read its row in the connector table, since that row determines whether offline access such as kubectl works at all.

Frequently asked questions

Official sources

1. dexidp/dex on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases