Add TiDB Cloud SQL proxy account (#18696)

TOC-tidb-cloud.md

@@ -241,6 +241,7 @@
       - [Connect AWS DMS to TiDB Cloud clusters](/tidb-cloud/tidb-cloud-connect-aws-dms.md)
 - Explore Data
   - [Chat2Query (Beta) in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md)
+  - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md)
 - Vector Search (Beta)
   - [Overview](/tidb-cloud/vector-search-overview.md)
   - Get Started

tidb-cloud/sql-proxy-account.md

@@ -0,0 +1,90 @@
+---
+title: SQL Proxy Account
+summary: Learn about the SQL proxy account in TiDB Cloud.
+---
+
+# SQL Proxy Account
+
+A SQL proxy account is a SQL user account that is automatically created by TiDB Cloud to access the database via [SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) or [Data Service](https://docs.pingcap.com/tidbcloud/api/v1beta1/dataservice) on behalf of a TiDB Cloud user. For example, `[email protected]` is a TiDB Cloud user account, while `3jhEcSimm7keKP8.testuser._41mqK6H4` is its corresponding SQL proxy account.
+
+SQL proxy accounts provide a secure, token-based authentication mechanism for accessing the database in TiDB Cloud. By eliminating the need for traditional username and password credentials, SQL proxy accounts enhance security and simplify access management.
+
+The key benefits of SQL proxy accounts are as follows:
+
+- Enhanced security: mitigates risks associated with static credentials by using JWT tokens.
+- Streamlined access: restricts access specifically to the SQL Editor and Data Service, ensuring precise control.
+- Ease of management: simplifies authentication for developers and administrators working with TiDB Cloud.
+
+## Identify the SQL proxy account
+
+If you want to identify whether a specific SQL account is a SQL proxy account, take the following steps:
+
+1. Examine the `mysql.user` table:
+
+    ```sql
+    USE mysql;
+    SELECT user FROM user WHERE plugin = 'tidb_auth_token';
+    ```
+
+2. Check grants for the SQL account. If roles like `role_admin`, `role_readonly`, or `role_readwrite` are listed, then it is a SQL proxy account.
+
+    ```sql
+    SHOW GRANTS for 'username';
+    ```
+
+## How the SQL proxy account is created
+
+The SQL proxy account is automatically created during TiDB Cloud cluster initialization for the TiDB Cloud user who is granted a role with permissions in the cluster.
+
+## How the SQL proxy account is deleted
+
+When a user is removed from [an organization](/tidb-cloud/manage-user-access.md#remove-an-organization-member) or [a project](/tidb-cloud/manage-user-access.md#remove-a-project-member), or their role changes to one that does not have access to the cluster, the SQL proxy account is automatically deleted.
+
+Note that if a SQL proxy account is manually deleted, it will be automatically recreated when the user log in to the TiDB Cloud console next time.
+
+## SQL proxy account username
+
+In some cases, the SQL proxy account username is exactly the same as the TiDB Cloud username, but in other cases it is not exactly the same. The SQL proxy account username is determined by the length of the TiDB Cloud user's email address. The rules are as follows:
+
+| Environment | Email length | Username format |
+| ----------- | ------------ | --------------- |
+| TiDB Cloud Dedicated | <= 32 characters | Full email address |
+| TiDB Cloud Dedicated | > 32 characters | `prefix($email, 23)_prefix(base58(sha1($email)), 8)` |
+| TiDB Cloud Serverless | <= 15 characters | `serverless_unique_prefix + "." + email` |
+| TiDB Cloud Serverless | > 15 characters | `serverless_unique_prefix + "." + prefix($email, 6)_prefix(base58(sha1($email)), 8)` |
+
+Examples:
+
+| Environment | Email address | SQL proxy account username |
+| ----------- | ----- | -------- |
+| TiDB Cloud Dedicated | `[email protected]` | `[email protected]` |
+| TiDB Cloud Dedicated | `[email protected]` | `longemailaddressexample_48k1jwL9` |
+| TiDB Cloud Serverless | `[email protected]` | `{user_name_prefix}[email protected]` |
+| TiDB Cloud Serverless | `[email protected]` | `{user_name_prefix}.longem_48k1jwL9`|
+
+> **Note:**
+>
+> In the preceding table, `{user_name_prefix}` is a unique prefix generated by TiDB Cloud to distinguish TiDB Cloud Serverless clusters. For details, see the [user name prefix](/tidb-cloud/select-cluster-tier.md#user-name-prefix) of TiDB Cloud Serverless clusters.
+
+## SQL proxy account password
+
+Since SQL proxy accounts are JWT token-based, it is not necessary to manage passwords for these accounts. The security token is automatically managed by the system.
+
+## SQL proxy account roles
+
+The SQL proxy account's role depends on the TiDB Cloud user's IAM role:
+
+- Organization level:
+    - Organization Owner: role_admin
+    - Organization Billing Admin: No proxy account
+    - Organization Member: No proxy account
+    - Organization Console Audit admin: No proxy account
+
+- Project level:
+    - Project Owner: role_admin
+    - Project Data Access Read-Write: role_readwrite
+    - Project Data Access Read-Only: role_readonly
+
+## SQL proxy account access control
+
+SQL proxy accounts are JWT token-based and only accessible to the Data Service and SQL Editor. It is impossible to access the TiDB Cloud cluster using a SQL proxy account with a username and password.