Registering OAuth2 Clients on Ory Hydra With Dynamic Client Registration

Problem & Takeaway

In many teams, adding a new OAuth2 client to Hydra requires manual database edits or a custom UI. This slows onboarding and invites errors. Dynamic client registration (DCR) removes that friction: a client can POST to /dcr and receive a client_id (and client_secret if needed) without any admin intervention.

The key takeaway: to use DCR you must supply redirect_uris and token_endpoint_auth_method in the JSON payload, and the Hydra instance must allow DCR (it can be disabled via configuration). Once registered, the client can immediately participate in the OAuth2/OIDC flow.

How DCR Works in Hydra

Hydra’s /dcr endpoint implements the RFC 7591 client‑registration framework. When a request is accepted, Hydra writes a record to the configured persistence store (PostgreSQL, MySQL, MongoDB, or a custom store) and responds with the client credentials. The store also holds the client’s metadata for later validation during token issuance.

Important validation points:

• redirect_uris – Must be a non‑empty array of absolute URLs. Hydra will reject the registration if any URI fails the pattern check. Wildcards (e.g., https://*.example.com/callback) are supported from v1.1+, but you must enable them explicitly in hydra.yaml under allow_insecure_redirect_uris or allow_wildcard_redirect_uris.
• token_endpoint_auth_method – The method the client will use to authenticate to Hydra’s token endpoint. Common values: client_secret_basic, client_secret_post, none. If you choose none, Hydra will not store a secret.
• All other optional fields (e.g., client_name, grant_types, response_types) can be omitted; Hydra will fill defaults.

Hydra requires TLS for production. Exposing /dcr over HTTP can leak the client secret in transit.

Concrete Example

Below is a minimal, verifiable example of registering a client that will use client_secret_basic for token authentication.

curl -X POST https://hydra.example.com/dcr \
     -H "Content-Type: application/json" \
     -d '{
  "redirect_uris": ["https://app.example.com/callback"],
  "token_endpoint_auth_method": "client_secret_basic"
}'

Run this command from a machine that can reach the Hydra instance over HTTPS. You need no special permissions beyond network access; the endpoint is public by design. After a successful request you should receive a 200 response similar to:

{
  "client_id": "abc123",
  "client_secret": "s3cr3t",
  "registration_access_token": "jwt…",
  "registration_client_uri": "https://hydra.example.com/clients/abc123"
}

Verify the registration by inspecting the persistence layer. For PostgreSQL, a query like:

SELECT client_id, redirect_uris, token_endpoint_auth_method
FROM hydra_client
WHERE client_id = 'abc123';

should return the values you supplied. If you are using the Ory CLI, you can also list clients with:

hydra clients list

Limits & Common Mistakes

1. Missing or malformed redirect_uris
   • Hydra will reject the request with a 400 error if the array is empty or contains relative URLs.
   • Always use absolute URLs. Even if your application runs on localhost during development, the URI must be fully qualified (e.g., https://localhost:3000/callback). Otherwise, the token endpoint will refuse the client.
2. Wrong token_endpoint_auth_method
   • If you specify client_secret_basic but later change the client to use none, the client will no longer be able to authenticate. Changing the auth method requires re‑registration or manual update of the record.
3. Wildcard redirect URIs not enabled
   • By default, Hydra disallows wildcards. If you need them, set allow_wildcard_redirect_uris: true in hydra.yaml and restart.
   • Even with wildcards, the pattern must match the exact scheme and domain; Hydra does not support arbitrary regex patterns.
4. Exposing /dcr over HTTP
   • Client secrets could be sniffed on the network. Always enforce HTTPS for the Hydra service in production.
5. Using the wrong endpoint URL
   • In a multi‑tenant setup, the DCR endpoint may be namespaced (e.g., /admin/dcr). Verify the correct path in your Hydra configuration.

What If I Need to Revoke a Client?

Unlike static registration, DCR records can be deleted via Hydra’s admin API:

curl -X DELETE https://hydra.example.com/clients/abc123 \
     -H "Authorization: Bearer <admin‑jwt>"

Ensure you have an admin JWT; this operation changes state, so treat it with caution.

Conclusion

Dynamic client registration in Ory Hydra streamlines onboarding and reduces manual errors. By providing the required fields and respecting the validation rules, you can add new OAuth2/OIDC clients on the fly. Keep TLS enabled, validate redirect URIs, and remember that changes to the authentication method require re‑registration.