[DOC] Update Authentication topic

docs/api/welcome/authentication.md

@@ -9,109 +9,148 @@ order: 1
 
 PMM Server's user authentication is built on top of and is compatible with [Grafana authentication](https://grafana.com/docs/grafana/latest/auth/grafana/).
 
-In this section we will talk about two main authentication mechanisms:
+Starting with PMM v3, authentication uses **Grafana service accounts** with limited scopes and enhanced security. Service accounts provide a secure and efficient way to manage access to PMM Server components and resources.
 
-- Basic HTTP authentication
-- Bearer Authentication (Authentication with an Service Token or API key)
+## Service accounts (recommended)
 
-### Basic HTTP Authentication
+Service accounts are the primary and recommended authentication method for PMM v3.x. They replace the basic authentication and API keys used in PMM 2.
 
-Basic authentication is a very simple way to authenticate a user. An API request must contain a header field in the form of `Authorization: Basic <credentials>`, where `<credentials>` is the Base64 encoding of ID (most often username or login) and password joined by a single colon `:`.
+### Benefits of service accounts
 
-```shell
-echo -n admin:admin | base64
-```
+With service accounts, you can:
 
-Let's assume the username is `admin` and the password is also `admin`. Then the API call to get the PMM Server version info would be as follows:
+- Control access to PMM Server components and resources
+- Define granular permissions for various actions
+- Create and manage multiple access tokens for a single service account
+- Implement token lifecycle management with expiration dates
 
-```shell
-curl -X GET --header 'Authorization: Bearer XXXXX' \
-  --header 'Content-Type: application/json' https://127.0.0.1/v1/version
-```
+Creating multiple tokens for the same service account is beneficial when:
 
-If you use `curl` to make API calls, a simple equivalent to the command above is:
+- Multiple applications require the same permissions but need to be audited or managed separately. By assigning each application its own token, you can track and control their actions individually.
+- A token becomes compromised and needs to be replaced. Instead of revoking the entire service account, you can rotate or replace the affected token without disrupting other applications using the same service account.
+- You want to implement token lifecycle management. You can set expiration dates for individual tokens, ensuring they are regularly rotated and reducing the risk of unauthorized access.
 
-```shell
-curl -X GET -u admin:admin --header 'Content-Type: application/json' https://127.0.0.1/v1/version
-```
+### Service account name management
 
-### Bearer Authentication
+To prevent node registration failures, PMM automatically manages service account names that exceed 200 characters using a `{prefix}_{hash}` pattern. For example:
 
-Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The bearer token is a cryptic Service Token, or API key, which can be generated by the server admin from the Settings UI or via a respective API call (read more about how to generate <a href="https://docs.percona.com/percona-monitoring-and-management/details/api.html#generate-service-token">Service token</a> or <a href="https://docs.percona.com/percona-monitoring-and-management/details/api.html#generate-api-keys">API key</a>). The client must send the Service Token/API key in the `Authorization` header when making requests to protected resources:
+- **Original**: `very_long_mysql_database_server_in_production_environment_with_specific_location_details...`
+- **Shortened**: `very_long_mysql_database_server_in_prod_4a7b3f9d`
 
-Service Token example:
-```shell
-curl -X GET --header 'Authorization: Bearer glsa_Fp0ggev31R58ueNJbJgYw7fIGfO3yKWH_746383ab' \
-  --header 'Content-Type: application/json' https://127.0.0.1/v1/version
-```
+### Generate a service account and token
 
-You can use the Service Token in basic authentication as well:
+PMM uses Grafana service account tokens for authentication. These tokens are randomly generated strings that serve as secure alternatives to basic authentication passwords.
 
-```shell
-curl -X GET --header 'Content-Type: application/json' \
-  https://service_token:glsa_Fp0ggev31R58ueNJbJgYw7fIGfO3yKWH_746383ab@127.0.0.1/v1/version
-```
-Service Token usually has "glsa_" prefix. If you convert it from API key, it will not change. If you use API key, then it will be automatically converted into Service Account and Service Token.
+To generate a service account token:
 
-API key example:
-```shell
-curl -X GET --header 'Authorization: Bearer eyJrIjoiUXRkeDNMS1g1bFVyY0tUj1o0SmhBc3g4QUdTRVAwekoiLCJuIjoicG1tLXRlc3QiLCJpZCI6MX0=' \
-  --header 'Content-Type: application/json' https://127.0.0.1/v1/version
-```
+1. Log into PMM.
+2. From the side menu, click **Administration > Users and access**.
+3. Click on the **Service accounts** card.
+4. Click **Add service account**. Specify a unique name for your service account, select a role from the drop-down menu, and click **Create** to display your newly created service account.
+5. Click **Add service account token**.
+6. In the pop-up dialog, provide a name for the new service token, or leave the field empty to generate an automatic name.
+7. Optionally, set an expiration date for the service account token. PMM cannot automatically rotate expired tokens, which means you will need to manually [update the PMM-agent configuration file](../use/commands/pmm-agent.md) with a new service account token. Permanent tokens remain valid indefinitely unless specifically revoked.
+8. Click **Generate Token**. A pop-up window will display the new token, which usually has a `glsa_` prefix.
+9. Copy your service token to the clipboard and store it securely.
+
+Now you can use your new service token for authentication in PMM API calls or in your [pmm-agent configuration](../use/commands/pmm-agent.md).
 
-You can use the API key in basic authentication as well:
+## Authenticating with service tokens
+
+!!! caution alert alert-warning "Important"
+    Use the `-k` or `--insecure` parameter to force cURL to ignore invalid and self-signed SSL certificate errors. The option will skip the SSL verification process, and you can bypass any SSL errors while still having SSL-encrypted communication. However, using the `--insecure` parameter is not recommended. Although the data transfer is encrypted, it is not entirely secure. 
+
+    For enhanced security of your PMM installation, you need valid SSL certificates. For information on validating SSL certificates, see [SSL certificates](../admin/security/ssl_encryption.md).
+
+### Bearer authentication with service tokens
+
+Include the service token in the Authorization header of an HTTP request:
 
 ```shell
-curl -X GET --header 'Content-Type: application/json' \
-  https://api_key:eyJrIjoiUXRkeDNMS1g1bFVyY0tUj1o0SmhBc3g4QUdTRVAwekoiLCJuIjoicG1tLXRlc3QiLCJpZCI6MX0=@127.0.0.1/v1/version
+curl -H "Authorization: Bearer glsa_Fp0ggev31R58ueNJbJgYw7fIGfO3yKWH_746383ab" \
+  -H 'Content-Type: application/json' https://127.0.0.1/v1/version
 ```
 
-### Protecting Credentials
+### Basic authentication with service tokens
+
+You can also use the service token in basic authentication. Use `service_token` as the username and the service token as the password:
 
-In the previous examples, the credentials can be gleaned from the shell history or processlist, which is undesirable.
+```shell
+curl -X GET https://service_token:glsa_Fp0ggev31R58ueNJbJgYw7fIGfO3yKWH_746383ab@127.0.0.1/v1/version
+```
 
-#### Disable History
+## Protecting credentials
 
-It is possible to hide from the shell history:
+Credentials should not be exposed in shell history or process lists. Here are recommended practices:
 
-bash
+### Disable history
 
+**Bash:**
 ```shell
 set +o history
 ```
 
-zsh
-
+**Zsh:**
 ```zsh
 SAVEHIST=0
 ```
 
-#### Using --netrc
+### Using --netrc with curl
 
-When using `curl` you also have the option of using `--netrc`. Here is an example `~/.netrc`:
+You can store credentials in a `~/.netrc` file and reference it with the `--netrc` option. This keeps credentials out of shell history and visible commands.
 
+Example `~/.netrc`:
 ```
 machine 127.0.0.1
-login admin
-password admin
+login service_token
+password glsa_Fp0ggev31R58ueNJbJgYw7fIGfO3yKWH_746383ab
 ```
 
-This can then be used as follows:
+Use it with curl:
+```shell
+curl --netrc -X GET -H 'Content-Type: application/json' https://127.0.0.1/v1/version
+```
 
+To use a different file:
 ```shell
-curl --netrc -X GET --header 'Content-Type: application/json' https://127.0.0.1/v1/version
+curl --netrc --netrc-file ~/.netrc-pmm -X GET -H 'Content-Type: application/json' https://127.0.0.1/v1/version
 ```
 
-Should you wish to use a different file then the `--netrc-file` option needs to be used. If we have the credentials stored in `~/.netrc-pmm` then the command would become:
+## Legacy authentication methods
+
+!!! caution alert alert-warning "Deprecation notice"
+    The following authentication methods are deprecated in PMM v3.x. They continue to work for backward compatibility but should not be used for new implementations. Use service accounts instead.
+
+### Basic HTTP authentication (Deprecated)
+
+Basic authentication is a simple way to authenticate a user. An API request must contain an Authorization header with Base64-encoded credentials:
 
 ```shell
-curl --netrc --netrc-file ~/.netrc-pmm -X GET --header 'Content-Type: application/json' https://127.0.0.1/v1/version
+curl -X GET -u admin:admin \
+  -H 'Content-Type: application/json' https://127.0.0.1/v1/version
 ```
 
-You can use API keys in this way too, for example:
+Where the credentials are formatted as `username:password` and Base64-encoded:
 
+```shell
+echo -n admin:admin | base64
 ```
-machine 127.0.0.1
-login api_key
-password eyJrIjoiUXRkeDNMS1g1bFVyY0tUj1o0SmhBc3g4QUdTRVAwekoiLCJuIjoicG1tLXRlc3QiLCJpZCI6MX0=
+
+### API keys (Deprecated)
+
+!!! info "Migration in PMM v3"
+    When you upgrade to PMM v3.x, any existing API keys are seamlessly converted to service accounts with corresponding service tokens. For more information, see [Migrate PMM 2 to PMM 3](../pmm-upgrade/migrating_from_pmm_2.md).
+
+API keys are no longer the primary authentication method and have been replaced by service accounts. If you have existing API keys from PMM v2.x, they will be automatically migrated to service tokens.
+
+Legacy API key example (not recommended):
+```shell
+curl -X GET -H 'Authorization: Bearer eyJrIjoiUXRkeDNMS1g1bFVyY0tUj1o0SmhBc3g4QUdTRVAwekoiLCJuIjoicG1tLXRlc3QiLCJpZCI6MX0=' \
+  -H 'Content-Type: application/json' https://127.0.0.1/v1/version
 ```
+
+You can use API keys in basic authentication as well (not recommended):
+```shell
+curl -X GET -u api_key:eyJrIjoiUXRkeDNMS1g1bFVyY0tUj1o0SmhBc3g4QUdTRVAwekoiLCJuIjoicG1tLXRlc3QiLCJpZCI6MX0= \
+  -H 'Content-Type: application/json' https://127.0.0.1/v1/version
+```