Skip to content

certificate-authentication.md: refine cert based authentication (#2973) #2987

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jun 22, 2020
Merged

certificate-authentication.md: refine cert based authentication (#2973) #2987

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
51 changes: 35 additions & 16 deletions certificate-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ category: reference
aliases: ['/docs/stable/reference/security/cert-based-authentication/']
---

# Certificate-Based Authentication for Login <span class="version-mark">New in v3.0.8</span>
# Certificate-Based Authentication for Login

Starting from v3.0.8, TiDB supports a certificate-based authentication method for users to log into TiDB. With this method, TiDB issues certificates to different users, uses encrypted connections to transfer data, and verifies certificates when users log in. This approach is more secure than the traditional password-based authentication method commonly used by MySQL users and is thus adopted by an increasing number of users.
TiDB supports a certificate-based authentication method for users to log into TiDB. With this method, TiDB issues certificates to different users, uses encrypted connections to transfer data, and verifies certificates when users log in. This approach is more secure than the traditional password-based authentication method commonly used by MySQL users and is thus adopted by an increasing number of users.

To use certificate-based authentication, you might need to perform the following operations:

Expand All @@ -20,15 +20,7 @@ The rest of the document introduces in detail how to perform these operations.

## Create security keys and certificates

### Install OpenSSL

It is recommended that you use [OpenSSL](https://www.openssl.org/) to create keys and certificates. Taking the Debian operation system as an example, execute the following command to install OpenSSL:

{{< copyable "shell-regular" >}}

```bash
sudo apt-get install openssl
```
It is recommended that you use [OpenSSL](https://www.openssl.org/) to create keys and certificates. The certificate generation process is similar to the process described in [Enable TLS Between TiDB Clients and Servers](/enable-tls-between-clients-and-servers.md). The following paragraphs demonstrate on how to configure more attribute fields that need to be verified in the certificate.

### Generate CA key and certificate

Expand Down Expand Up @@ -265,7 +257,7 @@ First, connect TiDB using the client to configure the login verification. Then,

### Get user certificate information

The user certificate information can be specified by `require subject`, `require issuer`, and `require cipher`, which are used to check the X509 certificate attributes.
The user certificate information can be specified by `require subject`, `require issuer`, `require san`, and `require cipher`, which are used to check the X509 certificate attributes.

+ `require subject`: Specifies the `subject` information of the client certificate when you log in. With this option specified, you do not need to configure `require ssl` or x509. The information to be specified is consistent with the entered `subject` information in [Generate client keys and certificates](#generate-client-keys-and-certificates).

Expand All @@ -287,6 +279,32 @@ The user certificate information can be specified by `require subject`, `require
openssl x509 -noout -subject -in ca-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//'
```

+ `require san`: Specifies the `Subject Alternative Name` information of the CA certificate that issues the user certificate. The information to be specified is consistent with the [`alt_names` of the `openssl.cnf` configuration file](/generate-self-signed-certificates.md) used to generate the client certificate.

+ Execute the following command to get the information of the `require san` item in the generated certificate:

{{< copyable "shell-regular" >}}

```shell
openssl x509 -noout -ext subjectAltName -in client.crt
```

+ `require san` currently supports the following `Subject Alternative Name` check items:

- URI
- IP
- DNS

+ Multiple check items can be configured after they are connected by commas. For example, configure `require san` as follows for the `u1` user:

{{< copyable "sql" >}}

```sql
create user 'u1'@'%' require san 'DNS:d1,URI:spiffe://example.org/myservice1,URI:spiffe://example.org/myservice2'
```

The above configuration only allows the `u1` user to log in to TiDB using the certificate with the URI item `spiffe://example.org/myservice1` or `spiffe://example.org/myservice2` and the DNS item `d1`.

+ `require cipher`: Checks the cipher method supported by the client. Use the following statement to check the list of supported cipher methods:

{{< copyable "sql" >}}
Expand All @@ -297,7 +315,7 @@ The user certificate information can be specified by `require subject`, `require

### Configure user certificate information

After getting the user certificate information (`require subject`, `require issuer`, `require cipher`), configure these information to be verified when creating a user, granting privileges, or altering a user. Replace `<replaceable>` with the corresponding information in the following statements.
After getting the user certificate information (`require subject`, `require issuer`, `require san`, `require cipher`), configure these information to be verified when creating a user, granting privileges, or altering a user. Replace `<replaceable>` with the corresponding information in the following statements.

You can configure one option or multiple options using the space or `and` as the separator.

Expand All @@ -306,30 +324,31 @@ You can configure one option or multiple options using the space or `and` as the
{{< copyable "sql" >}}

```sql
create user 'u1'@'%' require issuer '<replaceable>' subject '<replaceable>' cipher '<replaceable>';
create user 'u1'@'%' require issuer '<replaceable>' subject '<replaceable>' san '<replaceable>' cipher '<replaceable>';
```

+ Configure user certificate when granting privileges:

{{< copyable "sql" >}}

```sql
grant all on *.* to 'u1'@'%' require issuer '<replaceable>' subject '<replaceable>' cipher '<replaceable>';
grant all on *.* to 'u1'@'%' require issuer '<replaceable>' subject '<replaceable>' san '<replaceable>' cipher '<replaceable>';
```

+ Configure user certificate when altering a user:

{{< copyable "sql" >}}

```sql
alter user 'u1'@'%' require issuer '<replaceable>' subject '<replaceable>' cipher '<replaceable>';
alter user 'u1'@'%' require issuer '<replaceable>' subject '<replaceable>' san '<replaceable>' cipher '<replaceable>';
```

After the above configuration, the following items will be verified when you log in:

+ SSL is used; the CA that issues the client certificate is consistent with the CA configured in the server.
+ The `issuer` information of the client certificate matches the information specified in `require issuer`.
+ The `subject` information of the client certificate matches the information specified in `require cipher`.
+ The `Subject Alternative Name` information of the client certificate matches the information specified in `require san`.

You can log into TiDB only after all the above items are verified. Otherwise, the `ERROR 1045 (28000): Access denied` error is returned. You can use the following command to check the TLS version, the cipher algorithm and whether the current connection uses the certificate for the login.

Expand Down