verdaccio-theme-oidc

A custom Verdaccio theme that replaces the default login UI with a native OIDC flow. Works with any OpenID Connect provider (Google, Azure AD, Okta, Auth0, Keycloak, etc.).

Features

Authentication

• "Sign in with {Provider}" — OIDC PKCE redirect (provider auto-detected)
• Silent session restore on page refresh
• Token expiry tracking with status dot in header and expiry banner
• Re-authentication prompts for expired sessions and step-up operations
• Post-login return-to-page navigation

Package browsing

• Package grid with full-text search (name, description, keywords, and lazily indexed README text), scope filter, sort (newest, A–Z)
• Group-by-scope with collapse/expand
• Virtualized list (windowed rendering) — smooth scrolling for large registries
• Recent activity sidebar
• Keyboard shortcuts (/ and Ctrl+K to focus search)

Package detail

• Readme tab (GFM, syntax highlighting, anchor links)
• Versions tab (dist-tags, paginated list, publish dates)
• Dependencies tab (deps, peer, dev) with links to internal packages
• Uplinks tab (fetch time, etag)
• Sidebar: install commands (npm, pnpm, yarn, bun), .npmrc snippet, metadata (license, engines, size, dates, maintainers, links), quality score heuristic
• Deprecation warning banner

Settings — Quick Setup

• .npmrc with masked auth (reveal, copy, download)
• CLI config commands for npm, pnpm, and yarn (with tabs)
• Interactive npm login instructions

Settings — Account

• Profile info (avatar, name, email, provider, groups)
• Session status and permission badges (admin, token creation)
• Personal package permissions table (access/publish/unpublish per pattern)

Settings — API Tokens

• Create tokens with name and TTL presets (7–90 days)
• Least-privilege Permissions selector: full access, read-only (install but never publish), or publish only to specific package patterns (@scope/*, prefix-*, exact names); scoped tokens show a read-only/scoped badge
• One-time reveal with countdown timer (auto-clears after 60s)
• CI-ready NPM_AUTH value (base64-encoded, copy-ready)
• .npmrc CI snippet with ${NPM_AUTH} placeholder
• Active/inactive token list with expiry badges, last-used timestamps, and a fingerprint (last 4 chars of the NPM_AUTH value) to tell tokens apart
• Two-step revoke confirmation
• Re-auth banner when step-up authentication required
• Link to personal permissions for understanding token access scope

Settings — Admin

• Package Access: Merged view of config + dynamic rules; add/remove users and groups per pattern per action (access/publish/unpublish); create/delete dynamic patterns (when allowed)
• Access Control: Token creation mode display; manage token admins, allowed users, and the deny-list kill switch (blocks an identity from all auth and revokes its tokens); allowed groups (read-only, config-defined)
• All Tokens: Browse and filter all users' tokens; revoke individual tokens or all tokens for a user
• Audit Log: Unified event feed (token, ACL, package access) with server-side action/actor/date filters and paging
• Metrics: Runtime counters (auth success/failure, tokens, JWKS cache, active tokens, rate-limit rejections, audit-sink delivery, uptime) from the auth plugin's metrics endpoint
• Uplinks: Health status, host, auth configuration, timeout/retry settings

UX

• Dark/light theme toggle (persisted)
• Responsive layout (1024/768/480 breakpoints)
• Focus-visible indicators, ARIA labels on interactive elements
• Masked secrets with timed reveal

Requirements

This theme requires the companion verdaccio-auth-oidc plugin configured with both auth and middlewares sections. The middleware must have client_id set to enable browser-based PKCE login.

Installation

# Copy built theme to Verdaccio plugins directory
mkdir -p /path/to/verdaccio/plugins/verdaccio-theme-oidc
cp index.js static/ /path/to/verdaccio/plugins/verdaccio-theme-oidc/

Version compatibility: install the same version of @edyd/verdaccio-theme-oidc and @edyd/verdaccio-auth-oidc. They are released in lockstep; the theme's admin UI calls auth-plugin endpoints, so a newer theme paired with an older auth plugin can break the admin views.

Configuration

Add to your Verdaccio config.yaml:

theme:
  oidc: {}

auth:
  auth-oidc:
    issuer: 'https://accounts.google.com'
    username_claim: email

middlewares:
  auth-oidc:
    enabled: true
    client_id: 'your-oidc-client-id'
    external_url: 'https://your-verdaccio-host'

The provider name is auto-detected from the issuer URL. No additional theme configuration is needed.

With API tokens

To enable the token management UI in the settings page, configure api_tokens in the auth section:

auth:
  auth-oidc:
    issuer: 'https://accounts.google.com'
    username_claim: email
    api_tokens:
      enabled: true
      admin_users:
        - '[email protected]'

middlewares:
  auth-oidc:
    enabled: true
    client_id: 'your-oidc-client-id'
    external_url: 'https://your-verdaccio-host'

theme:
  oidc: {}

See the verdaccio-auth-oidc README for the full list of api_tokens options.

Troubleshooting

"OIDC authentication is not configured" — The middlewares section is missing or the auth-oidc middleware plugin is not installed. Add the middlewares section to your config.

"OIDC browser login is not enabled" — The middleware is installed but client_id is not set. Add client_id to your middleware config.

"Login redirects to the OIDC provider but never returns" — Make sure the redirect URI https://your-host/-/oidc/callback is registered in your OIDC provider's application settings.

Token management not showing — The api_tokens.enabled flag is not set in the auth config, or the user does not have permission to create tokens.

License

MIT