Client Credentials flow with Ory Hydra

Ory Hydra is an open source OpenID Connect Provider. It implements OAuth 2.0 Authorization Framework and the OpenID Connect Core 1.0 framework. It can issue OAuth 2.0 Access, Refresh, and ID tokens. This can be useful to test the token flow during the development on a local machine. In this post, we’ll setup Hydra using Docker, create a client and test a client_credentials flow through Hydra CLI and curl.

Setup

The code written for this post uses:

Docker Engine 20.10.17
Ory Hydra 1.11.9
Postgres 9.6

Configure Ory Hydra

Create a Docker Compose file with the following details.

yml
quickstart.yml

 1version: "3.7"
 2
 3services:
 4
 5  hydra:
 6    image: oryd/hydra:v1.11.9
 7    ports:
 8      - "4444:4444" # Public port
 9      - "4445:4445" # Admin port
10      - "5555:5555" # Port for hydra token user
11    command: serve all --dangerous-force-http
12    environment:
13      - DSN=postgres://hydra:secret@postgresd:5432/hydra?sslmode=disable&max_conns=20&max_idle_conns=4
14    restart: unless-stopped
15    depends_on:
16      - hydra-migrate
17    networks:
18      - hydranet
19
20  hydra-migrate:
21    image: oryd/hydra:v1.11.9
22    environment:
23      - DSN=postgres://hydra:secret@postgresd:5432/hydra?sslmode=disable&max_conns=20&max_idle_conns=4
24    command: migrate sql -e --yes
25    restart: on-failure
26    networks:
27      - hydranet
28
29  postgresd:
30    image: postgres:9.6
31    ports:
32      - "5432:5432"
33    environment:
34      - POSTGRES_USER=hydra
35      - POSTGRES_PASSWORD=secret
36      - POSTGRES_DB=hydra
37    networks:
38      - hydranet
39
40networks:
41  hydranet:

This is a modified version of the Compose file available on Hydra repository. There are 3 services configured here.

postgresd is the database which stores the details required by Hydra
hydra-migrate initializes the necessary tables and database objects required by Hydra to store the necessary details
hydra is the service that creates the APIs for token management, etc

Launch the containers with the following command.

docker-compose -f quickstart.yml up --build

This command builds the containers and launch them. You can open a new terminal and verify the health of all the containers. The services postgresd and hydra should be up and running.

1docker ps
2CONTAINER ID   IMAGE                COMMAND                  CREATED          STATUS          PORTS                                                      NAMES
3223ca5b3d9fa   oryd/hydra:v1.11.9   "hydra serve all --d…"   28 seconds ago   Up 25 seconds   0.0.0.0:4444-4445->4444-4445/tcp, 0.0.0.0:5555->5555/tcp   hydra-client-credentials-hydra-1
426af918199dd   postgres:9.6         "docker-entrypoint.s…"   28 seconds ago   Up 26 seconds   0.0.0.0:5432->5432/tcp                                     hydra-client-credentials-postgresd-1

Client Credentials flow with Hydra CLI

You can test Hydra using Hydra CLI available in the hydra container.

Let’s start by creating a client. Since we’re testing the Client Credentials flow, specify the client_credentials as a grant type.

sh
Creating a client

1docker-compose -f quickstart.yml exec hydra hydra clients create --endpoint http://localhost:4445/ --id my-client --secret my-secret --grant-types client_credentials --scope api
2You should not provide secrets using command line flags, the secret might leak to bash history and similar systems
3OAuth 2.0 Client ID: my-client

With this client, you can now generate a token.

sh
Generating a token

1docker-compose -f quickstart.yml exec hydra hydra token client --endpoint http://localhost:4444/ --client-id my-client --client-secret my-secret
2vRm9SR63-7vuhdMhZs72PT9Uhj4HQXCL3QrKVRja_yI.jpXIW0ichJFr4ANUSMVvXwL7CFEuNmCQNdUU6FgkGHc

When you introspect this token, you’ll receive the response whether the token is active.

sh
Introspecting a token

 1docker-compose -f quickstart.yml exec hydra hydra token introspect --endpoint http://localhost:4445/ vRm9SR63-7vuhdMhZs72PT9Uhj4HQXCL3QrKVRja_yI.jpXIW0ichJFr4ANUSMVvXwL7CFEuNmCQNdUU6FgkGHc
 2{
 3	"active": true,
 4	"aud": [],
 5	"client_id": "my-client",
 6	"exp": 1661071059,
 7	"iat": 1661067458,
 8	"iss": "http://localhost:4444/",
 9	"nbf": 1661067458,
10	"sub": "my-client",
11	"token_type": "Bearer",
12	"token_use": "access_token"
13}

If the token isn’t active, the active flag returns as false.

1docker-compose -f quickstart.yml exec hydra hydra token introspect --endpoint http://localhost:4445/ vRm9SR63-7vuhdMhZs72PT9Uhj4HQXCL3QrKVRja_yI.jpXIW0ichJFr4ANUSMVvXwL7CFEuNmCQNdUU6FgkGHd
2{
3	"active": false,
4	"aud": null
5}

Client Credentials flow with `curl`

Although Hydra CLI is convenient, it’s not practical when the applications need to communicate through API calls using HTTP. Hydra exposes REST endpoints for this purpose documented in its API reference. Let’s explore how this works with curl.

You can create a client by calling the /clients endpoint which is a part of the admin API. Once again, specify the client_credentials as a grant type.

sh
Creating a client

 1curl -X POST 'http://localhost:4445/clients' -H 'Content-Type: application/json' --data-raw '{ "client_id": "my-client-2", "client_name": "MyClientApp", "client_secret": "my-secret-2", "grant_types": ["client_credentials"], "scope": "api" }'
 2{
 3	"client_id": "my-client-2",
 4	"client_name": "MyClientApp",
 5	"client_secret": "my-secret-2",
 6	"redirect_uris": null,
 7	"grant_types": [
 8		"client_credentials"
 9	],
10	"response_types": null,
11	"scope": "api",
12	"audience": [],
13	"owner": "",
14	"policy_uri": "",
15	"allowed_cors_origins": [],
16	"tos_uri": "",
17	"client_uri": "",
18	"logo_uri": "",
19	"contacts": null,
20	"client_secret_expires_at": 0,
21	"subject_type": "public",
22	"jwks": {},
23	"token_endpoint_auth_method": "client_secret_basic",
24	"userinfo_signed_response_alg": "none",
25	"created_at": "2022-08-21T09:46:40Z",
26	"updated_at": "2022-08-21T09:46:39.868107Z",
27	"metadata": {},
28	"registration_access_token": "MnfHqsih-NlTYiL6DHZ-QxUcpLoQzw7ZHnbAp03qSlo.EqPZT8LnPp3AOOaHRycCi1_SomWXeGxnUSrSehHI0XM",
29	"registration_client_uri": "http://localhost:4444/oauth2/register/my-client-2",
30	"authorization_code_grant_access_token_lifespan": null,
31	"authorization_code_grant_id_token_lifespan": null,
32	"authorization_code_grant_refresh_token_lifespan": null,
33	"client_credentials_grant_access_token_lifespan": null,
34	"implicit_grant_access_token_lifespan": null,
35	"implicit_grant_id_token_lifespan": null,
36	"jwt_bearer_grant_access_token_lifespan": null,
37	"password_grant_access_token_lifespan": null,
38	"password_grant_refresh_token_lifespan": null,
39	"refresh_token_grant_id_token_lifespan": null,
40	"refresh_token_grant_access_token_lifespan": null,
41	"refresh_token_grant_refresh_token_lifespan": null
42}

After creating a client, you can generate a token using the client id and secret of the client as follows.

sh
Generating a token

1curl -u 'my-client-2:my-secret-2' -X POST 'http://localhost:4444/oauth2/token' -H 'Content-Type: application/x-www-form-urlencoded' --data-raw 'grant_type=client_credentials&scope=api'
2{
3	"access_token": "3mqL5bYDrEW-adM6QCrchQD9pLZvM2Gv2WHWCnrk_4w.1QhAtnI-f_QE9zdUcXKErzRFPaFjqF_dMWJHcwLwHE8",
4	"expires_in": 3599,
5	"scope": "api",
6	"token_type": "bearer"
7}

You can now introspect this token with the /introspect endpoint which is a part of the admin API. The response specifies whether the token is active.

sh
Introspecting a token

 1curl -X POST 'http://localhost:4445/oauth2/introspect' -H 'Content-Type: application/x-www-form-urlencoded' --data-raw 'token=3mqL5bYDrEW-adM6QCrchQD9pLZvM2Gv2WHWCnrk_4w.1QhAtnI-f_QE9zdUcXKErzRFPaFjqF_dMWJHcwLwHE8'
 2{
 3	"active": true,
 4	"scope": "api",
 5	"client_id": "my-client-2",
 6	"sub": "my-client-2",
 7	"exp": 1661078849,
 8	"iat": 1661075249,
 9	"nbf": 1661075249,
10	"aud": [],
11	"iss": "http://localhost:4444/",
12	"token_type": "Bearer",
13	"token_use": "access_token"
14}

Again, if the token isn’t active, the active flag returns as false.

1curl -X POST 'http://localhost:4445/oauth2/introspect' -H 'Content-Type: application/x-www-form-urlencoded' --data-raw 'token=3mqL5bYDrEW-adM6QCrchQD9pLZvM2Gv2WHWCnrk_4w.1QhAtnI-f_QE9zdUcXKErzRFPaFjqF_dMWJHcwLwHE9'
2{
3	"active": false
4}

Notes

Ory Hydra can also work with other databases besides Postgres. Check out the quickstart Compose files available on the GitHub repository for examples using CockroachDB, MySQL, SQLite, etc.
Other OAuth flows like implicit, authorization_code, refresh_token, etc. are also supported. The 5-min tutorial on the official site showcases the authorization_code based flow.
You can also pass a hydra.yml file with the configuration to customize the behavior of Hydra. In this post, the default configuration is used.

Related

CTEs are fantastic

Introduction to Problem Details

Client Credentials flow with Ory Hydra

Configure Ory Hydra

Client Credentials flow with Hydra CLI

Client Credentials flow with curl

Notes

Client Credentials flow with `curl`