diff --git a/content/en/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md b/content/en/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md index 44a98170d..b6382a1b7 100644 --- a/content/en/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md +++ b/content/en/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md @@ -1,9 +1,9 @@ --- -title: "OIDC identity provider" +title: "OIDC Identity Provider" keywords: "OIDC, identity provider" description: "How to use an external OIDC identity provider." -linkTitle: "OIDC identity provider" +linkTitle: "OIDC Identity Provider" weight: 12221 --- @@ -11,44 +11,52 @@ weight: 12221 [OpenID Connect](https://openid.net/connect/) is an interoperable authentication protocol based on the OAuth 2.0 family of specifications. It uses straightforward REST/JSON message flows with a design goal of “making simple things simple and complicated things possible”. It’s uniquely easy for developers to integrate, compared to any preceding Identity protocol, such as Keycloak, Okta, Dex, Auth0, Gluu, and many more. +## Prerequisites +You need to deploy a Kubernetes cluster and install KubeSphere in the cluster. For details, see [Installing on Linux](/docs/installing-on-linux/) and [Installing on Kubernetes](/docs/installing-on-kubernetes/). -*Example of using [Google Identity Platform](https://developers.google.com/identity/protocols/oauth2/openid-connect)*: +## Procedure -```yaml -apiVersion: v1 -data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - jwtSecret: "********" - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: google - type: OIDCIdentityProvider - mappingMethod: auto - provider: - clientID: '********' - clientSecret: '********' - issuer: https://accounts.google.com - redirectURL: 'https://ks-console/oauth/redirect/google' -kind: ConfigMap -name: kubesphere-config -namespace: kubesphere-system -``` +1. Log in to KubeSphere as `admin`, move the cursor to in the lower-right corner, click **kubectl**, and run the following command to edit `ks-installer` of the CRD `ClusterConfiguration`: -For the above example: + ```bash + kubectl -n kubesphere-system edit cc ks-installer + ``` + +2. Add the following fields under `spec.authentication.jwtSecret`. + + *Example of using [Google Identity Platform](https://developers.google.com/identity/protocols/oauth2/openid-connect)*: + + ```yaml + spec: + authentication: + jwtSecret: '' + authenticateRateLimiterMaxTries: 10 + authenticateRateLimiterDuration: 10m0s + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: google + type: OIDCIdentityProvider + mappingMethod: auto + provider: + clientID: '********' + clientSecret: '********' + issuer: https://accounts.google.com + redirectURL: 'https://ks-console/oauth/redirect/google' + ``` + + See description of parameters as below: + + | Parameter | Description | + | -------------------- | ------------------------------------------------------------ | + | clientID | The OAuth2 client ID. | + | clientSecret | The OAuth2 client secret. | + | redirectURL | The redirected URL to ks-console in the following format: `https:///oauth/redirect/`. The `` in the URL corresponds to the value of `oauthOptions:identityProviders:name`. | + | issuer | Defines how Clients dynamically discover information about OpenID Providers. | + | preferredUsernameKey | Configurable key which contains the preferred username claims. This parameter is optional. | + | emailKey | Configurable key which contains the email claims. This parameter is optional. | + | getUserInfo | GetUserInfo uses the userinfo endpoint to get additional claims for the token. This is especially useful where upstreams return "thin" ID tokens. This parameter is optional. | + | insecureSkipVerify | Used to turn off TLS certificate verification. | -| Parameter | Description | -| ----------| ----------- | -| clientID | The OAuth2 client ID. | -| clientSecret | The OAuth2 client secret. | -| redirectURL | The redirected URL to ks-console. | -| issuer | Defines how Clients dynamically discover information about OpenID Providers. | -| preferredUsernameKey | Configurable key which contains the preferred username claims. | -| emailKey | Configurable key which contains the email claims. | -| getUserInfo | GetUserInfo uses the userinfo endpoint to get additional claims for the token. This is especially useful where upstreams return "thin" id tokens. | -| insecureSkipVerify | Used to turn off TLS certificate verify. | \ No newline at end of file diff --git a/content/en/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md b/content/en/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md index 4a7933c63..f95aaec38 100644 --- a/content/en/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md +++ b/content/en/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md @@ -9,7 +9,7 @@ weight: 12210 This document describes how to use an external identity provider such as an LDAP service or Active Directory service on KubeSphere. -KubeSphere provides a built-in OAuth server. Users can obtain OAuth access tokens to authenticate themselves to the KubeSphere API. As a KubeSphere administrator, you can edit the `kubesphere-config` ConfigMap to configure OAuth and specify identity providers. +KubeSphere provides a built-in OAuth server. Users can obtain OAuth access tokens to authenticate themselves to the KubeSphere API. As a KubeSphere administrator, you can edit `ks-installer` of the CRD `ClusterConfiguration` to configure OAuth and specify identity providers. ## Prerequisites @@ -18,57 +18,49 @@ You need to deploy a Kubernetes cluster and install KubeSphere in the cluster. F ## Procedure -1. Log in to KubeSphere as `admin`, move the cursor to in the lower-right corner, click **Kubectl**, and run the following command to edit the `kubesphere-config` ConfigMap: +1. Log in to KubeSphere as `admin`, move the cursor to in the lower-right corner, click **kubectl**, and run the following command to edit `ks-installer` of the CRD `ClusterConfiguration`: ```bash - kubectl -n kubesphere-system edit cm kubesphere-config + kubectl -n kubesphere-system edit cc ks-installer ``` -2. Configure fields in the `data:kubesphere.yaml:authentication` section. +2. Add the following fields under `spec.authentication.jwtSecret`. Example: ```yaml - apiVersion: v1 - data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - loginHistoryRetentionPeriod: 168h - maximumClockSkew: 10s - multipleLogin: true - jwtSecret: "********" - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: ldap - type: LDAPIdentityProvider - mappingMethod: auto - provider: - host: 192.168.0.2:389 - managerDN: uid=root,cn=users,dc=nas - managerPassword: ******** - userSearchBase: cn=users,dc=nas - loginAttribute: uid - mailAttribute: mail + spec: + authentication: + jwtSecret: '' + authenticateRateLimiterMaxTries: 10 + authenticateRateLimiterDuration: 10m0s + loginHistoryRetentionPeriod: 168h + maximumClockSkew: 10s + multipleLogin: true + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: LDAP + type: LDAPIdentityProvider + mappingMethod: auto + provider: + host: 192.168.0.2:389 + managerDN: uid=root,cn=users,dc=nas + managerPassword: ******** + userSearchBase: cn=users,dc=nas + loginAttribute: uid + mailAttribute: mail ``` - + The fields are described as follows: - * `authenticateRateLimiterMaxTries`: Maximum number of consecutive login failures allowed during a period specified by `authenticateRateLimiterDuration`. If the number of consecutive login failures of a user reaches the limit, the user will be blocked. - - * `authenticateRateLimiterDuration`: Period during which `authenticateRateLimiterMaxTries` applies. - - * `loginHistoryRetentionPeriod`: Retention period of login records. Outdated login records are automatically deleted. - - * `maximumClockSkew`: Maximum clock skew for time-sensitive operations such as token expiration validation. The default value is `10s`. - - * `multipleLogin`: Whether multiple users are allowed to log in from different locations. The default value is `true`. - * `jwtSecret`: Secret used to sign user tokens. In a multi-cluster environment, all clusters must [use the same Secret](../../../multicluster-management/enable-multicluster/direct-connection/#prepare-a-member-cluster). - + * `authenticateRateLimiterMaxTries`: Maximum number of consecutive login failures allowed during a period specified by `authenticateRateLimiterDuration`. If the number of consecutive login failures of a user reaches the limit, the user will be blocked. + * `authenticateRateLimiterDuration`: Period during which `authenticateRateLimiterMaxTries` applies. + * `loginHistoryRetentionPeriod`: Retention period of login records. Outdated login records are automatically deleted. + * `maximumClockSkew`: Maximum clock skew for time-sensitive operations such as token expiration validation. The default value is `10s`. + * `multipleLogin`: Whether multiple users are allowed to log in from different locations. The default value is `true`. * `oauthOptions`: OAuth settings. * `accessTokenMaxAge`: Access token lifetime. For member clusters in a multi-cluster environment, the default value is `0h`, which means access tokens never expire. For other clusters, the default value is `2h`. * `accessTokenInactivityTimeout`: Access token inactivity timeout period. An access token becomes invalid after it is idle for a period specified by this field. After an access token times out, the user needs to obtain a new access token to regain access. @@ -79,7 +71,7 @@ You need to deploy a Kubernetes cluster and install KubeSphere in the cluster. F * If the value is `auto` (default), you need to specify a new username. KubeSphere automatically creates a user according to the username and maps the user to a third-party account. * If the value is `lookup`, you need to perform step 3 to manually map an existing KubeSphere user to a third-party account. * `provider`: Identity provider information. Fields in this section vary according to the identity provider type. - + 3. If `mappingMethod` is set to `lookup`, run the following command and add the labels to map a KubeSphere user to a third-party account. Skip this step if `mappingMethod` is set to `auto`. ```bash @@ -92,17 +84,13 @@ You need to deploy a Kubernetes cluster and install KubeSphere in the cluster. F iam.kubesphere.io/origin-uid: ``` -4. After the fields are configured, run the following command to restart ks-apiserver. +4. After the fields are configured, save your changes, and wait until the restart of ks-installer is complete. - ```bash - kubectl -n kubesphere-system rollout restart deploy/ks-apiserver - ``` - -{{< notice note >}} - -In a multi-cluster environment, you only need to configure the Host Cluster. - -{{}} + {{< notice note >}} + + In a multi-cluster environment, you only need to configure the host cluster. + + {{}} ## Identity provider @@ -111,14 +99,14 @@ You can configure multiple identity providers (IdPs) in the 'identityProviders' Kubesphere provides the following types of identity providers by default: -* [LDAPIdentityProvider](../use-an-ldap-service) +* [LDAP Identity Provider](../use-an-ldap-service) -* [OIDCIdentityProvider](../oidc-identity-provider) +* [OIDC Identity Provider](../oidc-identity-provider) -* [GitHubIdentityProvider]() +* [GitHub Identity Provider]() -* [CASIdentityProvider]() +* [CAS Identity Provider]() -* [AliyunIDaaSProvider]() +* [Aliyun IDaaS Provider]() You can also expand the kubesphere [OAuth2 authentication plug-in](../use-an-oauth2-identity-provider) to integrate with your account system. diff --git a/content/en/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md b/content/en/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md index a603846aa..571c153e0 100644 --- a/content/en/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md +++ b/content/en/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md @@ -16,42 +16,37 @@ This document describes how to use an LDAP service as an external identity provi ## Procedure -1. Log in to KubeSphere as `admin`, move the cursor to in the lower-right corner, click **Kubectl**, and run the following command to edit the `kubesphere-config` ConfigMap: +1. Log in to KubeSphere as `admin`, move the cursor to in the lower-right corner, click **kubectl**, and run the following command to edit `ks-installer` of the CRD `ClusterConfiguration`: ```bash - kubectl -n kubesphere-system edit cm kubesphere-config + kubectl -n kubesphere-system edit cc ks-installer ``` Example: ```yaml - apiVersion: v1 - data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - loginHistoryRetentionPeriod: 168h - maximumClockSkew: 10s - multipleLogin: true - jwtSecret: "********" - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: LDAP - type: LDAPIdentityProvider - mappingMethod: auto - provider: - host: 192.168.0.2:389 - managerDN: uid=root,cn=users,dc=nas - managerPassword: ******** - userSearchBase: cn=users,dc=nas - loginAttribute: uid - mailAttribute: mail + spec: + authentication: + jwtSecret: '' + maximumClockSkew: 10s + multipleLogin: true + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: LDAP + type: LDAPIdentityProvider + mappingMethod: auto + provider: + host: 192.168.0.2:389 + managerDN: uid=root,cn=users,dc=nas + managerPassword: ******** + userSearchBase: cn=users,dc=nas + loginAttribute: uid + mailAttribute: mail ``` - -2. Configure fields other than `oauthOptions:identityProviders` in the `data:kubesphere.yaml:authentication` section. For details, see [Set Up External Authentication](../set-up-external-authentication/). + +2. Configure fields other than `oauthOptions:identityProviders` in the `spec:authentication` section. For details, see [Set Up External Authentication](../set-up-external-authentication/). 3. Configure fields in `oauthOptions:identityProviders` section. @@ -80,15 +75,23 @@ This document describes how to use an LDAP service as an external identity provi iam.kubesphere.io/origin-uid: ``` -5. After the fields are configured, run the following command to restart ks-apiserver. +5. After the fields are configured, save your changes, and wait until the restart of ks-installer is complete. + + {{< notice note >}} + + The KubeSphere web console is unavailable during the restart of ks-installer. Please wait until the restart is complete. + + {{}} + +5. If you are using KubeSphere 3.2.0, run the following command after configuring LDAP and wait until `ks-installer` is up and running: ```bash - kubectl -n kubesphere-system rollout restart deploy/ks-apiserver + kubectl -n kubesphere-system set image deployment/ks-apiserver *=kubespheredev/ks-apiserver:release-3.2 ``` {{< notice note >}} - The KubeSphere web console is unavailable during the restart of ks-apiserver. Please wait until the restart is complete. + This is not required in the next release. {{}} diff --git a/content/en/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md b/content/en/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md index c3de00e8e..0ea1f959d 100644 --- a/content/en/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md +++ b/content/en/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md @@ -81,50 +81,44 @@ KubeSphere provides two built-in OAuth 2.0 plugins: [GitHubIdentityProvider](htt ## Integrate an Identity Provider with KubeSphere -1. Log in to KubeSphere as `admin`, move the cursor to in the lower-right corner, click **Kubectl**, and run the following command to edit the `kubesphere-config` ConfigMap: +1. Log in to KubeSphere as `admin`, move the cursor to in the lower-right corner, click **kubectl**, and run the following command to edit `ks-installer` of the CRD `ClusterConfiguration`: ```bash - kubectl -n kubesphere-system edit cm kubesphere-config + kubectl -n kubesphere-system edit cc ks-installer ``` -2. Configure fields other than `oauthOptions:identityProviders` in the `data:kubesphere.yaml:authentication` section. For details, see [Set Up External Authentication](../set-up-external-authentication/). +2. Configure fields other than `oauthOptions:identityProviders` in the `spec:authentication` section. For details, see [Set Up External Authentication](../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](https://docs.github.com/en/developers/apps/building-oauth-apps) and the [source code of the GitHubIdentityProvider](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) plugin. ```yaml - apiVersion: v1 - data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - jwtSecret: '******' - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: github - type: GitHubIdentityProvider - mappingMethod: auto - provider: - clientID: '******' - clientSecret: '******' - redirectURL: 'https://ks-console/oauth/redirect/github' + spec: + authentication: + jwtSecret: '' + authenticateRateLimiterMaxTries: 10 + authenticateRateLimiterDuration: 10m0s + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: github + type: GitHubIdentityProvider + mappingMethod: auto + provider: + clientID: '******' + clientSecret: '******' + redirectURL: 'https://ks-console/oauth/redirect/github' ``` - + Similarly, you can also use Alibaba Cloud IDaaS as an external identity provider. For details, see the official [Alibaba IDaaS documentation](https://www.alibabacloud.com/help/product/111120.htm?spm=a3c0i.14898238.2766395700.1.62081da1NlxYV0) and the [source code of the AliyunIDaasProvider](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) plugin. -4. After the `kubesphere-config` ConfigMap is modified, run the following command to restart ks-apiserver. - - ```bash - kubectl -n kubesphere-system rollout restart deploy/ks-apiserver - ``` +4. After the fields are configured, save your changes, and wait until the restart of ks-installer is complete. {{< notice note >}} - - The KubeSphere web console is unavailable during the restart of ks-apiserver. Please wait until the restart is complete. + + The KubeSphere web console is unavailable during the restart of ks-installer. Please wait until the restart is complete. {{}} diff --git a/content/zh/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md b/content/zh/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md index 493099f94..1280c9e40 100644 --- a/content/zh/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md +++ b/content/zh/docs/access-control-and-account-management/external-authentication/oidc-identity-provider.md @@ -1,54 +1,64 @@ --- -title: "OIDC身份提供者" +title: "OIDC 身份提供者" keywords: "OIDC, 身份提供者" description: "如何使用外部 OIDC 身份提供者。" -linkTitle: "OIDC身份提供者" +linkTitle: "OIDC 身份提供者" weight: 12221 --- ## OIDC 身份提供者 -[OpenID Connect](https://openid.net/connect/) 是一种基于 OAuth 2.0 系列规范的可互操作的身份认证协议。使用简单的 REST/JSON 消息流，其设计目标是 “让简单的事情变得简单，让复杂的事情成为可能” 。与之前的任何身份认证协议（例如 Keycloak、Okta、Dex、Auth0、Gluu 等）相比，开发人员集成起来非常容易。 +[OpenID Connect](https://openid.net/connect/) 是一种基于 OAuth 2.0 系列规范的可互操作的身份认证协议。使用简单的 REST/JSON 消息流，其设计目标是“让简单的事情变得简单，让复杂的事情成为可能”。与之前的任何身份认证协议（例如 Keycloak、Okta、Dex、Auth0、Gluu 等）相比，开发人员集成起来非常容易。 + +## 准备工作 + +您需要部署一个 Kubernetes 集群，并在集群中安装 KubeSphere。有关详细信息，请参阅[在 Linux 上安装](../../../installing-on-linux/)和[在 Kubernetes 上安装](../../../installing-on-kubernetes/)。 + +## 步骤 + +1. 以 `admin` 身份登录 KubeSphere，将光标移动到右下角 ，点击 **kubectl**，然后执行以下命令来编辑 CRD `ClusterConfiguration` 中的 `ks-installer`： + + ```bash + kubectl -n kubesphere-system edit cc ks-installer + ``` + +2. 在 `spec.authentication.jwtSecret` 字段下添加以下字段。 + + *使用 [Google Identity Platform](https://developers.google.com/identity/protocols/oauth2/openid-connect) 的示例*： + + ```yaml + spec: + authentication: + jwtSecret: '' + authenticateRateLimiterMaxTries: 10 + authenticateRateLimiterDuration: 10m0s + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: google + type: OIDCIdentityProvider + mappingMethod: auto + provider: + clientID: '********' + clientSecret: '********' + issuer: https://accounts.google.com + redirectURL: 'https://ks-console/oauth/redirect/google' + ``` + + 字段描述如下： + + | 参数 | 描述 | + | -------------------- | ------------------------------------------------------------ | + | clientID | 客户端 ID。 | + | clientSecret | 客户端密码。 | + | redirectURL | 重定向到 ks-console 的 URL，格式为：`https://<域名>/oauth/redirect/<身份提供者名称>`。URL 中的 `<身份提供者名称>` 对应 `oauthOptions:identityProviders:name` 的值。 | + | issuer | 定义客户端如何动态发现有关 OpenID 提供者的信息。 | + | preferredUsernameKey | 可配置的密钥，包含首选用户声明。此参数为可选参数。 | + | emailKey | 可配置的密钥，包含电子邮件声明。此参数为可选参数。 | + | getUserInfo | 使用 userinfo 端点获取令牌的附加声明。非常适用于上游返回 “thin” ID 令牌的场景。此参数为可选参数。 | + | insecureSkipVerify | 关闭 TLS 证书验证。 | -*使用 [Google Identity Platform](https://developers.google.com/identity/protocols/oauth2/openid-connect) 的示例*： - -```yaml -apiVersion: v1 -data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - jwtSecret: "********" - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: google - type: OIDCIdentityProvider - mappingMethod: auto - provider: - clientID: '********' - clientSecret: '********' - issuer: https://accounts.google.com - redirectURL: 'https://ks-console/oauth/redirect/google' -kind: ConfigMap -name: kubesphere-config -namespace: kubesphere-system -``` - -字段描述如下： - -| 参数 | 描述 | -| ----------| ----------- | -| clientID | 客户端 ID。 | -| clientSecret | 客户端密码。 | -| redirectURL | 重定向到 ks-console 的 URL。 | -| issuer | 定义客户端如何动态发现有关 OpenID 提供者的信息。 | -| preferredUsernameKey | 可配置的密钥，包含首选用户声明。 | -| emailKey | 可配置的密钥，包含电子邮件声明。 | -| getUserInfo | 使用 userinfo 端点获取令牌的附加声明。非常适用于上游返回 “thin” id令牌的场景。 | -| insecureSkipVerify | 关闭 TLS 证书验证。 | \ No newline at end of file diff --git a/content/zh/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md b/content/zh/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md index b1d75deb1..4c8a8fd53 100644 --- a/content/zh/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md +++ b/content/zh/docs/access-control-and-account-management/external-authentication/set-up-external-authentication.md @@ -9,7 +9,7 @@ weight: 12210 本文档描述了如何在 KubeSphere 上使用外部身份提供者，例如 LDAP 服务或 Active Directory 服务。 -KubeSphere 提供了一个内置的 OAuth 服务。用户通过获取 OAuth 访问令牌以对 API 进行身份验证。作为 KubeSphere 管理员，您可以编辑 `kubesphere-config` 来配置 OAuth 并指定身份提供者。 +KubeSphere 提供了一个内置的 OAuth 服务。用户通过获取 OAuth 访问令牌以对 API 进行身份验证。作为 KubeSphere 管理员，您可以编辑 CRD `ClusterConfiguration` 中的 `ks-installer` 来配置 OAuth 并指定身份提供者。 ## 准备工作 @@ -18,68 +18,60 @@ KubeSphere 提供了一个内置的 OAuth 服务。用户通过获取 OAuth 访 ## 步骤 -1. 以 `admin` 身份登录 KubeSphere，将光标移动到右下角 ，点击 **Kubectl**，然后运行以下命令来编辑 `kubesphere-config`： +1. 以 `admin` 身份登录 KubeSphere，将光标移动到右下角 ，点击 **kubectl**，然后执行以下命令来编辑 CRD `ClusterConfiguration` 中的 `ks-installer`： ```bash - kubectl -n kubesphere-system edit cm kubesphere-config + kubectl -n kubesphere-system edit cc ks-installer ``` -2. 在 `data:kubesphere.yaml:authentication` 部分配置字段 +2. 在 `spec.authentication.jwtSecret` 字段下添加以下字段。 示例: ```yaml - apiVersion: v1 - data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - loginHistoryRetentionPeriod: 168h - maximumClockSkew: 10s - multipleLogin: true - jwtSecret: "********" - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: ldap - type: LDAPIdentityProvider - mappingMethod: auto - provider: - host: 192.168.0.2:389 - managerDN: uid=root,cn=users,dc=nas - managerPassword: ******** - userSearchBase: cn=users,dc=nas - loginAttribute: uid - mailAttribute: mail + spec: + authentication: + jwtSecret: '' + authenticateRateLimiterMaxTries: 10 + authenticateRateLimiterDuration: 10m0s + loginHistoryRetentionPeriod: 168h + maximumClockSkew: 10s + multipleLogin: true + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: LDAP + type: LDAPIdentityProvider + mappingMethod: auto + provider: + host: 192.168.0.2:389 + managerDN: uid=root,cn=users,dc=nas + managerPassword: ******** + userSearchBase: cn=users,dc=nas + loginAttribute: uid + mailAttribute: mail ``` - + 字段描述如下： - - * `authenticateRateLimiterMaxTries`: `authenticateLimiterDuration` 指定的期间内允许的最大连续登录失败次数。如果用户连续登录失败次数达到限制，则该用户将被封禁。 - - * `authenticateRateLimiterDuration`: `authenticateRateLimiterMaxTries` 适用的时间段。 - - * `loginHistoryRetentionPeriod`: 用户登录记录保留期限，过期的登录记录将被自动删除。 - - * `maximumClockSkew`: 时间敏感操作（例如验证用户令牌的过期时间）的最大时钟偏差，默认值为10秒。 - - * `multipleLogin`: 是否允许多个用户同时从不同位置登录，默认值为 `true`。 - - * `jwtSecret`: 签发用户令牌的密钥。在多集群环境下，所有的集群必须[使用相同的密钥](../../../multicluster-management/enable-multicluster/direct-connection/#prepare-a-member-cluster)。 - - * `oauthOptions`: - * `accessTokenMaxAge`: 访问令牌有效期。对于多集群环境中的成员集群，默认值为 `0h`，这意味着访问令牌永不过期。对于其他集群，默认值为 `2h`。 - * `accessTokenInactivityTimeout`: 令牌空闲超时时间。该值表示令牌过期后，刷新用户令牌最大的间隔时间，如果不在此时间窗口内刷新用户身份令牌，用户将需要重新登录以获得访问权。 - * `identityProviders`: - * `name`: 身份提供者的名称。 - * `type`: 身份提供者的类型。 - * `mappingMethod`: 帐户映射方式，值可以是 `auto` 或者 `lookup`。 + + * `jwtSecret`：签发用户令牌的密钥。在多集群环境下，所有的集群必须[使用相同的密钥](../../../multicluster-management/enable-multicluster/direct-connection/#prepare-a-member-cluster)。 + * `authenticateRateLimiterMaxTries`：`authenticateLimiterDuration` 指定的期间内允许的最大连续登录失败次数。如果用户连续登录失败次数达到限制，则该用户将被封禁。 + * `authenticateRateLimiterDuration`：`authenticateRateLimiterMaxTries` 适用的时间段。 + * `loginHistoryRetentionPeriod`：用户登录记录保留期限，过期的登录记录将被自动删除。 + * `maximumClockSkew`：时间敏感操作（例如验证用户令牌的过期时间）的最大时钟偏差，默认值为10秒。 + * `multipleLogin`：是否允许多个用户同时从不同位置登录，默认值为 `true`。 + * `oauthOptions`： + * `accessTokenMaxAge`：访问令牌有效期。对于多集群环境中的成员集群，默认值为 `0h`，这意味着访问令牌永不过期。对于其他集群，默认值为 `2h`。 + * `accessTokenInactivityTimeout`：令牌空闲超时时间。该值表示令牌过期后，刷新用户令牌最大的间隔时间，如果不在此时间窗口内刷新用户身份令牌，用户将需要重新登录以获得访问权。 + * `identityProviders`： + * `name`：身份提供者的名称。 + * `type`：身份提供者的类型。 + * `mappingMethod`：帐户映射方式，值可以是 `auto` 或者 `lookup`。 * 如果值为 `auto`（默认），需要指定新的用户名。通过第三方帐户登录时，KubeSphere 会根据用户名自动创建关联帐户。 * 如果值为 `lookup`，需要执行步骤 3 以手动关联第三方帐户与 KubeSphere 帐户。 - * `provider`: 身份提供者信息。此部分中的字段根据身份提供者的类型而异。 - + * `provider`：身份提供者信息。此部分中的字段根据身份提供者的类型而异。 + 3. 如果 `mappingMethod` 设置为 `lookup`，可以运行以下命令并添加标签来进行帐户关联。如果 `mappingMethod` 是 `auto` 可以跳过这个部分。 ```bash @@ -90,19 +82,15 @@ KubeSphere 提供了一个内置的 OAuth 服务。用户通过获取 OAuth 访 labels: iam.kubesphere.io/identify-provider: iam.kubesphere.io/origin-uid: - ``` + ``` -4. 字段配置完成后，执行以下命令重启 ks-apiserver 。 +4. 字段配置完成后，保存修改，然后等待 ks-installer 重启完成。 - ```bash - kubectl -n kubesphere-system rollout restart deploy/ks-apiserver - ``` - -{{< notice note >}} - -多集群环境中，只需要在 Host 集群中进行配置。 - -{{}} + {{< notice note >}} + + 多集群环境中，只需要在主集群中进行配置。 + + {{}} ## 身份提供者 @@ -111,14 +99,14 @@ KubeSphere 提供了一个内置的 OAuth 服务。用户通过获取 OAuth 访 KubeSphere 默认提供了以下几种类型的身份提供者： -* [LDAPIdentityProvider](../use-an-ldap-service) +* [LDAP Identity Provider](../use-an-ldap-service) -* [OIDCIdentityProvider](../oidc-identity-provider) +* [OIDC Identity Provider](../oidc-identity-provider) -* [GitHubIdentityProvider]() +* [GitHub Identity Provider]() -* [CASIdentityProvider]() +* [CAS Identity Provider]() -* [AliyunIDaaSProvider]() +* [Aliyun IDaaS Provider]() 您也可以拓展 KubeSphere [OAuth2 认证插件](../use-an-oauth2-identity-provider) 与您的帐户系统进行集成。 diff --git a/content/zh/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md b/content/zh/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md index 6c24eb2b5..60909e928 100644 --- a/content/zh/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md +++ b/content/zh/docs/access-control-and-account-management/external-authentication/use-an-ldap-service.md @@ -16,42 +16,37 @@ weight: 12220 ## 步骤 -1. 以 `admin` 身份登录 KubeSphere，将光标移动到右下角 ，点击 **Kubectl**，然后运行以下命令来编辑 `kubesphere-config`： +1. 以 `admin` 身份登录 KubeSphere，将光标移动到右下角 ，点击 **kubectl**，然后执行以下命令来编辑 CRD `ClusterConfiguration` 中的 `ks-installer`： ```bash - kubectl -n kubesphere-system edit cm kubesphere-config + kubectl -n kubesphere-system edit cc ks-installer ``` 示例： ```yaml - apiVersion: v1 - data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - loginHistoryRetentionPeriod: 168h - maximumClockSkew: 10s - multipleLogin: true - jwtSecret: "********" - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: LDAP - type: LDAPIdentityProvider - mappingMethod: auto - provider: - host: 192.168.0.2:389 - managerDN: uid=root,cn=users,dc=nas - managerPassword: ******** - userSearchBase: cn=users,dc=nas - loginAttribute: uid - mailAttribute: mail - ``` - -2. 在 `data:kubesphere.yaml:authentication` 部分配置的 `oauthOptions:identityProviders` 以外的字段信息请参阅[设置外部身份认证](../set-up-external-authentication/)。 + spec: + authentication: + jwtSecret: '' + maximumClockSkew: 10s + multipleLogin: true + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: LDAP + type: LDAPIdentityProvider + mappingMethod: auto + provider: + host: 192.168.0.2:389 + managerDN: uid=root,cn=users,dc=nas + managerPassword: ******** + userSearchBase: cn=users,dc=nas + loginAttribute: uid + mailAttribute: mail + ``` + +2. 在 `spec:authentication` 部分配置 `oauthOptions:identityProviders` 以外的字段信息请参阅[设置外部身份认证](../set-up-external-authentication/)。 3. 在 `oauthOptions:identityProviders` 部分配置字段。 @@ -80,15 +75,23 @@ weight: 12220 iam.kubesphere.io/origin-uid: ``` -5. 字段配置完成后，执行以下命令重启 ks-apiserver 。 +5. 字段配置完成后，保存修改，然后等待 ks-installer 完成重启。 + + {{< notice note >}} + + KubeSphere Web 控制台在 ks-installer 重新启动期间不可用。请等待重启完成。 + + {{}} + +6. 如果您使用 KubeSphere 3.2.0，请在配置 LDAP 之后执行以下命令并等待至 `ks-installer` 成功运行： ```bash - kubectl -n kubesphere-system rollout restart deploy/ks-apiserver + kubectl -n kubesphere-system set image deployment/ks-apiserver *=kubespheredev/ks-apiserver:release-3.2 ``` {{< notice note >}} - KubeSphere Web 控制台在 ks-apiserver 重新启动期间不可用。请等待重启完成。 + 下个版本无需执行此步。 {{}} diff --git a/content/zh/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md b/content/zh/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md index aea61208c..9d6e99594 100644 --- a/content/zh/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md +++ b/content/zh/docs/access-control-and-account-management/external-authentication/use-an-oauth2-identity-provider.md @@ -20,7 +20,7 @@ weight: 12230 {{< notice note >}} -KubeSphere 提供了两个内置的 OAuth 2.0 插件：GitHub的 [GitHubIdentityProvider](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) 和阿里云IDaaS的 [AliyunIDaasProvider](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) ，可以根据内置的插件开发其他插件。 +KubeSphere 提供了两个内置的 OAuth 2.0 插件：GitHub 的 [GitHubIdentityProvider](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) 和阿里云IDaaS的 [AliyunIDaasProvider](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) ，可以根据内置的插件开发其他插件。 {{}} @@ -81,54 +81,48 @@ KubeSphere 提供了两个内置的 OAuth 2.0 插件：GitHub的 [GitHubIdentity ## 集成身份提供者 -1. 以 `admin` 身份登录 KubeSphere，将光标移动到右下角 ，点击 **Kubectl**，然后运行以下命令来编辑 `kubesphere-config`： +1. 以 `admin` 身份登录 KubeSphere，将光标移动到右下角 ，点击 **kubectl**，然后执行以下命令来编辑 CRD `ClusterConfiguration` 中的 `ks-installer`： ```bash - kubectl -n kubesphere-system edit cm kubesphere-config + kubectl -n kubesphere-system edit cc ks-installer ``` -2. 在 `data:kubesphere.yaml:authentication` 部分配置的 `oauthOptions:identityProviders` 以外的字段信息请参阅[设置外部身份认证](../set-up-external-authentication/)。 +2. 在 `spec:authentication` 部分配置的 `oauthOptions:identityProviders` 以外的字段信息请参阅[设置外部身份认证](../set-up-external-authentication/)。 3. 根据开发的身份提供者插件来配置 `oauthOptions:identityProviders` 中的字段。 - 以下是使用 GitHub 作为外部身份提供者的配置示例。详情请参阅[GitHub 官方文档](https://docs.github.com/en/developers/apps/building-oauth-apps) 和[GitHubIdentityProvider源代码](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) 。 + 以下是使用 GitHub 作为外部身份提供者的配置示例。详情请参阅 [GitHub 官方文档](https://docs.github.com/en/developers/apps/building-oauth-apps)和 [GitHubIdentityProvider 源代码](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) 。 ```yaml - apiVersion: v1 - data: - kubesphere.yaml: | - authentication: - authenticateRateLimiterMaxTries: 10 - authenticateRateLimiterDuration: 10m0s - jwtSecret: '******' - oauthOptions: - accessTokenMaxAge: 1h - accessTokenInactivityTimeout: 30m - identityProviders: - - name: github - type: GitHubIdentityProvider - mappingMethod: auto - provider: - clientID: '******' - clientSecret: '******' - redirectURL: 'https://ks-console/oauth/redirect/github' + spec: + authentication: + jwtSecret: '' + authenticateRateLimiterMaxTries: 10 + authenticateRateLimiterDuration: 10m0s + oauthOptions: + accessTokenMaxAge: 1h + accessTokenInactivityTimeout: 30m + identityProviders: + - name: github + type: GitHubIdentityProvider + mappingMethod: auto + provider: + clientID: '******' + clientSecret: '******' + redirectURL: 'https://ks-console/oauth/redirect/github' ``` + + 同样，您也可以使用阿里云 IDaaS 作为外部身份提供者。详情请参阅[阿里云 IDaaS 文档](https://www.alibabacloud.com/help/product/111120.htm?spm=a3c0i.14898238.2766395700.1.62081da1NlxYV0)和 [AliyunIDaasProvider 源代码](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go)。 - 同样，您也可以使用阿里云 IDaaS 作为外部身份提供者。详情请参阅[阿里云 IDaaS 文档](https://www.alibabacloud.com/help/product/111120.htm?spm=a3c0i.14898238.2766395700.1.62081da1NlxYV0) 和[AliyunIDaasProvider源代码](https://github.com/kubesphere/kubesphere/blob/release-3.1/pkg/apiserver/authentication/identityprovider/github/github.go) 。 - -4. 修改 `kubesphere-config` 配置后，执行以下命令重启 ks-apiserver 。 - - ```bash - kubectl -n kubesphere-system rollout restart deploy/ks-apiserver - ``` +4. 字段配置完成后，保存修改，然后等待 ks-installer 完成重启。 {{< notice note >}} - - KubeSphere Web 控制台在 ks-apiserver 重新启动期间不可用。请等待重启完成。 + + KubeSphere Web 控制台在 ks-installer 重新启动期间不可用。请等待重启完成。 {{}} -5. 进入 KubeSphere 登录界面，点击 **Log In with XXX** （例如， **Log In with GitHub**）。 +5. 进入 KubeSphere 登录界面，点击 **Log In with XXX** （例如，**Log In with GitHub**）。 6. 在外部身份提供者的登录界面，输入身份提供者配置的用户名和密码，登录 KubeSphere 。