We’re thrilled to announce the release of Ory Hydra 2.3.0! This version comes packed with graceful token refresh, performance improvements, and fixes that enhance stability, reduce database load, and streamline the developer experience. We strongly recommend upgrading to take advantage of these enhancements and ensure the best possible OAuth2 and OpenID Connect experience with Ory Hydra. Thank you to everyone who contributed!
Ory Hydra now supports graceful refresh token rotation, making OAuth2 and OpenID Connect refresh flows significantly more resilient in scenarios such as Single Page Apps and IoT. Even in highly distributed or concurrent environments, Hydra gracefully handles token refreshes reliably, ensuring tokens are not dropped or double-used.
Previously, the redirect_uri was not required when performing flows with scope=openid. This release enforces the requirement to comply with the OpenID Connect standard.
PR: #3900
Hydra now supports explicit SQL migration commands migrate sql up|down|status that streamline database schema management and help with zero-downtime upgrades.
PR: #3894
- Access token strategy & advanced CLI improvements
The CLI introduces new parameters and an option to specify a custom client ID on creation, making it easier to manage and script Hydra deployments.
PRs: #3718, #3725, #3874 - Built-in login & consent UI for
hydra perform authorization-code
A minimal built-in UI for login and consent can be enabled when testing with the CLI, removing the need to spin up a separate service.
PR: #3845
Unused indices have been removed, down migration scripts renamed for consistency, and all migrations are more efficient overall.
-
Improve persistence logic – Database transactions and concurrency have been improved across the authorization and token handlers.
PRs: #3756, #3763, #3886 -
Support for more claims in password grant – You can now include additional claims in the password grant flow, providing extra flexibility in advanced scenarios. Only available with an Ory Enterprise License.
PR: #3864 -
Transaction Wrappers
Authorization and token issuance are now wrapped more consistently to prevent partial writes and race conditions.
PRs: #3730, #3763 -
Improved Docker setup
Docker configurations have been refined, removing inconsistencies in the Compose setup and enabling a fully static binary build.
PRs: #3826, #3924 -
Proper JSON round-tripping
Fixed an issue causing custom claims to break if they were nested or unexpectedly typed. JSON round-trips are now correct.
PR: #3819 -
Speed up public key retrieval
Reduced overhead for the JWK public endpoint, solving CPU contention issues in large-scale deployments.
PRs: #3787, #3870 -
Fix Docker Compose references
The CLI now properly referencesdocker composeinstead ofdocker-compose, ensuring compatibility with modern Docker setups.
PR: #3815 -
Dependency upgrades
Bumpedfosite,ory/x,pgx/v5, and various third-party libraries for improved stability and performance. -
Updated docs
Updated examples, improved JWK documentation, added notes on Docker Compose usage, and refined OpenID Connect discovery docs. -
More tracing context
Tracing calls have been consistently standardized withotelx.End(), and additional context ensures better observability. -
Code generation & housekeeping
Various housekeeping tasks: pinned GHA versions, fixed minor comment typos, updated newsletters/links, and more.
To upgrade to 2.3.0, follow the usual steps:
- Back up your database (always recommended).
- Update your Hydra version in your Docker configuration, binary, or build to
v2.3.0. - Run
hydra migrate sql up(if using the new commands) or your usual migration procedure. - Restart your services and confirm that Hydra is up and running.
Check the migration docs for detailed information.
As always, we love hearing from our community. Here are some ways to get involved:
- Join our Slack: Ory Community Slack
- Ask questions on GitHub Discussions: Ory Hydra Discussions
- Submit bugs and feature requests: GitHub Issues
Thanks to all contributors for making Ory Hydra the best-in-class OAuth2 and OpenID Connect server.
For Ory Hydra v2.4.0 we are looking at another highly anticipated community-contributed feature, the OAuth 2.0 Device Authorization Grant!
Full Changelog: v2.2.0...v2.3.0
Happy building with Ory Hydra!
Breaking Changes
Going forward, OAuth2 Clients requesting an OpenID Connect flow must include the redirect_uri parameter or the request will be rejected.
Deleting consents no longer returns 404 in certain edge cases but instead always 204.
Bug Fixes
-
Advertise support for response_mode=form_post in OIDC discovery document (#3861) (9cc5f28)
-
Broken JSON round-tripping for custom claims (b36b701):
Adding custom claims with numerical types (think JavaScript Number) previously did not
round-trip through Hydra correctly. For example, passing UNIX timestamps in custom claims
would end up as floating points in exponential notation in the final token. That, in turn,
confused or broke downstream consumers of the token, including Kratos. -
Change comment on revokeOAuth2LoginSessions (#3853) (6d829dd)
-
Correct span names (554238b)
-
Correctly pass multiple token audiences and prompt parameters when performing the authorization code flow from the CLI (#3736) (632faef)
-
Cpu contention when reading JWKs and suppress generating duplicate JWKs (#3870) (d5f65c5):
Previously each concurrent caller would need to lock a shared mutex when reading or writing a given JWK set.
The read path now doesn't require locking a mutex at all and instead returns valid query results directly.The write path is now protected by a concurrency control mechanism (using x/sync/singleflight) to ensure only one JWK set is generated and persisted.
Note: Duplicate JWK sets may still be improperly generated if running more than one Hydra instance in a high traffic environment.
-
Do not iteratively delete records (#3766) (5ef20a2):
Resolves performance issues on some databases when deleting consent.
-
docs: Adjust note about SDK support on oauth2 flow endpoints (#3812) (d0e047c)
-
Error log when RP responds with status code 204 (#3731) (153e4b5)
-
Faster GetPublicKeys (#3787) (04c34aa):
GetPublicKeys used to fetch all keys in a set, even if they were actually not being used. This patch fixes that.
-
Improve docker set up (#3924) (8ca6cbd), closes #3914 #3683:
Improves the docker set up and removes some unused files.
-
Incorrect context passthru (fa50e3e)
-
Limit HTTP response size (2559819)
-
Omit explicit transaction in ConfirmLoginSession and add tracing (#3886) (a5b2d75)
-
Pass context to database ping (fa21711)
-
Require
redirect_uriin openid requests (#3900) (5caa629):Resolves a deviation from the OpenID Connect spec, where the
redirect_uriwas not required when performing flows withscope=openid. -
Untyped int build issues on 32bit architectures (#3885) (68aa167)
-
Upgrade fosite and improve webhook integration (#3727) (89323e2)
-
Use docker compose rather than docker-compose (#3815) (ffdfb73)
Code Generation
- Pin v2.3.0 release commit (ee8c339)
Documentation
Features
-
Add access token strategy parameter to cli (#3718) (7862dc3), closes #3717
-
Add expiry and requested times to logout table (#3837) (f83193f)
-
Add id parameter to create oauth2-client cli (#3725) (b372fd2):
Fixes #3724
-
Add Inspect option to registry (2013450)
-
Add migrate sql up|down|status (#3894) (d27882f):
This patch adds the ability to execute down migrations using:
hydra migrate sql down -e --steps {num_of_steps}Please read
hydra migrate sql down --helpcarefully.Going forward, please use the following commands
hydra migrate sql up ... hydra migrate sql status ...instead of the previous, now deprecated
hydra migrate sql ... hydra migrate status ...commands.
-
Built-in login/consent UI for
hydra perform authorization-code(#3845) (7f8bd90) -
Graceful refresh token rotation (#3860) (e278b40), closes #1831 #3770:
This patch adds a configuration flag which enables graceful refresh token rotation. Previously, refresh tokens could only be used once. On reuse, all tokens of that chain would be revoked.
This is particularly challenging in environments, where it's difficult to make guarantees on synchronization. This could lead to refresh tokens being sent twice due to some parallel execution.
To resolve this, refresh tokens can now be graceful by changing
oauth2.grant.refresh_token.grace_period=10s(example value). During this time, a refresh token can be used multiple times to generate new refresh, ID, and access tokens.All tokens will correctly be invalidated, when the refresh token is re-used after the grace period expires, or when the delete consent endpoint is used.
-
Handle concurrent refreshes and improve graceful refreshing (#3895) (0a6c966):
This patch improves Ory Hydra's ability to deal with refresh flows which, for example, concurrently refresh the same token. Furthermore, graceful token refresh has been improved to handle a variety of edge cases and scenarios.
Additionally, serializability errors in CockroachDB are now correctly retried.
See ory-corp/cloud#7311
Closes #3895 -
Support more claims in password grant (#3864) (41476ec):
For the resource owner password grant, the Kratos identity ID is now written to the sub claim, and the username is written to the ext.username claim. Further, token hooks are called for the initial token issuance as well as refresh flows for access tokens issued via the resource owner password grant, allowing users to customize the fields present in the access token (for the jwt strategy) as well as on introspection.
Tests
Unclassified
- Include Requested Scopes in Webhook Requests (#3891) (c3ff306), closes #3891
- update doc example for get oauth2-client (5e70cde)
Artifacts can be verified with cosign using this public key.