KubeSphere supports external authentication via OpenID Connect (OIDC), allowing users to log in to the KubeSphere web console using OIDC usernames and passwords.

Platform administrators can configure OIDC authentication through a Secret.

Steps

  1. Log in to the KubeSphere web console with a user who has the platform-admin role.

  2. Click Cluster Management and enter the host cluster.

  3. Click Configuration > Secrets in the left navigation pane.

  4. Click Create on the page.

  5. In the Create Secret dialog, click the Edit YAML toggle in the upper right corner to create the secret using YAML.

  6. Modify the YAML file according to the example and parameter descriptions below. After configuration, click Create.

  7. Log out of the KubeSphere web console. On the login page, click Log in via OIDC, and enter your OpenID Connect username and password to log in.

Note

In a multi-cluster environment, configuration is only required in the host cluster.

OIDC Basic Configuration

apiVersion: v1
kind: Secret
metadata:
  namespace: kubesphere-system  # Do not modify
  name: identity-provider-oidc  # Ensure this Secret name is unique within the Kubernetes cluster
  labels:
    config.kubesphere.io/type: identityprovider # Do not modify
    config.kubesphere.io/identityprovider: oidc # Must match the name field in configuration.yaml
type: config.kubesphere.io/identityprovider # Do not modify

stringData:
  configuration.yaml: |
    name: oidc
    type: OIDCIdentityProvider
    mappingMethod: auto
    hidden: false
    disabled: false
    provider:
        # Use auto-discovery
        issuer: https://accounts.google.com
        clientID: "your-client-id"
        clientSecret: "your-client-secret"
        redirectURL: "https://your-app.com/oauth/callback"

OIDC Full Configuration

The following only shows the configuration of the provider section under stringData:configuration.yaml. Other parts should remain the same as the corresponding parts in the OIDC Basic Configuration.

    provider:
        # Basic configuration
        issuer: https://accounts.google.com
        clientID: "your-client-id"
        clientSecret: "your-client-secret"
        redirectURL: "https://your-app.com/oauth/callback"

        # Optional configuration
        scopes:
            - "openid"
            - "email"
            - "profile"
        getUserInfo: true
        insecureSkipVerify: false

        # Custom claims configuration
        emailKey: "email"
        preferredUsernameKey: "preferred_username"
        displayNameKey: "name"

        # Manual endpoint configuration (endpoint-related configurations are required when issuer is not used)
        endpoint:
            authURL: "https://accounts.google.com/o/oauth2/v2/auth"
            tokenURL: "https://oauth2.googleapis.com/token"
            userInfoURL: "https://openidconnect.googleapis.com/v1/userinfo"
            jwksURL: "https://www.googleapis.com/oauth2/v3/certs"
            endSessionURL: "https://accounts.google.com/logout"

OIDC Parameter Description

This is the parameter description for the provider section under stringData:configuration.yaml. For parameter descriptions of other parts in the Secret, please refer to Configure External Authentication.

Parameter Type Required Default Value Description

issuer

string

No

-

The issuer URL of the OpenID Provider, used for dynamic discovery configuration

clientID

string

Yes

-

OAuth2 client ID

clientSecret

string

Yes

-

OAuth2 client secret

redirectURL

string

Yes

-

OAuth2 callback address

scopes

[]string

No

["openid"]

Requested scopes. Default includes "openid"

getUserInfo

bool

No

false

Whether to use the userinfo endpoint to obtain additional user information

insecureSkipVerify

bool

No

false

Whether to skip TLS certificate verification

endpoint.authURL

string

No

-

OAuth2 authorization endpoint URL

endpoint.tokenURL

string

No

-

OAuth2 token endpoint URL

endpoint.userInfoURL

string

No

-

OpenID UserInfo endpoint URL

endpoint.jwksURL

string

No

-

JSON Web Key Set URL

endpoint.endSessionURL

string

No

-

End session endpoint URL

emailKey

string

No

"email"

Custom claim key name for email information

preferredUsernameKey

string

No

"preferred_username"

Custom claim key name for username information

displayNameKey

string

No

-

Custom claim key name for display name