# 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, and they are used for [authorization](./authz).

## Authenticators
To enable authenticators in VulcanSQL, set `auth.enabled` to true in your `vulcan.yaml` configuration file:

```yaml
auth:
  enabled: true
```

VulcanSQL offers a range of built-in authenticators, each with its unique method of validation. You can find more information about how to enable and configure these authenticators in their respective documentation. Note that you can enable multiple authenticators if they validate different credentials.

Here is a list of built-in authenticators available in VulcanSQL:

* [**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 `<username>:<md5-password>`, one user per line. For example:

:::info
You can use `echo -n '<password>' | 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(<username>:<password>)` 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 `<username>:<bcrypt-password>`, 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(<username>:<password>)` 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: simple-token <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
```
