Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add TiDB Dashboard session docs #6058

Merged
merged 2 commits into from
Jul 30, 2021
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions TOC.md
Original file line number Diff line number Diff line change
Expand Up @@ -491,6 +491,9 @@
+ [Use Diagnostics](/dashboard/dashboard-diagnostics-usage.md)
+ [Search Logs Page](/dashboard/dashboard-log-search.md)
+ [Profile Instances Page](/dashboard/dashboard-profiling.md)
+ Session Management and Configuration
+ [Share Session](/dashboard/dashboard-session-share.md)
+ [Configure SSO](/dashboard/dashboard-session-sso.md)
+ [FAQ](/dashboard/dashboard-faq.md)
+ CLI
+ [tikv-ctl](/tikv-control.md)
Expand Down
56 changes: 56 additions & 0 deletions dashboard/dashboard-session-share.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: Share TiDB Dashboard Sessions
summary: Learn how to share current TiDB Dashboard sessions to others to access.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved
---

# Share TiDB Dashboard Sessions

You can share the current session of the TiDB Dashboard to other users so that they can access and operate the TiDB Dashboard without entering the user password.

## Steps for the Inviter

1. Sign into TiDB Dashboard.

2. Click the username in the left sidebar to access the configure page.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

3. Click **Share Current Session**.

![Sample Step](/media/dashboard/dashboard-session-share-settings-1.png)
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

> **Note:**
>
> For security, the shared session cannot be shared again.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

4. Adjust sharing settings in the popup dialog:

- Expire in: How long the shared session will last for. Signing out the current session will not sign out any shared sessions.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

- Share as read-only privilege: The shared session can only perform read operations but not write operations (like modifying configurations).
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

5. Click **Generate Authorization Code**.

![Sample Step](/media/dashboard/dashboard-session-share-settings-2.png)

6. Provide the generate **Authorization Code** to the user that you want to share session to.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step](/media/dashboard/dashboard-session-share-settings-3.png)

> **Warning:**
>
> Anyone can use the TiDB Dashboard with the authorization code. For this reason, please keep the authorization code secure and do not send it to someone that is untrusted to avoid unauthorized access.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

## Steps for the Invitee

1. In the sign in page in TiDB Dashboard, click **Use Alternative Authentication**.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step](/media/dashboard/dashboard-session-share-signin-1.png)

2. Click **Authorization Code** to use it to sign in.

![Sample Step](/media/dashboard/dashboard-session-share-signin-2.png)

3. Enter the authorization code you receive from others.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

4. Click **Sign In**.

![Sample Step](/media/dashboard/dashboard-session-share-signin-3.png)
151 changes: 151 additions & 0 deletions dashboard/dashboard-session-sso.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
---
title: Configure SSO for TiDB Dashboard
summary: Learn how to enable SSO sign in for TiDB Dashboard
TomShawn marked this conversation as resolved.
Show resolved Hide resolved
---

# Configure SSO for TiDB Dashboard

TiDB Dashboard supports [OIDC](https://openid.net/connect/) based Single Sign-On (SSO). After enabling the SSO feature of the TiDB Dashboard, users can authenticate with the configured SSO service and then use TiDB Dashboard without entering the SQL user password.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

## Configure OIDC SSO

### Enable SSO

1. Sign into TiDB Dashboard.

2. Click the username in the left sidebar to access the configure page.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

3. Under the **Single Sign-On** section, select **Enable to use SSO when sign into TiDB Dashboard** 。
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

4. Fill the **OIDC Client ID** and the **OIDC Discovery URL** fields in the form.

Generally the two fields can be obtained from the SSO service provider:
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

- OIDC Client ID: a.k.a. OIDC Token Issuer
- OIDC Discovery URL: a.k.a. OIDC Token Audience
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

5. Click **Authorize Impersonation** and input the SQL password.

TiDB Dashboard will store this SQL password and use it to impersonate a normal SQL sign-in after an SSO sign in is finished.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step](/media/dashboard/dashboard-session-sso-enable-1.png)

> **Note:**
>
> The password you entered will be encrypted and stored. The SSO sign-in will fail after the password of the SQL user is changed. In this case, you can re-enter the password to bring SSO back again.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

6. Click **Authorize and Save**.

![Sample Step](/media/dashboard/dashboard-session-sso-enable-2.png)

7. Click **Update** (Update) to save the configuration.

![Sample Step](/media/dashboard/dashboard-session-sso-enable-3.png)

Now SSO sign in has been enabled for TiDB Dashboard.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

> **Note:**
>
> For security, some SSO services requires additional configuration for the SSO service, like trusted sign in and sign out URIs. Please refer to the documentation of the SSO service for further information.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

### Disable SSO

You can disable the SSO, which will completely erase the stored SQL password:

1. Sign into TiDB Dashboard.

2. Click the username in the left sidebar to access the configure page.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

3. Under the **Single Sign-On** section, deselect **Enable to use SSO when sign into TiDB Dashboard** 。
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

4. Click **Update** (Update) to save the configuration.

![Sample Step](/media/dashboard/dashboard-session-sso-disable.png)

### Re-entering the Password after a Password Change
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

The SSO sign-in will fail once the password of the SQL user is changed. In this case, you can bring back the SSO sign-in by re-entering the SQL password:

1. Sign into TiDB Dashboard.

2. Click the username in the left sidebar to access the configure page.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

3. Under the **Single Sign-On** section, Click **Authorize Impersonation** and input the updated SQL password.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step](/media/dashboard/dashboard-session-sso-reauthorize.png)

4. Click **Authorize and Save**.

## Sign in with SSO
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

Once SSO is configured for the TiDB Dashboard, you can sign in via SSO by following steps below:
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

1. In the sign in page of TiDB Dashboard, click **Sign in via Company Account**.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step](/media/dashboard/dashboard-session-sso-signin.png)

2. Sign in in the configured SSO service.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

3. You will be redirected back to the TiDB Dashboard to finish the sign in.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

## Sample: Use Okta for TiDB Dashboard SSO
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

[Okta](https://www.okta.com/) is an OIDC SSO identity service, which is compatible with the SSO feature of TiDB Dashboard. Steps below demostrates how to configure Okta and TiDB Dashboard so that Okta can be used as the TiDB Dashboard SSO provider.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

### Step 1: Configure Okta

First, create an Okta Application Integration.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

1. Access Okta admin site.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

2. Navigate from left sidebar **Applications** > **Applications**.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

3. Click **Create App Integration**。

![Sample Step](/media/dashboard/dashboard-session-sso-okta-1.png)

4. In the poped up dialog, choose **OIDC - OpenID Connect** in **Sign-in method**.

5. Choose **Single-Page Application** in **Application Type**.

6. Click **Next** button.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step](/media/dashboard/dashboard-session-sso-okta-2.png)

7. Fill **Sign-in redirect URIs** as:
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

```
http://DASHBOARD_IP:PORT/dashboard/?sso_callback=1
```

Substitute `DASHBOARD_IP:PORT` with the actual domain (or IP address) and port that you use to access the TiDB Dashboard in the browser.

8. Fill **Sign-out redirect URIs** as:
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

```
http://DASHBOARD_IP:PORT/dashboard/
```

Similarly, substitute `DASHBOARD_IP:PORT` with the actual domain (or IP address) and port.

![Sample Step](/media/dashboard/dashboard-session-sso-okta-3.png)

9. Configure what kind of users in the organization is allowed to SSO sign in in the **Assignments** field, and then click **Save** to save the configuration.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step](/media/dashboard/dashboard-session-sso-okta-4.png)

### Step 2: Obtain OIDC information and fill in TiDB Dashboard

1. In the Application Integration just created in Okta, click **Sign On**.

![Sample Step 1](/media/dashboard/dashboard-session-sso-okta-info-1.png)

2. Copy values of the **Issuer** and **Audience** fields from the **OpenID Connect ID Token** section.

![Sample Step 2](/media/dashboard/dashboard-session-sso-okta-info-2.png)

3. Open TiDB Dashboard configure page, fill **OIDC Client ID** with **Issuer** obtained from the last step and fill **OIDC Discovery URL** with **Audience**. Then finish the authorization and save configuration, as:
TomShawn marked this conversation as resolved.
Show resolved Hide resolved

![Sample Step 3](/media/dashboard/dashboard-session-sso-okta-info-3.png)

Now TiDB Dashboard has been configured to use Okta SSO for signing in.
TomShawn marked this conversation as resolved.
Show resolved Hide resolved
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/dashboard/dashboard-session-sso-okta-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/dashboard/dashboard-session-sso-okta-2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/dashboard/dashboard-session-sso-okta-3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/dashboard/dashboard-session-sso-okta-4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/dashboard/dashboard-session-sso-signin.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.