Run OneiD in your own environment
Compare OneiD hosted by us with running it yourself, and see what your own environment needs for running, scaling and backups.
You can use OneiD hosted by us or run it in your own environment. Either way, each customer has its own OneiD deployment: one OneiD address, one database and one sign-in source. This page gives an overview of running OneiD yourself. We provide the installation guide and support.
Hosted by OneiD or your own environment
| Hosted by OneiD | In your own environment | |
|---|---|---|
| Who runs OneiD | The OneiD team | You |
| OneiD address and data store | Your own, provided by us | Your own |
| Software and support | The OneiD team | We supply the software and support |
| Containers, database, network | The OneiD team | You |
| Backups | Ask us | You |
For applications, there is no difference: the endpoints, flows and tokens are the same.
What your environment needs
- Container runtime. OneiD runs as Docker containers.
- Reverse proxy. A reverse proxy in front of OneiD that terminates TLS.
- PostgreSQL. OneiD keeps users, clients, signing keys, tokens and its other state in a PostgreSQL database.
- An https OneiD address. The address becomes the issuer in every token. Choose it carefully: changing it later changes the issuer that every application and API checks.
- A certificate to protect OneiD’s key ring. OneiD encrypts signing keys, MFA secrets and cookies at rest with keys that this certificate protects.
- Email (SMTP with TLS). OneiD sends password reset codes, user name reminders and MFA notifications by email.
- An initial administrator password, set at the first start.
- Your sign-in source. OneiD accounts, your LDAP or Active Directory server, or an OpenID Connect provider. See Where users come from.
Health endpoints
| Endpoint | Use |
|---|---|
/health/live |
Liveness: the process is running. |
/health/ready |
Readiness: OneiD is ready to serve requests. |
Both return a status only, with no details. Use them for your load balancer and container orchestrator checks.
Running several instances
You can run several OneiD instances behind a load balancer. They share their state through the database, so a user can start a sign-in on one instance and finish it on another.
Signing-key rotation
OneiD signs tokens with RSA keys and publishes the public keys in its JWKS.
- An administrator rotates the key in the admin console and chooses an activation time.
- OneiD publishes the new key in the JWKS early, before it signs anything with it, so that applications and APIs can fetch it in advance. When you run several instances, ask us for the restart sequence.
- The new key starts signing once the activation time has passed and the instances have restarted. Plan a restart of every instance after the activation time.
- The retired key stays in the JWKS for 30 days, so tokens it signed still validate.
Applications and APIs that cache the JWKS and re-fetch it on an unknown kid need no change.
Backups
In your own environment, backups are yours. Back up the PostgreSQL database regularly and test restores.
Keep the key-ring certificate with your backups, stored separately and securely. The signing keys and MFA secrets in the database are encrypted with keys that the certificate protects, so a database backup is of little use without it.
OneiD needs a working SMTP server with TLS. Without it, users of OneiD accounts cannot reset passwords or get user name reminders, and do not receive MFA notifications. Test email delivery before you go live.
Support
We provide the installation guide and support for running OneiD in your own environment. Contact us through the contact page.