OIDC Authentication

Overview

The Nacos OIDC authentication plugin provides OpenID Connect 1.0 / OAuth2 based authentication for the Nacos console, allowing Nacos to delegate user authentication and authorization to an external Identity Provider (IdP).

When the OIDC plugin is enabled, the Nacos console login page displays a “Sign in with SSO” button. Users click the button to be redirected to the IdP for authentication, and are automatically returned to the Nacos console upon successful login.

Use Cases

• Enterprise with an existing identity system (Keycloak, Okta, Auth0, Azure AD, etc.) that wants Nacos to use SSO
• Centralized user and permission management, avoiding separate account maintenance in Nacos
• Compliance with enterprise security requirements (MFA, audit logging, password policies)

Supported Identity Providers

Any OIDC 1.0 compliant IdP that exposes a /.well-known/openid-configuration discovery endpoint. Verified with:

• Keycloak (>= 18.0)
• Okta
• Auth0
• Azure AD / Microsoft Entra ID

Requirements

• Nacos: 3.2.0+
• JDK: 17+

1. Prerequisites

2. Set Up OIDC IdP (Keycloak Example)

Skip this section if you already have a working OIDC IdP.

2.1 Start Keycloak

docker run -d --name keycloak \
  -p 8081:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:24.0 \
  start-dev

Access http://localhost:8081 and log in with admin/admin.

2.2 Create a Realm

1. Click Create Realm in the top-left dropdown
2. Realm name: nacos
3. Click Create

2.3 Create a Client

1. Go to Clients → Create client
2. Step 1:
   • Client type: OpenID Connect
   • Client ID: nacos-server
   • Click Next
3. Step 2:
   • Client authentication: On
   • Authorization: Off
   • Check Standard flow
   • Click Next
4. Step 3:
   • Valid redirect URIs: http://localhost:8080/*
   • Web origins: http://localhost:8080
   • Click Save
5. Go to the Credentials tab and copy the Client secret

2.4 Create a Test User

1. Go to Users → Add user
2. Username: testuser, Email: test@example.com, Email verified: On
3. Click Create
4. Go to the Credentials tab
5. Click Set password, enter a password, set Temporary: Off

2.5 Record Key Information

Verify the discovery endpoint:

curl http://localhost:8081/realms/nacos/.well-known/openid-configuration

3. Configure application.properties

Edit <NACOS_HOME>/conf/application.properties.

3.1 Switch Auth System to OIDC

### Enable OIDC authentication
nacos.core.auth.system.type=oidc

### Enable authentication
nacos.core.auth.enabled=true

3.2 General Auth Configuration (Required)

These settings are still required even with OIDC enabled, as Nacos uses its own JWT for internal server-to-server communication.

### Server identity for inter-node communication (any non-empty string)
nacos.core.auth.server.identity.key=serverIdentity
nacos.core.auth.server.identity.value=security

### Internal JWT signing key (Base64 encoded, original string >= 32 chars)
nacos.core.auth.plugin.nacos.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg=

Important: If nacos.core.auth.plugin.nacos.token.secret.key is not set, the startup script will enter interactive mode prompting for input. Generate a key with openssl rand -base64 32.

3.3 OIDC Plugin Configuration (Required)

### IdP Issuer URI (for OIDC auto-discovery)
nacos.core.auth.plugin.oidc.issuer-uri=http://localhost:8081/realms/nacos

### OAuth2 Client credentials
nacos.core.auth.plugin.oidc.client-id=nacos-server
nacos.core.auth.plugin.oidc.client-secret=nacos-client-secret

### OAuth2 scopes
nacos.core.auth.plugin.oidc.scope=openid profile email

### Claim field for username extraction from ID Token
nacos.core.auth.plugin.oidc.username-claim=preferred_username

3.4 OIDC Optional Configuration

4. Start Nacos

cd <NACOS_HOME>
bin/startup.sh -m standalone   # Standalone mode
# or
bin/startup.sh                  # Cluster mode

Check logs:

tail -f logs/start.out

Success indicator: Nacos started successfully in logs.

5. Verify OIDC Login

5.1 Access the Console

Open http://localhost:8080/ in your browser. The login page should display a “Sign in with SSO” button with the username/password form hidden.

5.2 Click the SSO Button

Clicking the button redirects to the IdP login page. After authenticating at the IdP, you are automatically redirected back to the Nacos console.

5.3 Verify OIDC User Behavior

6. Login Flow

Browser              Nacos                    IdP (Keycloak)
   |                    |                            |
   | GET /              |                            |
   |------------------->|                            |
   | HTML + JS          |                            |
   |<-------------------|                            |
   | GET /v3/console/server/state                    |
   |------------------->|                            |
   | {auth_system_type: "oidc"}                      |
   |<-------------------|                            |
   | Render "Sign in with SSO" button                |
   | User clicks button |                            |
   | GET /v1/auth/oidc/login                         |
   |------------------->|                            |
   | 302 IdP authorize  |                            |
   |<-------------------|                            |
   | GET IdP authorize  |                            |
   |-------------------------------------------->    |
   | IdP login page     |                            |
   |<--------------------------------------------    |
   | User enters creds  |                            |
   |-------------------------------------------->    |
   | 302 callback?code= |                            |
   |<--------------------------------------------    |
   | GET /v1/auth/oidc/callback?code=...             |
   |------------------->|                            |
   |                    | POST token endpoint        |
   |                    |--------------------------->|
   |                    | {access_token, id_token}    |
   |                    |<---------------------------|
   |                    | JWKS signature validation   |
   |                    |--------------------------->|
   |                    |<---------------------------|
   | 302 / + Set-Cookie |                            |
   |<-------------------|                            |
   | JS reads cookies   |                            |
   | Syncs to localStorage                           |
   | Deletes cookies    |                            |
   | Enters console     |                            |

7. Troubleshooting

7.1 Startup hangs at “Please input the JWT token secret key”

Cause: nacos.core.auth.plugin.nacos.token.secret.key is not set.

Fix: Set a Base64-encoded key in application.properties:

nacos.core.auth.plugin.nacos.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg=

7.2 Startup fails: Empty identity

Cause: nacos.core.auth.server.identity.key/value are empty.

Fix:

nacos.core.auth.server.identity.key=serverIdentity
nacos.core.auth.server.identity.value=security

7.3 IdP reports redirect_uri error

Cause: The IdP client’s Valid Redirect URIs does not include the Nacos callback URL.

Fix: Add http://<nacos-host>:<port>/* to the IdP client configuration.

7.4 Callback returns “No valid OIDC token found”

Cause: JWT signature validation failed.

Steps:

1. Verify issuer-uri matches the IdP’s actual issuer (no trailing slash)
2. Check logs/nacos.log for detailed errors
3. Temporarily disable strict validation: strict-audience-validation=false
4. Verify the IdP’s JWKS endpoint is accessible

7.5 Auto-login after logout

This is standard OIDC SSO behavior. The IdP’s SSO session is still valid, so the IdP returns a logged-in state automatically. To force re-authentication, clear the IdP session at its logout endpoint.

8. Comparison with Other Auth Modes