V2 API release

This release publishes the existing V2 API under a separate module.

The existing API package will remain available for backward compatibility reasons,
but new features will only be added to the new module.

Usage

Although Dex remains backward compatible and continues to provide the API under the original location,
we highly recommend replacing it with the new location in your project (if you use the official API package):

go get github.com/dexidp/dex/api/[email protected]

Then replace every occurrence of github.com/dexidp/dex/api with github.com/dexidp/dex/api/v2 in your code.

Finally, make sure to get rid of the main Dex module dependency:

go mod tidy

We also recommend using the new API module instead of manually downloading the proto and generating client stubs using protoc.
Read more about the reasons below. (tl;dr: certain future changes might break backward compatibility for these consumers)

History

Dex V2 came with a major rewrite of its API using gRPC and Protobuf.
Consumers of this new API generally followed one of two paths in their applications:

Many users imported the github.com/dexidp/dex/api package directly.
While this worked quite well for most of the time,
it introduced a dependency between consuming projects and the main Dex module itself (with all of its own dependencies).
Sometimes this caused conflicts with other dependencies of the project (aka. dependency hell).
Using Dex this way also forced us to remain backward compatible in a bunch of other areas.

To solve the dependency problem, many consumers decided to download the single proto file from the repository
and generate client stubs themselves. This turned out to be a great alternative to importing the whole Dex project
(just to use its generated API package).

Changes in Protocol Buffers

For quite some time, we wanted to break this status quo.
We tried to steer users away from importing Dex and recommended generating stubs instead.

Ultimately, the recent changes introduced in the Protobuf V2 API for Go lead us to our current solution.
Namely, the new requirement of having a go_package directive in every proto file basically forces us to provide a package with generated code and
makes code generation on the consumer side nearly impossible. (Obviously, someone can hack around this limitation, but it can't be solved nicely)

Although this requirement does not affect us at the moment, since we still use the V1 API for Protobuf,
in the future we might want to upgrade to the new API. So we decided to find a better, official place for the Dex API that consumers can use
without depending on the Dex project itself.

Dedicated API package

We spent some time with experimenting, trying to find the best possible option.
We wanted to find a solution that's backward compatible, but also fits into our future plans with Dex.

After a few iterations, we ended up creating a new package under the original API package, called /v2 and we made it a separate Go module.
This allows us to keep the API close to the main project and lets consumers import the API without the rest of Dex's dependencies.

The first tag of this package is v2.0.0 and we intend to keep versioning this package, separately from the main Dex project.
When adding new features to the API, we will tag new minor versions. Breaking changes will result in a new major version of the API,
which may also result in a major Dex version, but that's still in the future.

Thanks to protobuf's backward compatibility (and our BC promise for the API),
you should be able to talk to Dex with older API versions (compared to the one compiled into Dex itself),
but we recommend using the same version. Although the proto itself should be backward compatible,
the API package depends on gRPC, which is (unfortunately) known to break things between different versions
(thanks to the relatively large shared library).

Future of Dex's API

We have plans to extend the API with new features. Most of them should be backward compatible changes,
so they will likely be added to the v2 API.

That being said, there are a bunch of changes that will break backward compatibility and as such, will require a v3 release.
Although we know it will happen, we don't have it on our near term roadmap. Whether the v2 and v3 will coexist or not is still undecided,
but there is a chance they can.

---

If you have any questions related to this release, feel free to open an issue or reach out on the #dexidp
channel in the Kubernetes Slack workspace.

v2.24.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.24.0

Features:

• Keystone connector: Added Email to Identity (#1681, @kenperkins, @chrigl)
• Atlassian Crowd connector: allow preferred_username claim to be set (#1684, @ mvdkleijn)
• Github connector: pass redirect_uri (#1700, @sockmister)
• server: allow having no secret for static public clients (#1701, @tkleczek)
• SAML connector: add flag for filtering groups (#1704, @srenatus)

Bug fixes, misc changes:

• CI: add mysql service (#1674, @bonifaido)
• CI: increase go lint timeout (#1676, @bonifaido)
• storage/kubernetes: wrap Kubernetes host address in square brackets for IPv6 (#1645, @JerrySunWRS)
• storage/kubernetes: remove shadowed ResourceVersion from connector (#1673, @ktravis)
• server/handlers: do not fail login if refresh token gone (#1670, @klarose)
• server/handlers: automatic consistency fixing in case of missing refresh token in db (#1678, @Teeed)
• Adding slack channel to README (#1686, @kenperkins)
• OIDC connector: add Icon (#1692, @nabokihms)
• OpenShift connector: rootCA option (#1694, @nabokihms)

v2.23.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.23.0

Features:

• connector: Atlassian Crowd connector (#1515 , @diafour, @nabokihms )
• connector/ldap: add multiple user to group mapping (#1612, @vi7 )
• Add support for password grant (#926, @xtremerui, Zach Brown)
• Add ability to set ID and Secret from environment variables for static clients (#1664, @yann-soubeyrand, @lhotrifork)

Bugfixes:

• Provider icons use the connector name, not the ID (#1576, @nabokihms)
• storage/mysql: increase auth_request.state length to 4096 (#1659, @bonifaido )

Minor changes:

• dependency upgrades (#1640, #1641, @sagikazarmark )
• storage/sql: allow specifying sql flavor specific migrations (#1659)
• Make prompt configurable for OIDC offline_access (#1656, @commixon )
• Setting email for OpenShift connector (#1661 , @sabre1041)
• Various documentation fixes (#1644, @cmurphy #1648, @int128)

v2.22.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.22.0

Features:

• google: Implement group whitelisting (#1591, @bonifaido)
• Read static password hash from environment variable (#1601, @krishnadurai)
• OpenShift connector (#1599, @sabre1041)

Bugfixes:

• Provider icons use the connector name, not the ID (#1576, @nabokihms)
• MySQL idle connection limiet (#1609, @PeopleRange)
• OIDC Email scope check (#1610, @nabokihms)
• google: Fix group retrieval (#1627, @jfrabaute)
• Prometheus is optional for the server (#1625, @xtremerui)

Minor changes:

• Moved to GitHub actions from TravisCI (#1596, #1605, @sagikazarmark)
• Improved conformance tests (#1556, @tkleczek)
• Upgraded Go to 1.13 and Alpine to 3.10 (#1592, @bonifaido)
• Improved code quality by introducing better linter settings (#1603, #1604, @sagikazarmark)
• microsoft: Improved connector tests (#1622, @chlunde)

v2.21.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.21.0

Notes:

The "only" main feature of this release is around OIDC and Google groups which were pretty long-awaited. 🎉

Features:

• Implement refreshing with Google (#1180, @JoelSpeed)
• Fetch groups in a Google Connector (#1185, @JoelSpeed)
• Add option to enable groups for oidc connectors (#1434, @jacksontj)

Bugfixes:

• Fix spelling errors in docs (#1569, @bhageena)
• preferred_username claim added on refresh token (#1586, @serhiimakogon)

v2.20.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.20.0

Notes:

The preferred_username OIDC claim was added to the ID Token in case of GitLab, GitHub, LDAP. This claim could be extended to other providers as well later on.

Features:

• connector/saml: Adding group filtering (#1544, @kenperkins)
• Run getUserInfo prior to claim enforcement (#1545, @jacksontj)
• server: templates: use relative URLs to refer to assets (#1554, @yanniszark)
• add preffered_username to idToken (#1566, @bonifaido )

Bug fixes, misc changes:

• gitlab: add groups scope by default when filtering is requested (#1520, @bonifaido)
• Fix typo (#1543, @wassan128)
• Fix typo (#1551, @gosharplite)
• storage/mysql: support pre-5.7.20 instances with tx_isolation only (#1550, @bonifaido)
• Fix URLs in curl cmd as stated in the overview doc (#1558, @aijingyc)
• Add note for redirect uri (#1568, @life1347)

v2.19.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.19.0

Notes:

• Following Mozilla's recommendations for secure TLS settings in the
  "Intermediate" compatibility mode, some insecure cipher suitess have been
  removed, overriding Golang's standard set of ciphers. In the unlikely event
  that this makes one of your clients NOT work with Dex anymore (and there's
  a decent reason for not being able to update that client), please file an
  issue. See #1540 for details.
• As mentioned in documentation, Kubernetes TPR suppport is removed in this
  release.

Features:

• connector/LDAP: display login error (#1530, @bonifaido)
• HTTPS/gRPC: Use a more conservative set of CipherSuites (#1540, @stevendanna)

Bug fixes, misc changes:

• Update ADOPTERS.md (#1534, @jthabet)
• storage/kubernetes: Removing Kubernetes TPR support (#1517, @venezia)
• Dockerfile: build with Golang 1.12.9 (#1529, @dkuerner)
• Kubernetes docs: Clarify the origin of openid-ca (#1521, @erwinvaneyk)
• Code update: Replace x/net/context with stdlib context (#, @erwinvaneyk)

v2.18.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.18.0

Features:

• Storage: New MySQL storage backend (#1485, @bonifaido)
• gRPC: Add reflection to gRPC API (#1512, @venezia)
• Add option to always display connector selection even if there's only one (#1505, @MarcDufresne)
• Added "connector_id" to skip straight to a connector (#1481, @LanceH)
• Allow arbitrary data to be passed to templates (#1504, @MarcDufresne)
• Gitlab: implement useLoginAsID as in GitHub connector (#1497, @bonifaido)
• Microsoft: option for group UUIDs instead of name and group whitelist (#1446, @maksd)
• gRPC: Add VerifyPassword to API (#1486, @AlbanSeurat)

Bug fixes, misc changes:

• MAINTAINERS: add @bonifaido (#1492, @srenatus)
• Update ADOPTERS.md (#1495, @pbochynski; #1494, @tanmaykm; #1493, @srenatus)
• example-app: add connector_id (#1496, @srenatus)
• Docs: fix MySQL sample query (#1498, @mkontani)
• Code quality: fix some lint issues (#1500, @srenatus)
• gRPC: fix logging in VerifyPassword (#1502, @srenatus)
• Return config validation errors in one go (#1439, @sks)
• Update all deps (#1501, @srenatus)
• Return HTTP 400 for invalid state parameter (#1490, @momokatte)
• Adjusting Makefile so that golint will compile (#1509, @venezia)
• Add tests for some callback handler error conditions (#1510, @momokatte)
• Add examples for recent additions to oauth2 configuration options (#1516, @tpdownes)
• Bump deps for http2 issues (#1519, @srenatus)
• Connectors: refactor filter code into a helper package (#1480, @srenatus)

v2.17.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.17.0

Notes:

• Dex finally offers a user info endpoint. While this doesn't expose any
  more information than is included in the ID tokens, it allows for using
  Dex in integrations that demand such an endpoint.
• With this release, the Linkedin connector is usable again!

Features:

• Add UserInfo endpoint (#1473, @alindeman, @jackielii, and @fjbsantiago)
• Linkedin: Update to use v2 APIs (#1460, @tanmaykm)
• server: add metrics for CORS handlers (#1429, @tsuna)
• OIDC: Add option to hit the optional userinfo endpoint (#1433, @jacksontj)
• OIDC: Make userID configurable (#1448, @cappyzawa)
• OIDC: Make userName configurable (#1459, @flarno11)
• GitLab: support for group whitelist (#1436, @bonifaido)

Bug fixes, misc changes:

• Print appropriate error when listing connectors fails (#1443, @deric)
• Bitbucket docs: update permission requirements (#1435, @bonifaido)
• Round out logging interface with functions for all levels (#1432, @alindeman)
• Fix typo in SAMLConnector interface (#1430, @mkontani)
• travis: replace golang 1.10 and 1.11 with 1.12 (#1457, @srenatus)
• OIDC: truely ignore "email_verified" claim if configured that way (#1456, @srenatus)
• MAINTAINERS: remove ericchiang@ (#1478, @ericchiang)

v2.16.0

The official docker release for this release can be pulled from

quay.io/dexidp/dex:v2.16.0

Features:

• Add an option to the OpenID Connect connector to always set email_verified to true (#1417, @gezb)
• Docker image no longer runs dex as root (#1426, @justaugustus)

Bug fixes, misc changes:

• Dex now logs client name instead of client_id (#1427, @yann-soubeyrand)
• Fixes for Go 1.11.4 modules (#1402, @lstoll)
• Refactor logging to use an interface instead of logrus directly (#1408, @sagikazarmark)