# Integrate KubeSphere with Okta Authentication

The third-party authentication is enhanced in KubeSphere 3.2.0. It becomes much easier than the 3.1.x version and you don't need to worry about the losing configuration issue anymore. In this article, we will demonstrate how to integrate KubeSphere with Okta through the OIDC provider step by step.

## Step 1: Enable HTTPS for Console

HTTPS is recommended for the production environment. If you do not need HTTPS in your environment, skip this step. To enable HTTPS for your KubeSphere web console, you need to get a certificate from a Certificate Authority (CA). For example, you can apply a certificate from [Let's Encrypt](https://letsencrypt.org/).

[cert-manager](https://github.com/jetstack/cert-manager/) can automatically request missing or expired certificates from a range of supported issuers (including [Let's Encrypt](https://letsencrypt.org/)). To set up cert-manager you should take a look at [this full example](https://cert-manager.io/docs/tutorials/acme/ingress/). We will not dig into the details here.

In the demo, The URL *https://console.kubesphere.io* will be used to access the KubeSphere web console.

## Step 2: Register an account (Optional)

Go to the [free-tail](https://www.Okta.com/free-trial/) page to register a new account if you don't have an Okta account. Once you get the activation email from Okta and activate it, you will be able to login to the Okta with the registered domain. In this demo, *https://kubesphere.Okta.com* will be used.

> You will be asked to set up Multi-Factor authentication when you login the first time. Please check Okta helps about how to set up it.


You need Okta admin permission if you are using an existing account.

## Step 3: Create a new Okta app

In the Okta admin console, you can find **Create App Integration** button under the Applications page. A wizard will pop when clicking it.


**1.** Select the **OIDC - OpenID Connect** on the wizard. Then **Application type** will be shown under the wizard. Select **Web Application** and click **Next** button.


**2.** In the General Settings section, you need to configure the following settings for KubeSphere integration:

- **App integration name**: Specify a name for KubeSphere integration.
- Optional. **Logo**: Add a logo to accompany KubeSphere integration in the Okta org.
- **Grant type**: **Authenrizion Code** and **Refresh Token** need to be checked. Leave other checkboxes unchecked.
- **Sign-in redirect URIs**: The Sign-in redirect URI is where Okta sends the authentication response and ID token for the sign-in request. Wildcard "*" is not recommended. The URL need to be set to Console OAuth login URL, in the format of "HTTP(s)://{domain or IP:port}/oauth/redirect/{Provider Name}". **Provider Name** can be changed, but it needs to be consistent with the identityProviders name in the ClusterConfiuration.
- **Sign-out redirect URIs**: When KubeSphere contacts Okta to close the user session, Okta redirects the user to this URI. (TODO: need more tests)

In Assignments:
**Controlled access**: The default access option assigns and grants access to this new app integration for everyone in your Okta org. Instead, you can choose to Limit access to selected groups and use the field to enter the names of specific groups found in your org, or Skip group assignment for now and create the app without assigning a group.

Click **Save** to commit your Application.


**Step 3**: On the Okta application page, you can find the **Client ID** and **Client secret** on the General tab. We need them in the KubeSphere Cluster Configuration.


## Step 4: Config KubeSphere

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:

kubectl -n kubesphere-system edit cc ks-installer

Add the following fields under spec.authentication.jwtSecret.

authentication:
  oauthOptions:
    identityProviders:
    - mappingMethod: auto
      name: Okta
      provider:
        clientID: **** # Get from otka
        clientSecret: ****  # Get from otka
        issuer: https://kubesphere.Okta.com # your Okta domain
	redirectURL: https://console.kubesphere.io/oauth/redirect/Okta
        scopes:
        - openid
        - email
        - profile
      type: OIDCIdentityProvider
      

When the ks-insaller running sucessfully. Okta login button is shown on the Login page. Users are redirected to Okta login page when clicking it. Users are required to register a valid username when login first time.


Once all the steps are done, you can assign roles for the users.

## Summary

KubeSphere provided various ways to interagte with your existing identity providers. However, OIDC is one of the most esisy one and well supported by many identity providers. It's recommanded if you need to intergrate with a third-party identity provider.