OIDC SSO

HomeBox supports OpenID Connect (OIDC) authentication, allowing users to log in using external identity providers like Keycloak, Authentik, Authelia, Google, Microsoft, etc.

Note

When configuring OIDC, always refer to the documentation provided by your identity provider for specific details and requirements.

Basic OIDC Setup

1. Enable OIDC: Set HBOX_OIDC_ENABLED=true
2. Provider Configuration: Set the required provider details:
   • HBOX_OIDC_ISSUER_URL: Your OIDC provider’s issuer URL, this must match exactly!
   • HBOX_OIDC_CLIENT_ID: Client ID provided by your OIDC provider
   • HBOX_OIDC_CLIENT_SECRET: Client secret provided by your OIDC provider
   • If using a reverse proxy, you may need to set HBOX_OPTIONS_TRUST_PROXY=true to ensure https is correctly detected.
   • If you have set HBOX_OPTIONS_HOSTNAME ensure it uses only the hostname, without the protocol (not https:// or http://)
3. Configure Redirect URI: Set the redirect URI in your OIDC provider to https://yourhomebox.example.com/api/v1/users/login/oidc/callback

Tip

To get the exact issuer URL from your OIDC provider, you can go to the .well-known/openid-configuration endpoint. So if the provider is https://auth.example.com, the well-known URL would be https://auth.example.com/.well-known/openid-configuration. The well-known URL will have a issuer key with the exact issuer URL that Homebox requires to function.

Check the documentation of your OIDC provider to get the exact well-known URL.

Advanced Configuration

• Group Authorization: Use HBOX_OIDC_ALLOWED_GROUPS to restrict access to certain groups. (e.g. HBOX_OIDC_ALLOWED_GROUPS=admins,developers)
  • Some providers require the groups scope to be enabled. Include it in HBOX_OIDC_SCOPES if necessary. (e.g. HBOX_OIDC_SCOPES=openid profile email groups)
• Custom Claims: Configure HBOX_OIDC_GROUP_CLAIM, HBOX_OIDC_EMAIL_CLAIM and HBOX_OIDC_NAME_CLAIM if your provider uses different claim names.
  • These default to HBOX_OIDC_GROUP_CLAIM=groups, HBOX_OIDC_EMAIL_CLAIM=email and HBOX_OIDC_NAME_CLAIM=name
• Auto Redirect to OIDC: Set HBOX_OIDC_AUTO_REDIRECT=true to automatically redirect users to the OIDC provider for authentication.
• Local Login: Set HBOX_OPTIONS_ALLOW_LOCAL_LOGIN=false to disable the usage of local credentials.
• Email Verification: Set HBOX_OIDC_VERIFY_EMAIL=true to require email verification from the OIDC provider before login.

Security Considerations

• Store HBOX_OIDC_CLIENT_SECRET in a securely, (e.g., environment variable manager or secret management tool).
• Use HTTPS for production deployments.
• Configure proper redirects in your OIDC provider, we don’t recommend the use of wildcards.
• Consider setting HBOX_OIDC_ALLOWED_GROUPS to restrict access to certain groups.

Note

If you’re deploying without docker containers, you can use command line arguments to configure HomeBox. Run homebox --help for more information.