Use an OAuth 2.0 Identity Provider

This document describes how to use an external identity provider based on the OAuth 2.0 protocol.

The following figure shows the authentication process between KubeSphere and an external OAuth 2.0 identity provider.

oauth2

Prerequisites

You need to deploy a Kubernetes cluster and install KubeSphere in the cluster. For details, see Installing on Linux and Installing on Kubernetes.

Develop an OAuth 2.0 Plugin

Note

KubeSphere provides two built-in OAuth 2.0 plugins: GitHubIdentityProvider for GitHub and AliyunIDaasProvider for Alibaba Cloud IDaaS. You can develop other plugins according to the built-in plugins.

  1. Clone the KubeSphere repository on your local machine, go to the local KubeSphere repository, and create a package for your plugin in the /pkg/apiserver/authentication/identityprovider/ directory.

  2. In the plugin package, implement the following interfaces:

    1. // /pkg/apiserver/authentication/identityprovider/oauth_provider.go
    2. type OAuthProvider interface {
    3.  // Exchange identity with a remote server.
    4.  IdentityExchange(code string) (Identity, error)
    5. }
    7. type OAuthProviderFactory interface {
    8.  // Return the identity provider type.
    9.  Type() string
    10.  // Apply settings from kubesphere-config.
    11.  Create(options oauth.DynamicOptions) (OAuthProvider, error)
    12. }
    1. // /pkg/apiserver/authentication/identityprovider/identity_provider.go
    2. type Identity interface {
    3.   // (Mandatory) Return the identifier of the user at the identity provider.
    4.  GetUserID() string
    5.   // (Optional) Return the name of the user to be referred as on KubeSphere.
    6.  GetUsername() string
    7.   // (Optional) Return the email address of the user.
    8.  GetEmail() string
    9. }

  3. Register the plugin in the init() function of the plugin package.

    1. // Custom plugin package
    2. func init() {
    3.   // Change <StructName> to the actual name of the struct that
    4.   // implements the OAuthProviderFactory interface.
    5.  identityprovider.RegisterOAuthProvider(&<StructName>{})
    6. }

  4. Import the plugin package in /pkg/apiserver/authentication/options/authenticate_options.go.

    1. // Change <CustomPackage> to the actual name of your plugin package.
    2. import (
    3.  ...
    4.  _ "kubesphere.io/kubesphere/pkg/apiserver/authentication/identityprovider/<CustomPackage>"
    5.  ...
    6.  )

  5. Build the image of ks-apiserver and deploy it in your cluster.

Integrate an Identity Provider with KubeSphere

  1. Log in to KubeSphere as admin, move the cursor to Use an OAuth 2.0 Identity Provider - 图2 in the bottom-right corner, click Kubectl, and run the following command to edit the kubesphere-config ConfigMap:

    1. kubectl -n kubesphere-system edit cm kubesphere-config

  2. Configure fields other than oauthOptions:identityProviders in the data:kubesphere.yaml:authentication section. For details, see Set Up External Authentication.

  3. Configure fields in oauthOptions:identityProviders section according to the identity provider plugin you have developed.

    The following is a configuration example that uses GitHub as an external identity provider. For details, see the official GitHub documentation and the source code of the GitHubIdentityProvider plugin.

    1. apiVersion: v1
    2. data:
    3.   kubesphere.yaml: |
    4.     authentication:
    5.       authenticateRateLimiterMaxTries: 10
    6.       authenticateRateLimiterDuration: 10m0s
    7.       loginHistoryRetentionPeriod: 7d
    8.       maximumClockSkew: 10s
    9.       multipleLogin: true
    10.       kubectlImage: kubesphere/kubectl:v1.0.0
    11.       jwtSecret: '********'
    12.       oauthOptions:
    13.         accessTokenMaxAge: 1h
    14.         accessTokenInactivityTimeout: 30m
    15.         identityProviders:
    16.         - name: GitHub
    17.           type: GitHubIdentityProvider
    18.           mappingMethod: auto
    19.           provider:
    20.             clientID: 'Iv1.547165ce1cf2f590'
    21.             clientSecret: '********'
    22.             redirectURL: 'https://ks-console/oauth/redirect'

    Similarly, you can also use Alibaba Cloud IDaaS as an external identity provider. For details, see the official Alibaba IDaaS documentation and the source code of the AliyunIDaasProvider plugin.

  4. After the kubesphere-config ConfigMap is modified, run the following command to restart ks-apiserver.

    1. kubectl -n kubesphere-system rollout restart deploy/ks-apiserver

    Note

    The KubeSphere web console is unavailable during the restart of ks-apiserver. Please wait until the restart is complete.

  5. Go to the KubeSphere login page, click Log In with XXX (for example, Log In with GitHub).

    github-login-page

  6. On the login page of the external identity provider, enter the username and password of a user configured at the identity provider to log in to KubeSphere.

    github-login-page