alibaba--nacos/specs/en/auth/oidc-auth-plugin-spec.md

OIDC Auth Plugin Spec

Scope

The OIDC auth plugin lets Nacos delegate authentication and authorization to an OpenID Connect 1.0 / OAuth2 identity provider. It implements the Auth Plugin Spec with auth service name oidc.

The server-side implementation lives in plugin-default-impl/nacos-oidc-auth-plugin. It was introduced to support standard identity providers for console SSO and token-based access. The Java client also contains OidcClientAuthServiceImpl, which obtains bearer tokens through the OAuth2 client credentials flow and injects them into SDK requests.

OIDC is not part of the default Nacos username/password auth plugin. It is an alternative auth mode selected by nacos.core.auth.system.type=oidc.

Server SPI

OidcAuthPluginService must:

Method	Contract
getAuthServiceName()	Return oidc.
identityNames()	Accept Authorization and accessToken.
enableAuth(action, type)	Enable auth for all actions and sign types.
validateIdentity(identityContext, resource)	Extract a bearer token or accessToken, validate it, map claims to an OIDC user, and store that user in IdentityContext.
validateAuthority(identityContext, permission)	Grant global administrators directly; otherwise delegate the permission decision to the configured authorization provider.
isLoginEnabled()	Return true; console login is handled by the OIDC login controller.
isAdminRequest()	Return false; the IdP owns user bootstrap and user management.

The plugin must not use Nacos local user, role, or permission management as the source of truth. Console user, role, permission, and password management surfaces should be hidden or disabled when OIDC is selected.

Required Configuration

OIDC mode is selected with:

nacos.core.auth.system.type=oidc
nacos.core.auth.enabled=true

Server-to-server identity and the default Nacos token secret can still be required by the runtime for internal communication and compatibility paths.

OIDC plugin configuration uses the nacos.core.auth.plugin.oidc. prefix:

Configuration	Default	Purpose
issuer-uri	empty	IdP issuer URI. The plugin uses it for OIDC discovery.
client-id	empty	OAuth2 client id registered in the IdP.
client-secret	empty	OAuth2 client secret. Also used by the current implementation for signed state.
scope	openid profile email	Scopes requested during browser login.
token-validation-method	jwt	Declared validation mode. Current server code validates JWTs through JWKS.
jwks-cache-ttl-seconds	3600	JWKS cache TTL.
username-claim	preferred_username	Claim used as the Nacos display username.
roles-claim	roles	Primary claim used to extract roles.
admin-role	nacos-admin	Role that maps to global administrator.
auto-create-user	true	Reserved for user mapping compatibility; OIDC remains the identity source of truth.
authorization-endpoint	empty	External endpoint used for non-admin authorization decisions.
authorization-timeout-ms	5000	Timeout for external authorization requests.
strict-nonce-validation	true	Reject authorization-code login when the ID token lacks or mismatches nonce.
strict-audience-validation	true	Reject tokens whose audience or authorized party does not match client-id.

issuer-uri and client-id are required for a valid server configuration. Browser login also requires client-secret, authorization endpoint discovery, and token endpoint discovery.

Browser Login Flow

The current implementation exposes browser-oriented endpoints under /v1/auth/oidc. These endpoints are implementation compatibility endpoints. Any new Nacos auth HTTP API should follow the v3 API rules in HTTP API Spec.

Endpoint	Purpose
/v1/auth/oidc/login	Redirect the browser to the IdP authorization endpoint.
/v1/auth/oidc/callback	Receive authorization code, validate state and nonce, exchange code for tokens, and return to the console.
/v1/auth/oidc/logout	Clear console-side auth state and optionally redirect to the IdP logout endpoint.
/v1/auth/oidc/config	Tell the console that OIDC mode is enabled and that local user/role/permission management is disabled.

The login flow must:

• Use OIDC discovery from {issuer-uri}/.well-known/openid-configuration.
• Generate a self-contained signed state value and a nonce.
• Exchange the authorization code at the IdP token endpoint.
• Validate the ID token signature and claims before accepting the user.
• Deliver short-lived console cookies only as a handoff mechanism for the frontend, then rely on normal request identity propagation.

Token Validation

The current implementation validates JWT tokens with JWKS. Validation must:

• Accept only supported asymmetric JWS algorithms.
• Require sub, iss, exp, and iat claims.
• Reject expired tokens and tokens that are not yet valid.
• Verify issuer, with trailing slash normalization.
• Verify audience or azp against client-id when strict audience validation is enabled.
• Refresh JWKS and retry once when signature verification fails, to tolerate key rotation.

Username mapping uses the configured username-claim, then falls back to common claims such as preferred_username, email, and finally sub. Role mapping uses the configured roles-claim, and may also read common Keycloak-style realm_access.roles, resource_access.{client-id}.roles, and groups claims. The configured admin-role maps to the Nacos global administrator concept.

Authorization

OIDC authentication identifies the caller. Authorization must still answer whether that caller may perform the requested Nacos action on the parsed resource.

The current implementation grants global administrators locally based on the mapped role. For non-admin users it calls the configured external authorization-endpoint with:

Field	Meaning
token	User access token.
resource	Nacos resource URI derived from Resource.
action	Nacos action, such as read or write.
resourceType, namespace, group, resourceName	Structured Nacos resource identity.

If authorization-endpoint is empty, the current implementation allows non-admin access. Deployments that need authorization isolation must configure an external authorization endpoint or provide a stricter OIDC authority provider.

Java Client Integration

OidcClientAuthServiceImpl is a Java Client SDK auth extension. It is separate from browser console SSO.

Client property	Purpose
nacos.client.auth.oidc.issuer-uri	OIDC issuer used for token endpoint discovery.
nacos.client.auth.oidc.client-id	OAuth2 client id.
nacos.client.auth.oidc.client-secret	OAuth2 client secret.
nacos.client.auth.oidc.scope	OAuth2 scopes, default openid.
nacos.client.auth.oidc.token-endpoint	Direct token endpoint override; skips discovery.

When configured, the client uses the OAuth2 client credentials grant, refreshes tokens before expiration, and injects both Authorization: Bearer ... and accessToken. When not configured, it must return an empty identity context and must not fail unrelated SDK calls.

Pending Issues

• The configuration model declares token-validation-method=introspection, but the current server validation path is JWT/JWKS-based. Introspection must not be documented as supported until an implementation exists.
• OIDC browser endpoints currently use /v1/auth/oidc. Any future Nacos-native auth APIs should use /v3/auth/oidc/* and the standard response/error model.
• Documentation and code must stay aligned on default values for strict nonce and audience validation.

Relationships

• General auth SPI rules: Auth Plugin Spec.
• Java client auth extension rules: Java SDK Implementation Spec.
• Default username/password auth: Default Auth Plugin Implementation Spec.