Python Operator for Ory Hydra - a scalable, security first OAuth 2.0 and OpenID Connect server. For more details and documentation, visit https://www.ory.sh/docs/hydra/.
juju deploy postgresql-k8s --channel 14/stable --trust
juju deploy self-signed-certificates --channel latest/stable --trust
juju deploy identity-platform-login-ui-operator --channel latest/edge --trust
juju deploy traefik-k8s --channel latest/stable --trust
juju deploy hydra --trust
juju integrate postgresql-k8s hydra
juju integrate identity-platform-login-ui-operator hydra
juju integrate traefik-k8s:certificates self-signed-certificates:certificates
juju integrate traefik-k8s hydra:public-ingressYou can follow the deployment status with watch -c juju status --color.
This charm requires an integration with postgresql-k8s-operator.
The Hydra Operator offers integration with the traefik-k8s-operator for ingress. Hydra has two APIs which can be exposed through ingress, the public API and the admin API.
If you have traefik deployed and configured in your hydra model, to provide ingress to the admin API run:
juju integrate traefik-admin hydra:admin-ingressTo provide ingress to the public API run:
juju integrate traefik-public hydra:public-ingressNote that the public ingress needs to be secured with HTTPS if the charm
config dev is not true.
This charm offers integration with kratos-operator. In order to integrate hydra with kratos, it needs to be able to access hydra's admin API endpoint. To enable that, integrate the two charms:
juju integrate kratos hydraThe following instructions assume that you have deployed traefik-admin
and traefik-public charms and integrated them with hydra. Note that the UI
charm should run behind a proxy.
This charm offers integration with identity-platform-login-ui-operator. In order to integrate them, run:
juju integrate hydra:ui-endpoint-info identity-platform-login-ui-operator:ui-endpoint-info
juju integrate identity-platform-login-ui-operator:hydra-endpoint-info hydra:hydra-endpoint-infoWhen migrating an Ory Hydra instance—for example, to a new server or environment—you need to ensure the new instance can decrypt existing user sessions and data. Hydra relies on two crucial secrets for this:
- System Secret: Used to encrypt sensitive data stored in the database, such as session payloads and JSON Web Key Sets (JWKS).
- Cookie Secret: Used to encrypt and sign Hydra's cookies.
If you restore Hydra from a database backup without using the original secrets, the new instance will generate its own, rendering the backed-up data unusable. The Charmed Hydra Operator provides several helper actions and configuration options to manage these secrets and enable seamless server migration.
The operator includes two Juju actions for managing secrets on a running Hydra instance.
This action retrieves the current secret keys used by Hydra. It's essential for backing up secrets before a migration.
# Get the system secret keys
juju run hydra/0 get-secret-keys type=system
# Get the cookie secret keys
juju run hydra/0 get-secret-keys type=cookieThis action adds a new secret key to Hydra's configuration. This is useful for key rotation or for adding a key from a backup to an existing deployment.
juju run hydra/0 add-secret-key type=cookie key=YOUR_NEW_COOKIE_SECRETNOTE: key length MUST be >16 characters
When deploying a new Hydra instance, you can use the following Juju configuration options to pre-seed the secrets, preventing the charm from generating new ones. These configurations only work on the initial deployment.
initial_system_secret_id: The ID of a Juju secret containing the system keys.initial_cookie_secret_id: The ID of a Juju secret containing the cookie keys.
These config have no effect after the charm has been deployed and secrets have been generated.
Let's walk through a common server migration scenario. Assume you have an existing Hydra deployment (old-model) integrated with a PostgreSQL database, and you want to migrate it to a new Juju model (new-model).
First we need to get the old Hydra secret keys:
$ juju run -m old-model hydra/0 get-secret-keys type=system -q
system: '["old-system-key-1", "old-system-key-2"]'
$ juju run -m old-model hydra/0 get-secret-keys type=cookie -q
cookie: '["old-cookie-key-1", "old-cookie-key-2"]'In your new model, create Juju secrets using the values you just retrieved:
$ juju add-secret -m new-model hydra-system-keys system1=old-system-key-1 system2=old-system-key-2
$ juju add-secret -m new-model hydra-cookie-keys cookie1=old-cookie-key-1 cookie2=old-cookie-key-2💡 Important: The order of the key-value pairs matters. The first key you provide (e.g., system1) will become the primary secret for the new Hydra instance.
Now we can deploy the Hydra in the new model, referencing the Juju secrets you just created:
juju deploy -m new-model hydra --config initial_system_secret_id=secret:<system-secret-id> --config initial_cookie_secret_id=secret:<cookie-secret-id>After deployment, you must grant the Hydra charm access to the secrets:
juju grant-secret -m new-model system hydra
juju grant-secret -m new-model cookie hydraNow, integrate the new Hydra instance with your migrated PostgreSQL database and any other necessary applications:
juju integrate -m new-model hydra postgresql
# ... integrate with other applications as neededOnce the new Hydra instance is running and integrated, it should be able to decrypt and use the backed-up database data seamlessly. You can verify this by checking that the new instance's JWKS endpoint (https://hydra-url/.well-known/jwks.json) matches the one from your old deployment.
The image used by this charm is hosted on Docker Hub and maintained by Ory.
Please see SECURITY.md for guidelines on reporting security issues.
Please see the Juju SDK docs for guidelines on enhancements to this charm following best practice guidelines, and CONTRIBUTING.md for developer guidance.
The Charmed Hydra Operator is free software, distributed under the Apache Software License, version 2.0. See LICENSE for more information.