Ory Hydra OAuth2 Server is out in v2.0!

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 making this release a major event for Ory and the entire Ory Community.

Trial run and testing

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

# This example works best in Bash
bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -b . ory
sudo mv ./ory /usr/local/bin/

# Or with Homebrew installed
brew install ory/tap/cli

create a new project (you may also use Docker)

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

and follow the quick & easy steps below.

OAuth 2.0 Client Credentials / Machine-to-Machine

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

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

OAuth 2.0 Authorize Code + OpenID Connect

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,

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

New Features

What's changed in Ory Hydra 2.0?

OAuth 2.0 Token Exchange

OAuth 2.0 Token Exchange (RFC8693) is now fully supported, including the JSON Web Token profile!

Ory Identity Integration

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.

Cryptographic Keys

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.

Performance

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

Primary Keys

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.

Denormalization

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

PKBDF2

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.

Upgrade Guide

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.

Database

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

APIs and SDK

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.

Pagination

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.

Admin API

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.

Flush Endpoint

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

SDK

To conform with the Ory V1 SDK, several SDK methods and payloads were renamed. Please check the CHANGELOG for a complete list of changes.

Issuer URL

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

Setting

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

has changed

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

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

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

Development Mode

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.

CLI

We now recommend using the Ory CLI to manage OAuth2 resources. As part of this restructuring, some of the commands were renamed. Here are some examples:

- hydra client create
+ ory create oauth2-client

- hydra clients list
+ ory list oauth2-clients

Additionally, array arguments now use the singular form:

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 for a complete list of changes.

OTEL

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

Ory Hydra 2.0 is out!