Tags

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.

PRs: [#3860](https://github.com/ory/hydra/pull/3860), [#3895](https://github.com/ory/hydra/pull/3895)

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](https://github.com/ory/hydra/pull/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](https://github.com/ory/hydra/pull/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](https://github.com/ory/hydra/pull/3718), [#3725](https://github.com/ory/hydra/pull/3725), [#3874](https://github.com/ory/hydra/pull/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](https://github.com/ory/hydra/pull/3845)

Unused indices have been removed, down migration scripts renamed for consistency, and all migrations are more efficient overall.

PRs: [#3859](https://github.com/ory/hydra/pull/3859), [#3911](https://github.com/ory/hydra/pull/3911)

- **Improve persistence logic** – Database transactions and concurrency have been improved across the authorization and token handlers.
PRs: [#3756](https://github.com/ory/hydra/pull/3756), [#3763](https://github.com/ory/hydra/pull/3763), [#3886](https://github.com/ory/hydra/pull/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](https://github.com/ory/hydra/pull/3864)

- **Transaction Wrappers**
Authorization and token issuance are now wrapped more consistently to prevent partial writes and race conditions.
PRs: [#3730](https://github.com/ory/hydra/pull/3730), [#3763](https://github.com/ory/hydra/pull/3763)
- **Improved Docker setup**
Docker configurations have been refined, removing inconsistencies in the Compose setup and enabling a fully static binary build.
PRs: [#3826](https://github.com/ory/hydra/pull/3826), [#3924](https://github.com/ory/hydra/pull/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](https://github.com/ory/hydra/pull/3819)
- **Speed up public key retrieval**
Reduced overhead for the JWK public endpoint, solving CPU contention issues in large-scale deployments.
PRs: [#3787](https://github.com/ory/hydra/pull/3787), [#3870](https://github.com/ory/hydra/pull/3870)
- **Fix Docker Compose references**
The CLI now properly references `docker compose` instead of `docker-compose`, ensuring compatibility with modern Docker setups.
PR: [#3815](https://github.com/ory/hydra/pull/3815)

- **Dependency upgrades**
Bumped `fosite`, `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 with `otelx.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:

1. **Back up your database** (always recommended).
2. **Update your Hydra version** in your Docker configuration, binary, or build to `v2.3.0`.
3. **Run `hydra migrate sql up`** (if using the new commands) or your usual migration procedure.
4. **Restart your services** and confirm that Hydra is up and running.

Check the [migration docs](https://www.ory.sh/docs/hydra/self-hosted/upgrade) for detailed information.

As always, we love hearing from our community. Here are some ways to get involved:

- **Join our Slack**: [Ory Community Slack](https://www.ory.sh/chat)
- **Ask questions on GitHub Discussions**: [Ory Hydra Discussions](https://github.com/ory/hydra/discussions)
- **Submit bugs and feature requests**: [GitHub Issues](https://github.com/ory/hydra/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](https://github.com/ory/hydra/compare/v2.2.0...v2.3.0)

*Happy building with Ory Hydra!*

![Ory Hydra 2.2.0](http://ory.sh/images/newsletter/hydra-2.2.0/banner.png)

Ory Hydra, the OAuth2 and OpenID Connect server designed for web-scale deployments introduces its most advanced update with version 2.2!

Want to check out Ory Hydra yourself? Try common OAuth2 flows in the [Ory OAuth2 Get Started guide](https://www.ory.sh/docs/getting-started/ory-network-oauth2)!

This version significantly enhances performance, supporting six times more authorization flows than version 2.1, thanks to architectural improvements that minimize database interactions for login and consent processes.

Key improvements include:

- Enhanced integration with Ory Kratos, ensuring seamless synchronization of login and logout states across both services. Users logged out from Ory Hydra will automatically log out from Ory Kratos, enhancing security and user experience.
- The ability to bypass the logout consent screen for specific clients, streamlining the logout process.
- Simplified migration with the new feature to import OAuth2 Client IDs, making the transition to Ory Hydra smoother.
- Support for the OIDC Verifiable Credentials specification, expanding the server's capabilities in identity verification.

Thank all contributors who have made this release available!

Introduces logout compatibility with Ory Kratos.

Test release

This release optimizes the performance of authorization code grant flows by minimizing the number of database queries. We acheive this by storing the flow in an AEAD-encoded cookie and AEAD-encoded request parameters for the authentication and consent screens.

BREAKING CHANGE:

* The client that is used as part of the authorization grant flow is stored in the AEAD-encoding. Therefore, running flows will not observe updates to the client after they were started.
* Because the login and consent challenge values now include the AEAD-encoded flow, their size increased to around 1kB for a flow without any metadata (and increases linearly with the amount of metadata). Please adjust your ingress / gateway accordingly.

This release optimizes the performance of authorization code grant flows by minimizing the number of database queries. We acheive this by storing the flow in an AEAD-encoded cookie and AEAD-encoded request parameters for the authentication and consent screens.

BREAKING CHANGE:

* The client that is used as part of the authorization grant flow is stored in the AEAD-encoding. Therefore, running flows will not observe updates to the client after they were started.
* Because the login and consent challenge values now include the AEAD-encoded flow, their size increased to around 1kB for a flow without any metadata (and increases linearly with the amount of metadata). Please adjust your ingress / gateway accordingly.

We are excited to announce the next Ory Hydra release! This release includes the following important changes:

- Fixed a memory leak in the OpenTelemetry implementation, improving overall memory usage and stability.
- Added a missing index for faster janitor cleanup, resulting in quicker and more efficient cleanup operations.
- Fixed a bug related to SameSite in dev mode, ensuring proper functionality and consistency in handling SameSite attributes during development.

We appreciate your continuous support and feedback. Please feel free to reach out to us with any further suggestions or issues.

Resolve a regression in looking up access and refresh tokens.

We are excited to share this year's Q1 release of Ory Hydra: v2.1.0!

Highlights:

* Support for Datadog tracing (#3431).
* Ability to skip consent for trusted clients (#3451).
* Setting access token type in the OAuth2 Client is now possible (#3446).
* Revoke login sessions by SessionID (#3450).
* Session lifespan extended on session refresh (#3464).
* Token request hooks added for all grant types (#3427).
* Reduced SQL tracing noise (#3481).

Don't want to run the upgrade yourself? Switch to [Ory Network](https://console.ory.sh/registration?flow=d1ae4761-3493-4dd9-b0ce-3200916b38aa)!

Bugfixes for migration and pagination regressions and a new endpoint.

This release resolves bugs and SDK publishing issues.

Resolves an issues with post-release steps and adds the introspect command to the Ory Hydra CLI.

This milestone release impacts most of Ory’s installed base. While we are thrilled to unveil Ory Hydra 2.0, we would strongly suggest reading this document carefully and to the end.

Open Source software is not easy. Besides the community version Ory Hydra 2.0, Ory now provides the Ory OAuth2 & OpenID service on the [Ory Network](https://www.ory.sh) making this release a major event for Ory and the entire Ory Community.

Ory Hydra 2.0 is available now. Install the Ory CLI for the best developer experience.

```shell
bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -b . ory
sudo mv ./ory /usr/local/bin/

brew install ory/tap/cli
```

create a new project (you may also use [Docker](https://www.ory.sh/docs/hydra/5min-tutorial))

```
ory create project --name "Ory Hydra 2.0 Example"
project_id="{set to the id from output}"
```

and follow the quick & easy steps below.

Create an OAuth 2.0 Client, and run the OAuth 2.0 Client Credentials flow:

```shell
ory create oauth2-client --project $project_id \
    --name "Client Credentials Demo" \
    --grant-type client_credentials
client_id="{set to client id from output}"
client_secret="{set to client secret from output}"

ory perform client-credentials --client-id=$client_id --client-secret=$client_secret --project $project_id
access_token="{set to access token from output}"

ory introspect token $access_token --project $project_id
```

Try out the OAuth 2.0 Authorize Code grant right away!

By accepting permissions `openid` and `offline_access` at the consent screen, Ory refreshes and OpenID Connect ID token,

```shell
ory create oauth2-client --project $project_id \
    --name "Authorize Code with OpenID Connect Demo" \
    --grant-type authorization_code \
    --response-type code \
    --redirect-uri ttp://127.0.0.1:4446/callback
code_client_id="{set to client id from output}"
code_client_secret="{set to client secret from output}"

ory perform authorization-code \
    --project $project_id \
    --client-id $code_client_id \
    --client-secret $code_client_secret
code_access_token="{set to access token from output}"

ory introspect token $code_access_token --project $project_id
```

What's changed in Ory Hydra 2.0?

[OAuth 2.0 Token Exchange (RFC8693)](https://datatracker.ietf.org/doc/html/rfc8693) is now fully supported, including the JSON Web Token profile!

Ory Identities is now compatible with the Ory OAuth2 Login and Consent Flow. This means, for example, that Ory Kratos can be the login provider for Ory Hydra with a bit of configuration.

The Ory Network enables has this integration as a default.

Ory Hydra 2.0 now natively supports key types such as ES256 for signing ID Tokens and OAuth 2.0 Access Tokens in JWT format.

Additionally, the key naming mechanism was updated to conform with industry best practices.

Ory Hydra 2.0 ships a complete refactoring of the internal database structure, reducing database storage at scale and optimizing query performance.

All primary keys are now UUIDs to avoid hotspots in distributed systems. Please note that as part of this change it is no longer possible to choose the OAuth 2.0 Client ID. Instead, Ory chooses the best-performing ID format for the petabyte scale.

Ory chose to denormalize tables that had a negative performance impact due to excessive JOIN statements.

Using BCrypt as the primary hashing algorithm for OAuth 2.0 Client Secrets creates excessive CPU consumption at scale. OAuth 2.0 Client Secrets are auto-generated in Ory Hydra 2.x, removing the need for excessive hashing costs.

The new PKBDF2 hasher can be fine-tuned to support hashing at scale without a significant threat model impact.

This section only applies in scenarios where Ory Hydra is working in a do-it-yourself fashion e.g. on Docker. An Ory Hydra 2.0 compatible service is already available on the [Ory Network](https://www.ory.sh).

The database schema changed significantly from the previous structure. Please be aware that there might be a period where the database tables will be locked for writes while the upgrade runs.

**A full backup of the database before upgrading is essential!** We recommend trying out the upgrade on a copy of a production database first.

To run the SQL migrations using:

```
hydra migrate sql $DSN
```

Ory Hydra 1.x is a crucial service at Ory. Version 2.0 streamlines the APIs and SDKs to follow Ory API’s semantics and specification.

To better support TB-scale environments, the OAuth2 Client HTTP API's query
parameters for pagination have changed from `limit` and `offset` to `page_token`
and `page_size`. The `page_token` is an opaque string contained in the HTTP
`Link` Header, which expresses the next, previous, first, and last page.

Administrative endpoints now have an `/admin` prefix (e.g. `POST /admin/keys` instead of `POST /keys`). Existing administrative endpoints will redirect to this new prefixed path for backward compatibility.

HTTP endpoint `/oauth2/flush`, used to flush inactive access tokens was deprecated and has been removed. Please use `hydra janitor` instead.

To conform with the Ory V1 SDK, several SDK methods and payloads were renamed. Please check the [CHANGELOG](https://github.com/ory/hydra/blob/master/CHANGELOG.md) for a complete list of changes.

The `iss` (issuer) value no longer appends a trailing slash but instead uses the raw value set in the config.

Setting

```yaml
urls:
  self:
    issuer: https://auth.example.com
```

has changed

```patch
- "iss": "https://auth.example.com/"
+ "iss": "https://auth.example.com"
```

To set a trailing slash make sure to set it in the config value:

```yaml
urls:
  self:
    issuer: https://auth.example.com/
```

Flags `--dangerous-allow-insecure-redirect-url` and `--dangerous-force-http` have been removed. Use the `--dev` flag instead to denote a development environment with reduced security restrictions.

We now recommend using the [Ory CLI](https://www.ory.sh/docs/guides/cli/installation) to manage OAuth2 resources. As part of this restructuring, some of the commands were renamed. Here are some examples:

```patch
- hydra client create
+ ory create oauth2-client

- hydra clients list
+ ory list oauth2-clients
```

Additionally, array arguments now use the singular form:

```patch
hydra create client \
- --redirect-uris foo --redirect-uris bar \
+ --redirect-uri foo --redirect-uri bar \
- --grant-types foo --grant-types bar \
+ --grant-type foo --grant-type bar \
- --response-types foo --response-types bar \
+ --response-type foo --response-type bar \
- --allowed-cors-origins foo --allowed-cors-origins bar \
+ --allowed-cors-origin foo --allowed-cors-origin bar \
- --post-logout-callbacks foo --post-logout-callbacks bar \
+ --post-logout-callback foo --post-logout-callback bar
```

To manage resources in a do-it-yourself installation, continue using the `hydra` CLI.

Please check the [CHANGELOG](https://github.com/ory/hydra/blob/master/CHANGELOG.md) for a complete list of changes.

Ory Hydra 2.0 ships with support for OpenTelemetry. The previous telemetry solution using OpenTracing format is deprecated with this release.