hanahmily commented on code in PR #704: URL: https://github.com/apache/skywalking-banyandb/pull/704#discussion_r2256002422
########## docs/operation/security.md: ########## @@ -4,6 +4,53 @@ Security is a critical aspect of any application. In this section, we will discu ## Authentication +### External Basic Auth (Client ↔ Server) + +BanyanDB supports username/password-based authentication across both gRPC and HTTP endpoints. The following flags are used to configure basic auth: + +- `--auth-config-file`: Path to the authentication config file (YAML format) + +For example, an authentication config file might be defined like this: +```yaml +users: + - username: admin + password: 123456 + - username: test + password: 123456 +``` +BanyanDB server supports setting multiple usernames and passwords. And the config file must have permissions `0600`. Run this command after creating config file: +```shell +chmod 600 /path/to/config.yaml +``` +Then, you can use the following flags: +```shell +banyand liaison --auth-config-file=/path/to/config.yaml +``` + +When you use bydbctl, you should append `username` and `password` parameter. For example: +```shell +bydbctl group get -g group1 -a http://localhost:17913 -u admin -p 123456 +``` +The flags `addr`, `group`, `username`, `password` will be automatically saved to home directory with name `.bydbctl.yaml` with permissions `0600` if it not exists. + +Also, you can customize the config file, for example: +```yaml +addr: http://localhost:17913 +group: group1 +username: admin +password: 123456 +``` +The bydbctl config file should have permissions `0600` as well. Run this command after creating config file: +```shell +chmod 600 /path/to/bydbctlCfg.yaml +``` +Then, you can use the following flags: +```shell +bydbctl --config /path/to/bydbctlCfg.yaml group list +``` Review Comment: ```suggestion BanyanDB supports username and password-based authentication for both gRPC and HTTP endpoints. This guide explains how to configure and use this feature for both the BanyanDB server and the `bydbctl` command-line tool. ### 1. Configuring the BanyanDB Server To enable authentication on the BanyanDB server, you need to create a **YAML configuration file** that defines your users and their passwords. #### a. Create the Configuration File The configuration file should contain a list of users. For security, it's highly recommended to use strong, unique passwords instead of the examples provided below. ```yaml users: - username: admin password: StrongPassword123 - username: dev_user password: AnotherStrongPassword456 ``` #### b. Set File Permissions To protect your credentials, the configuration file **must** have read/write permissions only for the owner. Set the correct permissions using the following command: ```shell chmod 600 /path/to/auth_config.yaml ``` This command ensures that only the file's owner can read or modify the contents. #### c. Start the BanyanDB Server Finally, start the BanyanDB server with the `--auth-config-file` flag, pointing to the file you just created: ```shell banyand liaison --auth-config-file=/path/to/auth_config.yaml ``` ### 2. Authenticating with `bydbctl` When the BanyanDB server has authentication enabled, you must provide a username and password with your `bydbctl` commands. There are two ways to do this. #### Option 1: Use Command-Line Flags You can provide the authentication details directly in your `bydbctl` command using the `-u` and `-p` flags. ```shell bydbctl group get -g group1 -a http://localhost:17913 -u admin -p StrongPassword123 ``` > **Note:** The `addr`, `group`, `username`, and `password` parameters will be automatically saved to a file named `.bydbctl.yaml` in your home directory if it doesn't already exist. This file will also have the permissions `0600` for security. #### Option 2: Use a `bydbctl` Configuration File You can create a separate configuration file for `bydbctl` to store your connection and authentication details. #### a. Create the Configuration File Create a YAML file containing your connection details. For example: ```yaml addr: http://localhost:17913 group: group1 username: admin password: StrongPassword123 ``` #### b. Set File Permissions Just like with the server's authentication file, the `bydbctl` configuration file should have secure permissions: ```shell chmod 600 /path/to/bydbctl_config.yaml ``` #### c. Run `bydbctl` with the Configuration File You can then run `bydbctl` by specifying the path to your configuration file with the `--config` flag. ```shell bydbctl --config /path/to/bydbctl_config.yaml group list ``` ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
