Skip to content

Commit ecc837d

Browse files
kokokuokokokuo
authored
Merge pull request #267 from cyyeh/feature/update-doc
update authentication and authorization docs
2 parents 5df01ae + e6bb21b commit ecc837d

File tree

2 files changed

+176
-4
lines changed

2 files changed

+176
-4
lines changed

‎packages/doc/docs/data-privacy/authn.mdx

+160-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Authentication
22
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.
33

4-
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.
4+
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.
5+
These attributes can include user names, departments, groups, statuses, and more, and they are used for [authorization](./authz).
56

67
## Authenticators
78
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
1516
1617
Here is a list of built-in authenticators available in VulcanSQL:
1718
18-
* **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.
19-
* **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.
20-
* **Simple Token**: Authenticate users with a static token. This method involves checking the provided token against a pre-configured token value.
19+
* [**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.
20+
* [**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.
21+
* [**Simple Token**](#simple-token): Authenticate users with a static token. This method involves checking the provided token against a pre-configured token value.
2122
2223
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.
24+
25+
## HTTP Basic
26+
27+
With HTTP basic authentication, VulcanSQL authenticates users via [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
28+
29+
### Configuration
30+
31+
Please fill out the values in your `vulcan.yaml`.
32+
33+
```yaml
34+
auth:
35+
enabled: true
36+
options:
37+
basic:
38+
# Read users and passwords from a text file.
39+
htpasswd-file:
40+
path: passwd.txt # Path to the password file.
41+
users: # (Optional) Add attributes for users
42+
- name: eason
43+
attr:
44+
department: engineer
45+
```
46+
47+
### Password file
48+
49+
You need to create a password file in format `<username>:<md5-password>`, one user per line. For example:
50+
51+
:::info
52+
You can use `echo -n '<password>' | md5sum` to generate an md5 string
53+
:::
54+
55+
```txt
56+
eason:202cb962ac59075b964b07152d234b70
57+
andy:202cb962ac59075b964b07152d234b70
58+
```
59+
60+
If you want to add some attributes for these users, you can set them in `vulcan.yaml`. For example,
61+
62+
```yaml
63+
auth:
64+
enabled: true
65+
options:
66+
basic:
67+
htpasswd-file:
68+
path: passwd.txt
69+
users:
70+
- name: eason
71+
attr:
72+
department: engineer
73+
```
74+
75+
This config adds `department=engineer` for user "eason", but adds no attribute to user "andy".
76+
77+
### Providing credentials to HTTP Header
78+
79+
You need to add a header `Authorization: basic base64(<username>:<password>)` when sending requests, for example, sending requests with username "ivan" and password "123".
80+
81+
```shell
82+
curl -H "Authorization: basic aXZhbjoxMjM=" http://localhost:3000/api/customer
83+
```
84+
85+
## Password File
86+
87+
VulcanSQL authenticates users via HTTP header with a password file.
88+
89+
### Configuration
90+
91+
```yaml
92+
auth:
93+
enabled: true
94+
options:
95+
password-file:
96+
path: passwd.txt
97+
users:
98+
- name: eason
99+
attr:
100+
department: engineer
101+
```
102+
103+
### Password file
104+
105+
You need to create a password file in format `<username>:<bcrypt-password>`, one user per line. For example:
106+
107+
```
108+
eason:$2y$10$PRK6uQ52bYNPdiz4V0XtQel/Pyr8DRCvoTATcGqW5mukv7J3uvebC
109+
andy:$2y$10$evKAprboGgLdPPeODt4n6.PTA9Iy0h1tltx5Dc1ZaIZVfBd2K1xqy
110+
```
111+
112+
This file provides two users "eason and "andy with password "123”.
113+
114+
:::info
115+
To generate bcrypt-password, you can use htpasswd command, for example, to generate user "andy and password "123”:
116+
117+
```bash
118+
htpasswd -bnBC 10 "andy" 123
119+
```
120+
:::
121+
122+
If you want to add some attributes for these users, you can set them in `vulcan.yaml`. For example,
123+
124+
```yaml
125+
auth:
126+
enabled: true
127+
options:
128+
password-file:
129+
path: passwd.txt
130+
users:
131+
- name: andy
132+
attr:
133+
department: engineer
134+
```
135+
136+
This config adds `department=engineer` for user "andy, but adds no attribute to user "eason".
137+
138+
### Providing credentials to HTTP Header
139+
140+
You need to add a header `Authorization: password-file base64(<username>:<password>)` when sending requests. For example, sending requests with username "andy” and password "123”.
141+
142+
```shell
143+
curl -H "Authorization: password-file YW5keToxMjM=" http://localhost:3000/api/customer
144+
```
145+
146+
## Simple Token
147+
148+
### Configuration
149+
150+
```yaml
151+
auth:
152+
enabled: true
153+
options:
154+
simple-token:
155+
- name: eason # User name
156+
token: some-secret # Token to authenticate
157+
attr: # (optional) attributes for this user
158+
department: engineer
159+
- name: andy
160+
token: another-secret
161+
attr:
162+
department: engineer
163+
```
164+
165+
Simple token authenticator requires a user list. You must set the name and token for each user, and give them some optional attributes.
166+
167+
:::caution
168+
The token for each user must be different; otherwise, the last configured user overrides all the previous ones.
169+
170+
:::
171+
172+
### Providing credentials to HTTP Header
173+
174+
You need to add a header `Authorization: simple-token <token>` when sending requests, for example, sending requests with the token “another-secret”.
175+
176+
```shell
177+
curl -H "Authorization: simple-token another-secret" http://localhost:3000/api/customer
178+
```

‎packages/doc/docs/data-privacy/authz.mdx

+16
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,19 @@ The configurations for each data source are defined in the `profiles.yaml` file.
4343
group: 'admin*'
4444
enabled: 'true'
4545
```
46+
47+
## Set the allowed profiles to each template
48+
49+
For every SQL template, we need to tell VulcanSQL what profiles they could use by adding `profiles` property on the schema.
50+
From top to bottom, users use the first qualified profile. If users can't use any of them, 403 error will be thrown.
51+
52+
```yaml
53+
urlPath: /customer
54+
profiles:
55+
- pg-admin
56+
- pg-non-admin
57+
```
58+
59+
:::info
60+
For detailed descriptions on `profile` and `profiles` fields, please refer to the [documentation here](../references/api-schema#profiles--profile-field).
61+
:::

0 commit comments

Comments
 (0)