From 373fe53d10c1c9d68641ee629ee17b79ff0468ae Mon Sep 17 00:00:00 2001 From: ChihYu Yeh Date: Thu, 3 Aug 2023 09:48:52 +0800 Subject: [PATCH 1/2] update authentication and authorization docs --- packages/doc/docs/data-privacy/authn.mdx | 164 ++++++++++++++++++++++- packages/doc/docs/data-privacy/authz.mdx | 12 ++ 2 files changed, 172 insertions(+), 4 deletions(-) diff --git a/packages/doc/docs/data-privacy/authn.mdx b/packages/doc/docs/data-privacy/authn.mdx index e78ec8c9..5134a3cb 100644 --- a/packages/doc/docs/data-privacy/authn.mdx +++ b/packages/doc/docs/data-privacy/authn.mdx @@ -1,7 +1,8 @@ # Authentication To ensure that only authorized users access your VulcanSQL application, it's essential to identify who sends the request. This process, called authentication, typically involves validating credentials such as tokens, cookies, or other forms of identification. -In VulcanSQL, `Authenticators` handle this process, either by validating the credentials themselves or by querying third-party authentication providers. Once the authentication process is complete, additional user attributes are also added to the request for further processing. These attributes can include user names, departments, groups, statuses, and more, depending on the specific authenticator used. +In VulcanSQL, `Authenticators` handle this process, either by validating the credentials themselves or by querying third-party authentication providers. Once the authentication process is complete, additional user attributes are also added to the request for further processing. +These attributes can include user names, departments, groups, statuses, and more, and they are used for [authorization](./authz). ## Authenticators To enable authenticators in VulcanSQL, set `auth.enabled` to true in your `vulcan.yaml` configuration file: @@ -15,8 +16,163 @@ VulcanSQL offers a range of built-in authenticators, each with its unique method Here is a list of built-in authenticators available in VulcanSQL: -* **HTTP Basic**: Authenticate users via HTTP basic authentication. This method requires users to provide a username and password, which are transmitted as headers in each request. -* **Password File**: Validate users' credentials using a password file. This method involves comparing the provided username and password against a pre-defined list of authorized users stored in a file. -* **Simple Token**: Authenticate users with a static token. This method involves checking the provided token against a pre-configured token value. +* [**HTTP Basic**](#http-basic): Authenticate users via HTTP basic authentication. This method requires users to provide a username and password, which are transmitted as headers in each request. +* [**Password File**](#password-file): Validate users' credentials using a password file. This method involves comparing the provided username and password against a pre-defined list of authorized users stored in a file. +* [**Simple Token**](#simple-token): Authenticate users with a static token. This method involves checking the provided token against a pre-configured token value. By implementing the appropriate authenticators for your VulcanSQL application, you can ensure that only authorized users access your system and protect sensitive data from unauthorized access. + +## HTTP Basic + +With HTTP basic authentication, VulcanSQL authenticates users via [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). + +### Configuration + +Please fill out the values in your `vulcan.yaml`. + +```yaml +auth: + enabled: true + options: + basic: + # Read users and passwords from a text file. + htpasswd-file: + path: passwd.txt # Path to the password file. + users: # (Optional) Add attributes for users + - name: eason + attr: + department: engineer +``` + +### Password file + +You need to create a password file in format `:`, one user per line. For example: + +:::info +You can use `echo -n '' | md5sum` to generate an md5 string +::: + +```txt +eason:202cb962ac59075b964b07152d234b70 +andy:202cb962ac59075b964b07152d234b70 +``` + +If you want to add some attributes for these users, you can set them in `vulcan.yaml`. For example, + +```yaml +auth: + enabled: true + options: + basic: + htpasswd-file: + path: passwd.txt + users: + - name: eason + attr: + department: engineer +``` + +This config adds `department=engineer` for user "eason", but adds no attribute to user "andy". + +### Providing credentials to HTTP Header + +You need to add a header `Authorization: basic base64(:)` when sending requests, for example, sending requests with username "ivan" and password "123". + +```shell +curl -H "Authorization: basic aXZhbjoxMjM=" http://localhost:3000/api/customer +``` + +## Password File + +VulcanSQL authenticates users via HTTP header with a password file. + +### Configuration + +```yaml +auth: + enabled: true + options: + password-file: + path: passwd.txt + users: + - name: eason + attr: + department: engineer +``` + +### Password file + +You need to create a password file in format `:`, one user per line. For example: + +``` +eason:$2y$10$PRK6uQ52bYNPdiz4V0XtQel/Pyr8DRCvoTATcGqW5mukv7J3uvebC +andy:$2y$10$evKAprboGgLdPPeODt4n6.PTA9Iy0h1tltx5Dc1ZaIZVfBd2K1xqy +``` + +This file provides two users "eason and "andy with password "123”. + +:::info +To generate bcrypt-password, you can use htpasswd command, for example, to generate user "andy and password "123”: + +```bash +htpasswd -bnBC 10 "andy" 123 +``` +::: + +If you want to add some attributes for these users, you can set them in `vulcan.yaml`. For example, + +```yaml +auth: + enabled: true + options: + password-file: + path: passwd.txt + users: + - name: andy + attr: + department: engineer +``` + +This config adds `department=engineer` for user "andy, but adds no attribute to user "eason". + +### Providing credentials to HTTP Header + +You need to add a header `Authorization: password-file base64(:)` when sending requests. For example, sending requests with username "andy” and password "123”. + +```shell +curl -H "Authorization: password-file YW5keToxMjM=" http://localhost:3000/api/customer +``` + +## Simple Token + +### Configuration + +```yaml +auth: + enabled: true + options: + simple-token: + - name: eason # User name + token: some-secret # Token to authenticate + attr: # (optional) attributes for this user + department: engineer + - name: andy + token: another-secret + attr: + department: engineer +``` + +Simple token authenticator requires a user list. You must set the name and token for each user, and give them some optional attributes. + +:::caution +The token for each user must be different; otherwise, the last configured user overrides all the previous ones. + +::: + +### Providing credentials to HTTP Header + +You need to add a header `Authorization: sample-token ` when sending requests, for example, sending requests with the token “another-secret”. + +```shell +curl -H "Authorization: simple-token another-secret" http://localhost:3000/api/customer +``` diff --git a/packages/doc/docs/data-privacy/authz.mdx b/packages/doc/docs/data-privacy/authz.mdx index 6f895fc3..5bde64be 100644 --- a/packages/doc/docs/data-privacy/authz.mdx +++ b/packages/doc/docs/data-privacy/authz.mdx @@ -43,3 +43,15 @@ The configurations for each data source are defined in the `profiles.yaml` file. group: 'admin*' enabled: 'true' ``` + +## Set the allowed profiles to each template + +For every SQL template, we need to tell VulcanSQL what profiles they could use by adding `profiles` property on the schema. +From top to bottom, users use the first qualified profile. If users can't use any of them, 403 error will be thrown. + +```yaml +urlPath: /customer +profiles: + - pg-admin + - pg-non-admin +``` From e6bb21ba021c84604eb9365d133d24728b9891a1 Mon Sep 17 00:00:00 2001 From: ChihYu Yeh Date: Thu, 3 Aug 2023 11:32:32 +0800 Subject: [PATCH 2/2] refine wording --- packages/doc/docs/data-privacy/authn.mdx | 2 +- packages/doc/docs/data-privacy/authz.mdx | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/doc/docs/data-privacy/authn.mdx b/packages/doc/docs/data-privacy/authn.mdx index 5134a3cb..9932b1cc 100644 --- a/packages/doc/docs/data-privacy/authn.mdx +++ b/packages/doc/docs/data-privacy/authn.mdx @@ -171,7 +171,7 @@ The token for each user must be different; otherwise, the last configured user o ### Providing credentials to HTTP Header -You need to add a header `Authorization: sample-token ` when sending requests, for example, sending requests with the token “another-secret”. +You need to add a header `Authorization: simple-token ` when sending requests, for example, sending requests with the token “another-secret”. ```shell curl -H "Authorization: simple-token another-secret" http://localhost:3000/api/customer diff --git a/packages/doc/docs/data-privacy/authz.mdx b/packages/doc/docs/data-privacy/authz.mdx index 5bde64be..af7dc052 100644 --- a/packages/doc/docs/data-privacy/authz.mdx +++ b/packages/doc/docs/data-privacy/authz.mdx @@ -55,3 +55,7 @@ profiles: - pg-admin - pg-non-admin ``` + +:::info +For detailed descriptions on `profile` and `profiles` fields, please refer to the [documentation here](../references/api-schema#profiles--profile-field). +::: \ No newline at end of file