A continuation of HomeBox the inventory and organization system built for the Home User
Improve oidc docs and fix attachment issue (#1153)
Tonya096b682f0a46
diff --git a/backend/app/api/handlers/v1/v1_ctrl_auth.go b/backend/app/api/handlers/v1/v1_ctrl_auth.goindex defc8175..50468970 100644--- a/backend/app/api/handlers/v1/v1_ctrl_auth.go+++ b/backend/app/api/handlers/v1/v1_ctrl_auth.go@@ -124,7 +124,7 @@ func (ctrl *V1Controller) HandleAuthLogin(ps ...AuthProvider) errchain.HandlerFureturn validate.NewUnauthorizedError()}- ctrl.setCookies(w, noPort(r.Host), newToken.Raw, newToken.ExpiresAt, true)+ ctrl.setCookies(w, noPort(r.Host), newToken.Raw, newToken.ExpiresAt, true, newToken.AttachmentToken)return server.JSON(w, http.StatusOK, TokenResponse{Token: "Bearer " + newToken.Raw,ExpiresAt: newToken.ExpiresAt,@@ -178,7 +178,7 @@ func (ctrl *V1Controller) HandleAuthRefresh() errchain.HandlerFunc {return validate.NewUnauthorizedError()}- ctrl.setCookies(w, noPort(r.Host), newToken.Raw, newToken.ExpiresAt, false)+ ctrl.setCookies(w, noPort(r.Host), newToken.Raw, newToken.ExpiresAt, false, newToken.AttachmentToken)return server.JSON(w, http.StatusOK, newToken)}}@@ -187,7 +187,7 @@ func noPort(host string) string {return strings.Split(host, ":")[0]}-func (ctrl *V1Controller) setCookies(w http.ResponseWriter, domain, token string, expires time.Time, remember bool) {+func (ctrl *V1Controller) setCookies(w http.ResponseWriter, domain, token string, expires time.Time, remember bool, attachmentToken string) {http.SetCookie(w, &http.Cookie{Name: cookieNameRemember,Value: strconv.FormatBool(remember),@@ -219,6 +219,19 @@ func (ctrl *V1Controller) setCookies(w http.ResponseWriter, domain, token stringHttpOnly: false,Path: "/",})++ // Set attachment token cookie (accessible to frontend, not HttpOnly)+ if attachmentToken != "" {+ http.SetCookie(w, &http.Cookie{+ Name: "hb.auth.attachment_token",+ Value: attachmentToken,+ Expires: expires,+ Domain: domain,+ Secure: ctrl.cookieSecure,+ HttpOnly: false,+ Path: "/",+ })+ }}func (ctrl *V1Controller) unsetCookies(w http.ResponseWriter, domain string) {@@ -252,6 +265,17 @@ func (ctrl *V1Controller) unsetCookies(w http.ResponseWriter, domain string) {HttpOnly: false,Path: "/",})++ // Unset attachment token cookie+ http.SetCookie(w, &http.Cookie{+ Name: "hb.auth.attachment_token",+ Value: "",+ Expires: time.Unix(0, 0),+ Domain: domain,+ Secure: ctrl.cookieSecure,+ HttpOnly: false,+ Path: "/",+ })}// HandleOIDCLogin godoc@@ -310,7 +334,7 @@ func (ctrl *V1Controller) HandleOIDCCallback() errchain.HandlerFunc {}// Set cookies and redirect to home- ctrl.setCookies(w, noPort(r.Host), newToken.Raw, newToken.ExpiresAt, true)+ ctrl.setCookies(w, noPort(r.Host), newToken.Raw, newToken.ExpiresAt, true, newToken.AttachmentToken)http.Redirect(w, r, "/home", http.StatusFound)return nil}diff --git a/docs/.vitepress/menus/en.mts b/docs/.vitepress/menus/en.mtsindex ca1fb40a..41257424 100644--- a/docs/.vitepress/menus/en.mts+++ b/docs/.vitepress/menus/en.mts@@ -6,6 +6,7 @@ export default [{text: 'Installation', link: '/en/installation'},{text: 'Configure', link: '/en/configure'},{text: 'Storage', link: '/en/configure/storage'},+ {text: 'OIDC', link: '/en/configure/oidc'},{text: 'Upgrade Guide', link: '/en/upgrade'},{text: 'Migration Guide', link: '/en/migration'},]diff --git a/docs/en/configure/index.md b/docs/en/configure/index.mdindex bceb5c43..b643d83c 100644--- a/docs/en/configure/index.md+++ b/docs/en/configure/index.md@@ -73,6 +73,83 @@ aside: false| HBOX_THUMBNAIL_HEIGHT | 500 | height for generated thumbnails in pixels || HBOX_BARCODE_TOKEN_BARCODESPIDER | | API token for BarcodeSpider.com service used for barcode product lookups. If not set, barcode product lookups will not be performed. |+```sh+Options:+ --barcode-token-barcodespider <string>+ --database-database <string>+ --database-driver <string> (default: sqlite3)+ --database-host <string>+ --database-password <string>+ --database-port <string>+ --database-pub-sub-conn-string <string> (default: mem://{{ .Topic }})+ --database-sqlite-path <string> (default: ./.data/homebox.db?_pragma=busy_timeout=999&_pragma=journal_mode=WAL&_fk=1&_time_format=sqlite)+ --database-ssl-cert <string>+ --database-ssl-key <string>+ --database-ssl-mode <string> (default: require)+ --database-ssl-root-cert <string>+ --database-username <string>+ --debug-enabled <bool> (default: false)+ --debug-port <string> (default: 4000)+ --demo <bool>+ -h, --help display this help message+ --label-maker-additional-information <string>+ --label-maker-bold-font-path <string>+ --label-maker-dynamic-length <bool> (default: true)+ --label-maker-font-size <float> (default: 32.0)+ --label-maker-height <int> (default: 200)+ --label-maker-label-service-timeout <int>+ --label-maker-label-service-url <string>+ --label-maker-margin <int> (default: 32)+ --label-maker-padding <int> (default: 32)+ --label-maker-print-command <string>+ --label-maker-regular-font-path <string>+ --label-maker-width <int> (default: 526)+ --log-format <string> (default: text)+ --log-level <string> (default: info)+ --mailer-from <string>+ --mailer-host <string>+ --mailer-password <string>+ --mailer-port <int>+ --mailer-username <string>+ --mode <string> (default: development)+ --oidc-allowed-groups <string>+ --oidc-auto-redirect <bool> (default: false)+ --oidc-button-text <string> (default: Sign in with OIDC)+ --oidc-client-id <string>+ --oidc-client-secret <string>+ --oidc-email-claim <string> (default: email)+ --oidc-email-verified-claim <string> (default: email_verified)+ --oidc-enabled <bool> (default: false)+ --oidc-group-claim <string> (default: groups)+ --oidc-issuer-url <string>+ --oidc-name-claim <string> (default: name)+ --oidc-request-timeout <duration> (default: 30s)+ --oidc-scope <string> (default: openid profile email)+ --oidc-state-expiry <duration> (default: 10m)+ --oidc-verify-email <bool> (default: false)+ --options-allow-analytics <bool> (default: false)+ --options-allow-local-login <bool> (default: true)+ --options-allow-registration <bool> (default: true)+ --options-auto-increment-asset-id <bool> (default: true)+ --options-currency-config <string>+ --options-github-release-check <bool> (default: true)+ --options-hostname <string>+ --options-trust-proxy <bool> (default: false)+ --storage-conn-string <string> (default: file:///./)+ --storage-prefix-path <string> (default: .data)+ --thumbnail-enabled <bool> (default: true)+ --thumbnail-height <int> (default: 500)+ --thumbnail-width <int> (default: 500)+ -v, --version display version+ --web-host <string>+ --web-idle-timeout <duration> (default: 30s)+ --web-max-upload-size <int> (default: 10)+ --web-port <string> (default: 7745)+ --web-read-timeout <duration> (default: 10s)+ --web-write-timeout <duration> (default: 10s)+```+:::+### HBOX_WEB_HOST examples| Value | Notes |@@ -170,114 +247,4 @@ For SQLite in production:## OIDC Configuration-HomeBox supports OpenID Connect (OIDC) authentication, allowing users to login using external identity providers like Keycloak, Authentik, Google, Microsoft, etc.--### 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- - `HBOX_OIDC_CLIENT_ID`: Client ID from your OIDC provider- - `HBOX_OIDC_CLIENT_SECRET`: Client secret from your OIDC provider--3. **Configure Redirect URI**: In your OIDC provider, set the redirect URI to:- `https://your-homebox-domain.example.com/api/v1/users/login/oidc/callback`--### Advanced OIDC Configuration--- **Group Authorization**: Use `HBOX_OIDC_ALLOWED_GROUPS` to restrict access to specific groups-- **Custom Claims**: Configure `HBOX_OIDC_GROUP_CLAIM`, `HBOX_OIDC_EMAIL_CLAIM`, and `HBOX_OIDC_NAME_CLAIM` if your provider uses different claim names-- **Auto Redirect to OIDC**: Set `HBOX_OIDC_AUTO_REDIRECT=true` to automatically redirect users directly to OIDC-- **Local Login**: Set `HBOX_OPTIONS_ALLOW_LOCAL_LOGIN=false` to completely disable username/password login-- **Email Verification**: Set `HBOX_OIDC_VERIFY_EMAIL=true` to require email verification from the OIDC provider--### Security Considerations--::: warning OIDC Security-- Store `HBOX_OIDC_CLIENT_SECRET` securely (use environment variables, not config files)-- Use HTTPS for production deployments-- Configure proper redirect URIs in your OIDC provider-- Consider setting `HBOX_OIDC_ALLOWED_GROUPS` for group-based access control-:::--::: tip CLI Arguments-If you're deploying without docker you can use command line arguments to configure the application. Run `homebox --help`-for more information.--```sh-Options:- --barcode-token-barcodespider <string>- --database-database <string>- --database-driver <string> (default: sqlite3)- --database-host <string>- --database-password <string>- --database-port <string>- --database-pub-sub-conn-string <string> (default: mem://{{ .Topic }})- --database-sqlite-path <string> (default: ./.data/homebox.db?_pragma=busy_timeout=999&_pragma=journal_mode=WAL&_fk=1&_time_format=sqlite)- --database-ssl-cert <string>- --database-ssl-key <string>- --database-ssl-mode <string> (default: require)- --database-ssl-root-cert <string>- --database-username <string>- --debug-enabled <bool> (default: false)- --debug-port <string> (default: 4000)- --demo <bool>- -h, --help display this help message- --label-maker-additional-information <string>- --label-maker-bold-font-path <string>- --label-maker-dynamic-length <bool> (default: true)- --label-maker-font-size <float> (default: 32.0)- --label-maker-height <int> (default: 200)- --label-maker-label-service-timeout <int>- --label-maker-label-service-url <string>- --label-maker-margin <int> (default: 32)- --label-maker-padding <int> (default: 32)- --label-maker-print-command <string>- --label-maker-regular-font-path <string>- --label-maker-width <int> (default: 526)- --log-format <string> (default: text)- --log-level <string> (default: info)- --mailer-from <string>- --mailer-host <string>- --mailer-password <string>- --mailer-port <int>- --mailer-username <string>- --mode <string> (default: development)- --oidc-allowed-groups <string>- --oidc-auto-redirect <bool> (default: false)- --oidc-button-text <string> (default: Sign in with OIDC)- --oidc-client-id <string>- --oidc-client-secret <string>- --oidc-email-claim <string> (default: email)- --oidc-email-verified-claim <string> (default: email_verified)- --oidc-enabled <bool> (default: false)- --oidc-group-claim <string> (default: groups)- --oidc-issuer-url <string>- --oidc-name-claim <string> (default: name)- --oidc-request-timeout <duration> (default: 30s)- --oidc-scope <string> (default: openid profile email)- --oidc-state-expiry <duration> (default: 10m)- --oidc-verify-email <bool> (default: false)- --options-allow-analytics <bool> (default: false)- --options-allow-local-login <bool> (default: true)- --options-allow-registration <bool> (default: true)- --options-auto-increment-asset-id <bool> (default: true)- --options-currency-config <string>- --options-github-release-check <bool> (default: true)- --options-hostname <string>- --options-trust-proxy <bool> (default: false)- --storage-conn-string <string> (default: file:///./)- --storage-prefix-path <string> (default: .data)- --thumbnail-enabled <bool> (default: true)- --thumbnail-height <int> (default: 500)- --thumbnail-width <int> (default: 500)- -v, --version display version- --web-host <string>- --web-idle-timeout <duration> (default: 30s)- --web-max-upload-size <int> (default: 10)- --web-port <string> (default: 7745)- --web-read-timeout <duration> (default: 10s)- --web-write-timeout <duration> (default: 10s)-```--:::+For configuring OpenID Connect (OIDC) authentication, refer to the [OIDC Configuration Guide](/en/configure/oidc).diff --git a/docs/en/configure/oidc.md b/docs/en/configure/oidc.mdnew file mode 100644index 00000000..d6c3d129--- /dev/null+++ b/docs/en/configure/oidc.md@@ -0,0 +1,38 @@+# Configure OIDC++HomeBox supports OpenID Connect (OIDC) authentication, allowing users to login using external identity providers like Keycloak, Authentik, Authelia, Google, Microsoft, etc.++## 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 should be a URL without a trailing slash).+ - `HBOX_OIDC_CLIENT_ID`: Client ID from your OIDC provider.+ - `HBOX_OIDC_CLIENT_SECRET`: Client secret from your OIDC provider.+ - If you are using a reverse proxy, it may be necessary to set `HBOX_OPTIONS_TRUST_PROXY=true` to ensure `https` is correctly detected.++3. **Configure Redirect URI**: In your OIDC provider, set the redirect URI to:+ `https://your-homebox-domain.example.com/api/v1/users/login/oidc/callback`.++## Advanced OIDC Configuration++- **Group Authorization**: Use `HBOX_OIDC_ALLOWED_GROUPS` to restrict access to specific groups, e.g. `HBOX_OIDC_ALLOWED_GROUPS=admin,homebox`.+ - Some providers require the `groups` scope to return group claims, include it in `HBOX_OIDC_SCOPE` (e.g. `openid profile email groups`) or configure the provider to release the claim.+- **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 directly to OIDC.+- **Local Login**: Set `HBOX_OPTIONS_ALLOW_LOCAL_LOGIN=false` to completely disable username/password login.+- **Email Verification**: Set `HBOX_OIDC_VERIFY_EMAIL=true` to require email verification from the OIDC provider.++## Security Considerations++::: warning OIDC Security+- Store `HBOX_OIDC_CLIENT_SECRET` securely (use environment variables, not config files).+- Use HTTPS for production deployments.+- Configure proper redirect URIs in your OIDC provider.+- Consider setting `HBOX_OIDC_ALLOWED_GROUPS` for group-based access control.+:::++::: tip CLI Arguments+If you're deploying without docker you can use command line arguments to configure the application. Run `homebox --help` for more information.+:::\ No newline at end of file