Files

T

Diocrafts f08cffc0e8 feat: add VitePress docs site, music file picker modal, Dockerfile optimization, i18n keys for 14 locales

- Add docs/ with VitePress site (19 pages): guide, config, architecture, FAQ
- Add GitHub Actions workflow for auto-deploy to GitHub Pages
- Replace music 'Add Tracks' upload picker with in-app audio file browser modal
- Add music picker CSS styles with dark theme support
- Add missing i18n keys (search_audio, no_audio_files, etc.) to all 14 locales
- Optimize Dockerfile: shared base stage, COPY --chmod, consolidated RUN, HEALTHCHECK
- Improve README: docs links, updated stats (222+ tests, 14 languages), feature status

2026-04-11 20:58:34 +02:00

3.5 KiB

Raw Blame History

OIDC / SSO

OxiCloud supports OpenID Connect for single sign-on with providers like Keycloak, Authentik, Authelia, Google, and Azure AD.

How It Works

User clicks "Sign in with SSO" on the login page
Browser redirects to the identity provider (IdP)
User authenticates with their existing credentials
IdP redirects back to OxiCloud with an auth code
OxiCloud exchanges the code for user info and issues its own JWT tokens

Configuration

OXICLOUD_OIDC_ENABLED=true
OXICLOUD_OIDC_ISSUER_URL="https://authentik.example.com/application/o/oxicloud/"
OXICLOUD_OIDC_CLIENT_ID="your-client-id"
OXICLOUD_OIDC_CLIENT_SECRET="your-client-secret"
OXICLOUD_OIDC_REDIRECT_URI="https://oxicloud.example.com/api/auth/oidc/callback"
OXICLOUD_OIDC_SCOPES="openid profile email"
OXICLOUD_OIDC_FRONTEND_URL="https://oxicloud.example.com"
OXICLOUD_OIDC_AUTO_PROVISION=true
OXICLOUD_OIDC_ADMIN_GROUPS="oxicloud-admins"
OXICLOUD_OIDC_PROVIDER_NAME="Authentik"

Variable Reference

Variable	Default	Description
`OXICLOUD_OIDC_ENABLED`	`false`	Master switch
`OXICLOUD_OIDC_ISSUER_URL`	—	Provider's OIDC issuer URL
`OXICLOUD_OIDC_CLIENT_ID`	—	OAuth client ID
`OXICLOUD_OIDC_CLIENT_SECRET`	—	OAuth client secret
`OXICLOUD_OIDC_REDIRECT_URI`	`http://localhost:8086/api/auth/oidc/callback`	Callback URL registered with the IdP
`OXICLOUD_OIDC_SCOPES`	`openid profile email`	Requested scopes
`OXICLOUD_OIDC_FRONTEND_URL`	`http://localhost:8086`	Where to redirect the browser after auth
`OXICLOUD_OIDC_AUTO_PROVISION`	`true`	Auto-create users on first login
`OXICLOUD_OIDC_ADMIN_GROUPS`	—	OIDC groups that grant admin role
`OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN`	`false`	Hide password login when OIDC is active
`OXICLOUD_OIDC_PROVIDER_NAME`	`SSO`	Label shown on the login button

::: warning If OXICLOUD_OIDC_ENABLED=true but issuer_url, client_id, or client_secret are empty, OIDC is automatically disabled with an error log. :::

API Endpoints

Method	Endpoint	Description
GET	`/api/auth/oidc/providers`	Returns OIDC provider info
GET	`/api/auth/oidc/authorize`	Authorization URL for redirect to IdP
GET	`/api/auth/oidc/callback`	Callback from IdP with auth code
POST	`/api/auth/oidc/exchange`	Exchange auth code for JWT tokens

Provider Examples

Keycloak

# docker-compose.yml
services:
  oxicloud:
    environment:
      OXICLOUD_OIDC_ENABLED: "true"
      OXICLOUD_OIDC_ISSUER_URL: "https://keycloak.example.com/realms/your-realm"
      OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
      OXICLOUD_OIDC_CLIENT_SECRET: "your-client-secret"
      OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
      OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
      OXICLOUD_OIDC_PROVIDER_NAME: "Keycloak"

Authentik

OXICLOUD_OIDC_ISSUER_URL="https://authentik.example.com/application/o/oxicloud/"
OXICLOUD_OIDC_PROVIDER_NAME="Authentik"

Google

OXICLOUD_OIDC_ISSUER_URL="https://accounts.google.com"
OXICLOUD_OIDC_PROVIDER_NAME="Google"

Notes

Always use HTTPS for OIDC connections
One OIDC provider per instance (single-provider model)
OIDC users share the same permissions model as local users
After OIDC auth, the backend issues its own JWT tokens (no IdP token dependency)
Use the admin settings UI (/admin.html) to configure and test OIDC at runtime

3.5 KiB Raw Blame History