Operate
OpenID Connect sign-in
Connect an OIDC provider with PKCE, exact issuer/subject bindings, controlled enrollment, and recovery planning.
v0.3.0 referenceReviewed
On this page
OIDC authenticates a user; Hopya retains its own account, sessions, workspace memberships, and roles. A provider that supports OIDC does not need SAML for this connection.
Test your exact provider/version/HTTPS topology. Keep a tested local administrator account for recovery.
Provider Requirements
| Requirement | Value |
|---|---|
| Discovery | Standards-compliant OIDC metadata |
| Flow | Authorization Code with ID tokens |
| PKCE | S256 |
| Confidential client auth | client_secret_post |
| Scopes | openid, profile, email |
| Identity | Stable iss + sub; exact (issuer, subject) binding |
| JIT provisioning | Valid email + boolean email_verified:true; optional name |
| Production URLs | HTTPS for Hopya, issuer, and every discovered endpoint |
Register Hopya
- Create a confidential client named Hopya.
- Register the exact callback:
https://tasks.example.com/api/v1/auth/sso/callback- Enable Authorization Code, PKCE S256, and
openid profile email. - Restrict access to intended users/groups; prefer an allowlisted group when supported.
- Store client ID/secret privately as operator configuration.
Issuer must match exactly: use discovery’s issuer value, not its discovery-document URL. Preserve paths, case, and trailing slash.
Configure Hopya
| Variable | Set to |
|---|---|
APP_URL | Exact public HTTPS origin, e.g. https://tasks.example.com |
OIDC_ISSUER | Exact discovery issuer, e.g. https://id.example.com |
OIDC_CLIENT_ID | Registered client ID |
OIDC_CLIENT_SECRET | Privately supplied client secret |
OIDC_AUTO_PROVISION | True only for deliberate verified non-admin enrollment; false otherwise |
OIDC_ALLOW_INSECURE_HTTP | False for normal deployment |
After supplying those values privately, recreate the deployment:
docker compose up -d --build --force-recreateCompose sends provider variables only to the API. Never expose the secret through PUBLIC_*.
Open the instance’s /login and choose Continue with single sign-on. First login can create a non-admin account only with valid verified non-colliding email and enabled provisioning. Repeat logins use (issuer, sub), not email.
Grant Access
- Restrict the client to intended users/groups.
- Deliberately enable
OIDC_AUTO_PROVISION=true; let users sign in once. - Add each Hopya account to the intended workspace and role.
- Optionally disable provisioning again and recreate the API; existing identity bindings continue working.
| Enrollment case | Result |
|---|---|
| Verified new email + provisioning enabled | New non-admin account, no existing workspace membership |
| Email already belongs to a local account | No automatic linking; admin must independently verify issuer/subject and explicitly link in OIDC identities |
| Same linked issuer/subject, changed email | Stable identity binding, not email matching |
Email alone is not proof of identity. Workspace access always follows Hopya membership rules.
Provider Notes
| Provider / topology | Check |
|---|---|
| Pocket ID | Configure Allowed User Groups; new client initially permits no groups; issuer normally public base URL |
| Separate login/authorization services | Use discovery issuer, not account-management URL |
| Other providers | Verify discovery, client auth, claims, HTTPS; no blanket certification |
Lifecycle Limits
| Action | Limit / required follow-up |
|---|---|
| Provider creates/deletes user | Not directory synchronization; no automatic immediate Hopya create/disable/remove; no SCIM endpoint |
| Remove upstream access | Blocks future authorization, not an already-issued Hopya session |
| Immediate deprovisioning | Also remove Hopya workspace memberships or disable account |
| Local logout | Not a promise of provider-wide logout |
Sources: