Related Features

Admin UI OIDC Login

SeaweedFS Enterprise supports OpenID Connect (OIDC) authorization code login for the admin UI. This lets operators sign in through an existing identity provider such as Keycloak, Okta, Authentik, or another standards-compliant OIDC service instead of managing a separate admin password.

What It Does

  • Adds a Sign in with OIDC button to the admin login page
  • Supports the standard authorization code flow
  • Maps OIDC users to SeaweedFS admin UI roles: admin or readonly
  • Caps the admin UI session lifetime to the OIDC ID token expiration
  • Can run alongside local admin credentials on the same login page

If both local credentials and OIDC are configured, users can choose either sign-in method.

Why Customers Use It

  • Single sign-on: Reuse the same identity provider already used for internal apps
  • Centralized access control: Grant or revoke admin access through IdP groups or claims
  • Reduced credential sprawl: Avoid storing a separate admin password for every operator
  • Safer session handling: SeaweedFS limits the admin session to the source token lifetime

Configuration

Configure OIDC in security.toml under [admin.oidc].

[admin.oidc]
enabled = true
issuer = "https://idp.example.com/realms/seaweed"
client_id = "seaweedfs-admin-ui"
client_secret = "replace-me"
redirect_url = "https://admin.example.com/login/oidc/callback"
scopes = ["openid", "profile", "email"]
jwks_uri = ""                     # optional override; defaults from OIDC discovery
tls_ca_cert = ""                  # optional absolute path for a custom CA bundle
tls_insecure_skip_verify = false  # testing only; do not use in production

[admin.oidc.role_mapping]
default_role = "readonly"

[[admin.oidc.role_mapping.rules]]
claim = "groups"
value = "seaweedfs-admin"
role = "admin"

[[admin.oidc.role_mapping.rules]]
claim = "groups"
value = "seaweedfs-readonly"
role = "readonly"

Required Fields

  • issuer: OIDC issuer URL
  • client_id: OAuth client ID
  • client_secret: OAuth client secret
  • redirect_url: callback URL registered with your identity provider
  • role_mapping: at least one rule or a default_role

Allowed admin UI roles are:

  • admin
  • readonly

Redirect URL

The redirect URL must point to the SeaweedFS admin callback endpoint:

/login/oidc/callback

Examples:

  • https://admin.example.com/login/oidc/callback
  • https://admin.example.com/seaweedfs/login/oidc/callback when the admin UI is served behind -urlPrefix=/seaweedfs

For production deployments, use HTTPS. HTTP is only appropriate for localhost development.

Role Mapping

SeaweedFS does not create a new permission model for OIDC users. Instead, it maps OIDC claims into the two existing admin UI roles:

  • admin: full read/write access in the admin UI
  • readonly: view-only access

Typical mappings use an IdP group claim such as groups, but any string or string-list claim can be matched.

Admin Startup Behavior

  • OIDC endpoints are discovered when the admin server starts
  • If your identity provider changes its discovery endpoints, restart the admin server
  • If local admin credentials are also configured and OIDC initialization fails, the admin UI still starts with local login enabled

Production Notes

  • Prefer enabling TLS on the admin server with [https.admin]
  • Register the exact external callback URL in your identity provider
  • If you use a private CA for the IdP, set tls_ca_cert to an absolute path
  • Avoid tls_insecure_skip_verify outside of short-lived test environments

Local Credentials and OIDC Together

You can keep a local break-glass admin account and still offer SSO:

  • Local auth comes from [admin] and [admin.readonly]
  • OIDC auth comes from [admin.oidc]
  • When both are configured, the /login page shows both sign-in options

This is useful when the identity provider is temporarily unavailable or when you want a recovery path during rollout.