<commit_before># Upgrading

The intent of this document is to make migration of breaking changes as easy as possible. Please note that not all
breaking changes might be included here. Please check the [CHANGELOG.md](./CHANGELOG.md) for a full list of changes
before finalizing the upgrade process.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [1.0.0-alpha.1](#100-beta1)
  - [OpenID Connect Certified](#openid-connect-certified)
  - [Breaking Changes](#breaking-changes)
    - [Introspection API](#introspection-api)
      - [Introspection is now capable of introspecting refresh tokens](#introspection-is-now-capable-of-introspecting-refresh-tokens)
    - [Access Control & Warden API](#access-control-&-warden-api)
      - [Running the backwards compatible set up](#running-the-backwards-compatible-set-up)
        - [Warden API](#warden-api)
        - [Warden Groups](#warden-groups)
    - [jwk: Forces JWK to have a unique ID](#jwk-forces-jwk-to-have-a-unique-id)
    - [Consent Flow](#consent-flow)
    - [Changes to the CLI](#changes-to-the-cli)
      - [`hydra host`](#hydra-host)
      - [`hydra connect`](#hydra-connect)
      - [`hydra token user`](#hydra-token-user)
      - [`hydra token client`](#hydra-token-client)
      - [`hydra token validate`](#hydra-token-validate)
      - [`hydra clients create`](#hydra-clients-create)
      - [`hydra migrate ladon`](#hydra-migrate-ladon)
      - [`hydra policies`](#hydra-policies)
      - [`hydra groups`](#hydra-groups)
    - [SDK](#sdk)
  - [Improvements](#improvements)
    - [Health Check endpoint has moved](#health-check-endpoint-has-moved)
    - [Unknown request body payloads result in error](#unknown-request-body-payloads-result-in-error)
    - [UTC everywhere](#utc-everywhere)
    - [Pagination everywhere](#pagination-everywhere)
    - [Flushing old access tokens](#flushing-old-access-tokens)
    - [Prometheus endpoint](#prometheus-endpoint)
- [0.11.12](#01112)
- [0.11.3](#0113)
- [0.11.0](#0110)
- [0.10.0](#0100)
  - [Breaking Changes](#breaking-changes-1)
    - [Introspection now requires authorization](#introspection-now-requires-authorization)
    - [New consent flow](#new-consent-flow)
    - [Audience](#audience)
    - [Response payload changes to `/warden/token/allowed`](#response-payload-changes-to-wardentokenallowed)
    - [Go SDK](#go-sdk)
    - [Health endpoints](#health-endpoints)
    - [Group endpoints](#group-endpoints)
    - [Replacing hierarchical scope strategy with wildcard scope strategy](#replacing-hierarchical-scope-strategy-with-wildcard-scope-strategy)
    - [AES-GCM nonce storage](#aes-gcm-nonce-storage)
    - [Minor Breaking Changes](#minor-breaking-changes)
      - [Token signature algorithm changed from HMAC-SHA256 to HMAC-SHA512](#token-signature-algorithm-changed-from-hmac-sha256-to-hmac-sha512)
      - [HS256 JWK Generator now uses all 256 bit](#hs256-jwk-generator-now-uses-all-256-bit)
      - [ES512 Key generator](#es512-key-generator)
      - [Build tags deprecated](#build-tags-deprecated)
  - [Important Additions](#important-additions)
    - [Prefixing Resources Names](#prefixing-resources-names)
    - [Refreshing OpenID Connect ID Token using `refresh_token` grant type](#refreshing-openid-connect-id-token-using-refresh_token-grant-type)
  - [Important Changes](#important-changes)
    - [Telemetry](#telemetry)
    - [URL Encoding Root Client Credentials](#url-encoding-root-client-credentials)
- [0.9.0](#090)
- [0.8.0](#080)
  - [Breaking changes](#breaking-changes)
    - [Ladon updated to 0.6.0](#ladon-updated-to-060)
    - [Redis and RethinkDB deprecated](#redis-and-rethinkdb-deprecated)
    - [Moved to ory namespace](#moved-to-ory-namespace)
    - [SDK](#sdk-1)
    - [JWK](#jwk)
    - [Migrations are no longer automatically applied](#migrations-are-no-longer-automatically-applied)
  - [Changes](#changes)
    - [Log format: json](#log-format-json)
    - [SQL Connection Control](#sql-connection-control)
    - [REST API Docs are now generated from source code](#rest-api-docs-are-now-generated-from-source-code)
    - [Documentation on scopes](#documentation-on-scopes)
    - [New response writer library](#new-response-writer-library)
    - [Graceful http handling](#graceful-http-handling)
    - [Best practice HTTP server config](#best-practice-http-server-config)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## 1.0.0-beta.1

This section summarizes important changes introduced in 1.0.0. **Follow it chronologically to ensure a proper migration.**

We are very well aware that the changelist is huge and we try to prepare you as good as we can to migrate to this version.
We also understand that breaking changes are frustrating and it takes time to adopt to them. We sincerely hope that
the benefits from this version (improved consent flow, easier set up, clear boundaries & responsibilities)
outweigh the hassle of upgrading to the new version.

If you have difficulties upgrading and would like a helping hand, reach out to us at [mailto:<EMAIL>](<EMAIL>) and
we will help you with the upgrade process. Our services are billed by the hour and are priced fairly.

### OpenID Connect Certified

ORY Hydra is now OpenID Connect Certified! Certification spans the OAuth 2.0 Authorize Code Flow, Implicit Flow, and Hybrid Flow
as well as dynamic discovery.

The certification is one reason for the breaking changes in the consent app.

### Breaking Changes

#### Introspection API

One change has been made to the introspection API which is that key `aud` is no longer a string, but an array of strings.
As this claim has not been supported actively up until now, this will most likely not affect you at all.

##### Introspection is now capable of introspecting refresh tokens

Previously, we disabled the introspection of refresh tokens. This has now changed to comply with the OAuth 2.0 specification.
To distinguish tokens, use the `token_type` in the introspection response. It can either be `access_token` or `refresh_token`.

#### Access Control & Warden API

Internal access control, access control policies, and the Warden API have moved to a separate project called [ORY Keto](https://github.com/ory/keto).
You will be able to run a combination of ORY Hydra, [ORY Oathkeeper](https://github.com/ory/oathkeeper), and [ORY Keto](https://github.com/ory/keto) which will be backwards compatible with
ORY Hydra before the 1.0.0 release. This section explains how to upgrade and links to an example explaining the set up
of the three services.

**This means that ORY Hydra has no longer any type of internal access control. Endpoints such as `POST /clients` no longer<commit_msg>docs: Adds upgrade instructions from 0.9.x to 1.0.0<commit_after># Upgrading

The intent of this document is to make migration of breaking changes as easy as possible. Please note that not all
breaking changes might be included here. Please check the [CHANGELOG.md](./CHANGELOG.md) for a full list of changes
before finalizing the upgrade process.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [1.0.0-alpha.1](#100-beta1)
  - [OpenID Connect Certified](#openid-connect-certified)
  - [Breaking Changes](#breaking-changes)
    - [Introspection API](#introspection-api)
      - [Introspection is now capable of introspecting refresh tokens](#introspection-is-now-capable-of-introspecting-refresh-tokens)
    - [Access Control & Warden API](#access-control-&-warden-api)
      - [Running the backwards compatible set up](#running-the-backwards-compatible-set-up)
        - [Warden API](#warden-api)
        - [Warden Groups](#warden-groups)
    - [jwk: Forces JWK to have a unique ID](#jwk-forces-jwk-to-have-a-unique-id)
    - [Consent Flow](#consent-flow)
    - [Changes to the CLI](#changes-to-the-cli)
      - [`hydra host`](#hydra-host)
      - [`hydra connect`](#hydra-connect)
      - [`hydra token user`](#hydra-token-user)
      - [`hydra token client`](#hydra-token-client)
      - [`hydra token validate`](#hydra-token-validate)
      - [`hydra clients create`](#hydra-clients-create)
      - [`hydra migrate ladon`](#hydra-migrate-ladon)
      - [`hydra policies`](#hydra-policies)
      - [`hydra groups`](#hydra-groups)
    - [SDK](#sdk)
  - [Improvements](#improvements)
    - [Health Check endpoint has moved](#health-check-endpoint-has-moved)
    - [Unknown request body payloads result in error](#unknown-request-body-payloads-result-in-error)
    - [UTC everywhere](#utc-everywhere)
    - [Pagination everywhere](#pagination-everywhere)
    - [Flushing old access tokens](#flushing-old-access-tokens)
    - [Prometheus endpoint](#prometheus-endpoint)
- [0.11.12](#01112)
- [0.11.3](#0113)
- [0.11.0](#0110)
- [0.10.0](#0100)
  - [Breaking Changes](#breaking-changes-1)
    - [Introspection now requires authorization](#introspection-now-requires-authorization)
    - [New consent flow](#new-consent-flow)
    - [Audience](#audience)
    - [Response payload changes to `/warden/token/allowed`](#response-payload-changes-to-wardentokenallowed)
    - [Go SDK](#go-sdk)
    - [Health endpoints](#health-endpoints)
    - [Group endpoints](#group-endpoints)
    - [Replacing hierarchical scope strategy with wildcard scope strategy](#replacing-hierarchical-scope-strategy-with-wildcard-scope-strategy)
    - [AES-GCM nonce storage](#aes-gcm-nonce-storage)
    - [Minor Breaking Changes](#minor-breaking-changes)
      - [Token signature algorithm changed from HMAC-SHA256 to HMAC-SHA512](#token-signature-algorithm-changed-from-hmac-sha256-to-hmac-sha512)
      - [HS256 JWK Generator now uses all 256 bit](#hs256-jwk-generator-now-uses-all-256-bit)
      - [ES512 Key generator](#es512-key-generator)
      - [Build tags deprecated](#build-tags-deprecated)
  - [Important Additions](#important-additions)
    - [Prefixing Resources Names](#prefixing-resources-names)
    - [Refreshing OpenID Connect ID Token using `refresh_token` grant type](#refreshing-openid-connect-id-token-using-refresh_token-grant-type)
  - [Important Changes](#important-changes)
    - [Telemetry](#telemetry)
    - [URL Encoding Root Client Credentials](#url-encoding-root-client-credentials)
- [0.9.0](#090)
- [0.8.0](#080)
  - [Breaking changes](#breaking-changes)
    - [Ladon updated to 0.6.0](#ladon-updated-to-060)
    - [Redis and RethinkDB deprecated](#redis-and-rethinkdb-deprecated)
    - [Moved to ory namespace](#moved-to-ory-namespace)
    - [SDK](#sdk-1)
    - [JWK](#jwk)
    - [Migrations are no longer automatically applied](#migrations-are-no-longer-automatically-applied)
  - [Changes](#changes)
    - [Log format: json](#log-format-json)
    - [SQL Connection Control](#sql-connection-control)
    - [REST API Docs are now generated from source code](#rest-api-docs-are-now-generated-from-source-code)
    - [Documentation on scopes](#documentation-on-scopes)
    - [New response writer library](#new-response-writer-library)
    - [Graceful http handling](#graceful-http-handling)
    - [Best practice HTTP server config](#best-practice-http-server-config)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## 1.0.0-beta.1

This section summarizes important changes introduced in 1.0.0. **Follow it chronologically to ensure a proper migration.**

We are very well aware that the changelist is huge and we try to prepare you as good as we can to migrate to this version.
We also understand that breaking changes are frustrating and it takes time to adopt to them. We sincerely hope that
the benefits from this version (improved consent flow, easier set up, clear boundaries & responsibilities)
outweigh the hassle of upgrading to the new version.

If you have difficulties upgrading and would like a helping hand, reach out to us at [mailto:<EMAIL>](<EMAIL>) and
we will help you with the upgrade process. Our services are billed by the hour and are priced fairly.

### Upgrading from versions v0.9.x

This is a (potentially incomplete) summary of what needs to be done to upgrade from versions of the 0.9.x branch, which are still common. First of all, these changes are important:

1. [Replacing hierarchical scope strategy with wildcard scope strategy](#replacing-hierarchical-scope-strategy-with-wildcard-scope-strategy)
2. [AES-GCM nonce storage](#aes-gcm-nonce-storage)

The second change is particularly important as you need to perform the strategies presented there before upgrading to 1.0.0.

When upgrading, try to follow these steps. As always, try this with a staging environment first and create back ups. Never run this directly in production unless you are 100% sure everything works:

1. Get the latest ORY Hydra binary or docker image from the 1.0.0 branch.
2. Run `$ export DATABASE_URL=<your-database-url>`.
3. If you want to keep using Access Control Policies and the Warden API, you must install ORY Keto using the binaries or the docker image:
   1. `$ keto migrate hydra $DATABASE_URL`.
   2. `$ keto migrate sql $DATABASE_URL`.
   3. Read how to update the JWK storage: [AES-GCM nonce storage](#aes-gcm-nonce-storage). If you only use auto-generated keys and have never used POST or PUT on the `/keys` API, you can probably just execute a `DELETE FROM hydra_jwk` to just remove all the auto-generated keys. When starting the ORY Hydra 1.0.0 CLI the required keys will be re-generated automatically.
   4. `$ hydra migrate $DATABASE_URL`.
4. If you do use Access Control Policies nor the Warden API, you can skip ORY Keto:
   1. Read how to update the JWK storage: [AES-GCM nonce storage](#aes-gcm-nonce-storage) and **read point 3.3 of this list**.
   2. `$ hydra migrate $DATABASE_URL`.
5. `$ export SCOPE_STRATEGY=DEPRECATED_HIERARCHICAL_SCOPE_STRATEGY` - this will set the [scope strategy](#replacing-hierarchical-scope-strategy-with-wildcard-scope-strategy) to the old scope strategy used in version 0.9.x. If you set this, you don't need to update the scopes your OAuth 2.0 Clients are allowed to request.
6. `$ hydra help serve`.
7. `$ hydra serve --your-flags`.
   
It's still a good idea to read through the changes in 0.10.0, for example: [Response payload changes to `/warden/token/allowed`](#response-payload-changes-to-wardentokenallowed). You can, however, skip the [New consent flow](#new-consent-flow) subsection in the 0.10.0 section. All required changes are explained in detail in this release's consent flow description.

### OpenID Connect Certified

ORY Hydra is now OpenID Connect Certified! Certification spans the OAuth 2.0 Authorize Code Flow, Implicit Flow, and Hybrid Flow
as well as dynamic discovery.

The certification is one reason for the breaking changes in the consent app.

### Breaking Changes

#### Introspection API

One change has been made to the introspection API which is that key `aud` is no longer a string, but an array of strings.
As this claim has not been supported actively up until now, this will most likely not affect you at all.

##### Introspection is now capable of introspecting refresh tokens

Previously, we disabled the introspection of refresh tokens. This has now changed to comply with the OAuth 2.0 specification.
To distinguish tokens, use the `token_type` in the introspection response. It can either be `access_token` or `refresh_token`.

#### Access Control & Warden API

Internal access control, access control policies, and the Warden API have moved to a separate project called [ORY Keto](https://github.com/ory/keto).
You will be able to run a combination of ORY Hydra, [ORY Oathkeeper](https://github.com/ory/oathkeeper), and [ORY Keto](https://github.com/ory/keto) which will be backwards compatible with
ORY Hydra before the 1.0.0 release. This section explains how to upgrade and links to an example explaining the set up
of the three services.

**This means that ORY Hydra has no longer any type of internal access control. Endpoints such as `POST /clients` no longer
{'fraction_non_alphanumeric': 0.11285110613969675, 'fraction_numerical': 0.016281382053194134, 'mean_word_length': 4.004042288557214, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3563119', 'n_tokens_mistral': 5184, 'n_tokens_neox': 4697, 'n_words': 1657}