OIDC authentication for the Strapi Admin Panel. Works with Keycloak, Auth0, Okta, Azure AD, Authentik, Authelia, and any other OpenID Connect provider.

• Features
• Quick Start
• Installation
• Configuration
  • Client assertion
  • Security features
  • Client IP attribution and reverse proxies
• Usage
  • Login
  • Logout
• Admin Settings
• Group-to-Role Mapping
  • Example configuration
  • Role assignment precedence
  • Role updates on subsequent logins
• REST API
• Credits
• Donations
• License

Features

• OIDC sign-in for the Strapi Admin Panel using Authorization Code flow with PKCE
• Works with any OIDC provider, including Keycloak, Auth0, Okta, Azure AD, Authentik, and Authelia
• Configurable Login via SSO button with custom text
• Enforce OIDC mode to remove email/password login and block local-login API calls
• Skip Login Page to redirect unauthenticated users straight to the IdP
• Default OIDC roles assigned to new users on first login
• Email whitelist with optional per-entry role overrides, JSON import/export, and a REST API
• Group-to-role mapping based on a configurable OIDC claim
• Audit log of authentication events with admin UI filtering, NDJSON export, and a REST API
• Configurable audit-log retention and Remember Me sessions
• RP-initiated logout and backchannel logout support
• Optional private-key JWT client assertion for token-endpoint authentication
• Optional email verification requirement before login is allowed
• Secure, httpOnly, __Host- prefixed cookies with PKCE state and nonce

Quick Start

Add the plugin to config/plugins.js (or .ts) with the four required values:

module.exports = ({ env }) => ({
  'strapi-plugin-oidc': {
    enabled: true,
    config: {
      OIDC_PUBLIC_URL: env('PUBLIC_URL', 'https://strapi.example.com'), // origin only -- we append /strapi-plugin-oidc/oidc/callback
      OIDC_ISSUER: env('OIDC_ISSUER'),
      OIDC_CLIENT_ID: env('OIDC_CLIENT_ID'),
      OIDC_CLIENT_SECRET: env('OIDC_CLIENT_SECRET'),
    },
  },
});

Then restart Strapi, go to Settings → OIDC Plugin, choose the default roles, and click Save.

Installation

npm install strapi-plugin-oidc

Configuration

All options can be set in config/plugins.js or via environment variables. Optional values use the defaults shown below.

| Option | Required | Default | Description | | ----------------------------- | ---------------------------------- | ---------------------- | --------------------------------------------------------------------------- | | OIDC_PUBLIC_URL | Yes, if PUBLIC_URL is not set | '' | Strapi origin (scheme + host + port, no path or trailing slash) | | OIDC_ISSUER | Yes | '' | Provider issuer URL, e.g. https://auth.example.com/realms/myrealm | | OIDC_CLIENT_ID | Yes | '' | Client ID registered with the provider | | OIDC_CLIENT_SECRET | Yes, unless using client assertion | '' | Client secret | | OIDC_CLIENT_ASSERTION | No | '' | Private-key JWT for token-endpoint auth (replaces client_secret) | | OIDC_SCOPE | No | openid profile email | Space-separated OIDC scopes | | OIDC_FAMILY_NAME_FIELD | No | family_name | Claim field used for the user's family name | | OIDC_GIVEN_NAME_FIELD | No | given_name | Claim field used for the user's given name | | OIDC_SSO_BUTTON_TEXT | No | Login via SSO | Text shown on the SSO button | | OIDC_ENFORCE | No | null | null = use Admin UI toggle; true/false = config override | | OIDC_SKIP_LOGIN_PAGE | No | null | null = use Admin UI toggle; true/false = config override | | REMEMBER_ME | No | false | Persist admin sessions across browser restarts | | AUDIT_LOG_RETENTION_DAYS | No | 90 | Days to keep audit logs; set 0 to disable | | OIDC_GROUP_FIELD | No | groups | Claim field containing group membership | | OIDC_GROUP_ROLE_MAP | No | {} | JSON map of group names to arrays of Strapi role names | | OIDC_REQUIRE_EMAIL_VERIFIED | No | true | Reject logins unless the provider reports email_verified=true | | OIDC_TRUSTED_IP_HEADER | No | '' | Trusted proxy header containing the real client IP (see reverse-proxy note) | | OIDC_FORCE_SECURE_COOKIES | No | false | Force the Secure cookie flag (only use behind HTTPS) | | OIDC_MAX_AGE | No | undefined | max_age sent to the IdP, in seconds | | OIDC_PROMPT | No | '' | prompt sent to the IdP, e.g. login or consent |

OIDC_PUBLIC_URL is your Strapi instance's origin, e.g. https://myapp.com. The plugin appends /strapi-plugin-oidc/oidc/callback to build the full redirect URI.

OIDC_ISSUER is the provider's issuer URL. The plugin uses it for OIDC discovery via openid-client, which is the single source of truth for all endpoints, the JWKS URI, and the canonical issuer. Discovery is lazy; it runs on the first sign-in request and is cached for 15 minutes, so Strapi boots even if the IdP is temporarily unreachable.

Note: The explicit endpoint overrides (OIDC_AUTHORIZATION_ENDPOINT, OIDC_TOKEN_ENDPOINT, OIDC_USERINFO_ENDPOINT, OIDC_END_SESSION_ENDPOINT, OIDC_JWKS_URI) were removed in this version. If you previously configured them, delete those keys and rely on OIDC_ISSUER plus discovery.

Client assertion

Instead of a static client_secret, you can authenticate to the IdP token endpoint with a private-key JWT. Set either OIDC_CLIENT_SECRET or OIDC_CLIENT_ASSERTION, not both.

module.exports = ({ env }) => ({
  'strapi-plugin-oidc': {
    enabled: true,
    config: {
      // ... other required OIDC config ...
      OIDC_CLIENT_SECRET: '', // leave empty when using an assertion
      OIDC_CLIENT_ASSERTION: env('OIDC_CLIENT_ASSERTION'), // JSON string or object
    },
  },
});

OIDC_CLIENT_ASSERTION accepts either a JSON string or an object with the following shape:

| Field | Required | Default | Description | | ------------ | -------- | ------- | ----------------------------------------------------------- | | privateKey | Yes | - | PKCS#8 private key in PEM format | | keyId | No | - | Key ID (kid) to include in the JWT header | | algorithm | No | RS256 | Signing algorithm (must match the key type the IdP expects) |

Security features

• OIDC protocol layer: Built on openid-client v6, which handles discovery, PKCE, token exchange, ID-token verification, userinfo, and RP-initiated logout
• ID token verification: Enabled automatically when the discovery document includes a jwks_uri. Validates signature, issuer, audience, and expiry
• Email verification: OIDC_REQUIRE_EMAIL_VERIFIED: true (default) rejects unverified emails
• CSRF protection: OIDC state/nonce and POST-only logout endpoint
• Rate limiting: 1 000 req/min per IP+UA on sign-in/callback/logout routes (in-process; add a reverse-proxy limiter for multi-node). Backchannel logout is limited to 30 req/min per IP
• Secure cookies: OIDC_FORCE_SECURE_COOKIES forces the Secure flag. Only enable this on HTTPS origins; on HTTP origins the browser rejects __Host- prefixed cookies and OIDC login will fail silently
• Backchannel logout: Receives signed logout_token POSTs from the IdP and invalidates the matching admin session

Client IP attribution and reverse proxies

The plugin logs client IPs for rate-limit buckets and audit logs. When Strapi runs behind a reverse proxy, enable Koa proxy mode so Strapi trusts X-Forwarded-For; otherwise all IPs will be the proxy's internal address.

In config/server.ts:

proxy: {
  koa: true,
},

Set OIDC_TRUSTED_IP_HEADER to the header your CDN or proxy uses to forward the real client IP. The header is only honoured when Koa proxy mode is enabled. Accepted values (all others are silently ignored):

| Header | Provider | | --------------------------- | ------------------------------------------------- | | cf-connecting-ip | Cloudflare | | true-client-ip | Cloudflare Enterprise, Akamai | | fastly-client-ip | Fastly | | fly-client-ip | Fly.io | | x-nf-client-connection-ip | Netlify | | x-real-ip | nginx (proxy_set_header X-Real-IP $remote_addr) |

Only headers that CDN/proxy vendors guarantee to strip from inbound client requests are accepted, preventing IP spoofing via forged headers.

Usage

Login

Navigate to /strapi-plugin-oidc/oidc to start the OIDC flow, or click the Login via SSO button injected into the Strapi login page.

Logout

RP-initiated logout

When the discovery document includes an end_session_endpoint, clicking logout redirects to the provider's end-session URL (RP-initiated logout). If the provider session has already expired, Strapi skips the redirect and goes straight to the login page.

The logout endpoint is POST /strapi-plugin-oidc/logout. Using POST instead of GET prevents CSRF-forced-logout attacks.

Backchannel logout

If your IdP supports OpenID Connect Back-Channel Logout, register https://<your-strapi>/strapi-plugin-oidc/backchannel-logout as the backchannel logout URL.

The endpoint accepts POST requests carrying a signed logout_token. The plugin verifies the token against the IdP JWKS and requires:

• a valid events claim containing http://schemas.openid.net/event/backchannel-logout
• no nonce claim
• a sub and/or sid claim that matches a Strapi admin user

When a match is found, the user's refresh tokens are invalidated. Invalid or unmatched tokens still receive HTTP 200 to avoid leaking information. The endpoint is rate-limited to 30 requests per minute per IP.

Admin Settings

Manage the plugin under Settings → OIDC Plugin.

Default Roles: Strapi admin role(s) assigned to new users on first login.

Whitelist: Restrict access to specific email addresses. When empty, any authenticated OIDC user gets an account. Supports:

• Individual emails with optional role overrides
• JSON import / export
• Bulk delete with confirmation

Audit Logs: Authentication events recorded and visible in the settings page. Filter by action, email, IP, and date. Download exports the current view as NDJSON. Set AUDIT_LOG_RETENTION_DAYS to 0 to disable. Records older than the configured value (default: 90 days) are purged daily. Admin routes require the plugin's read/update permissions.

Enforce OIDC Login: Removes email/password fields from the login page and blocks direct login API calls. Automatically disabled when the whitelist is empty to prevent lockout. The toggle is grayed out when OIDC_ENFORCE is set in config. Lockout recovery: set OIDC_ENFORCE: false in your plugin config and restart Strapi.

Skip Login Page: Redirects unauthenticated users straight to the OIDC provider without showing the Strapi login page. Toggle under Settings → Login Settings. The toggle is grayed out when OIDC_SKIP_LOGIN_PAGE is set in config. Set OIDC_SKIP_LOGIN_PAGE: false in your plugin config to disable and restart Strapi.

Group-to-Role Mapping

When your OIDC provider includes group membership in the userinfo response (e.g. a groups claim containing ["strapi-admins", "strapi-editors"]), you can automatically assign Strapi roles based on group membership.

| Setting | Default | Description | | --------------------- | ---------- | --------------------------------------------------------- | | OIDC_GROUP_FIELD | 'groups' | OIDC claim field that contains the group membership array | | OIDC_GROUP_ROLE_MAP | '{}' | JSON map of group names to Strapi role names |

Example configuration

module.exports = ({ env }) => ({
  'strapi-plugin-oidc': {
    enabled: true,
    config: {
      // ... other OIDC config ...
      OIDC_GROUP_FIELD: 'groups',
      OIDC_GROUP_ROLE_MAP: JSON.stringify({
        'strapi-admins': ['Super Admin'],
        'strapi-editors': ['Editor'],
        'strapi-authors': ['Editor', 'Author'],
      }),
    },
  },
});

Role names are the display names shown in Settings → Roles (e.g. "Editor", "Super Admin", "Author"). IDs are not supported, use names for clarity.

Role assignment precedence

1. OIDC groups match OIDC_GROUP_ROLE_MAP → mapped Strapi roles
2. No match or no mapping → default OIDC roles (new users only)

Role updates on subsequent logins

• New users: Roles assigned on first login (group-mapped or default).
• Existing users with group match: Roles updated to reflect current mapping.
• Existing users without group match: Roles left unchanged. Manually-assigned roles are never overwritten.

REST API

The whitelist and audit log can be managed programmatically with Strapi API tokens. See the REST API reference for endpoint details, required scopes, query parameters, and examples.

Credits

This plugin began as a fork of strapi-plugin-sso by yasudacloud. Since then, the OIDC implementation has been rewritten on top of openid-client, and the codebase has diverged significantly from the original. Huge thanks to yasudacloud for creating the original foundation of this plugin!

Donations

Feel free to donate if you'd like to support the development of this plugin.

License

MIT