Skip to main content

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.

Authenticators​

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

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: 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.

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.

Configuration​

Please fill out the values in your vulcan.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

eason:202cb962ac59075b964b07152d234b70
andy:202cb962ac59075b964b07152d234b70

If you want to add some attributes for these users, you can set them in vulcan.yaml. For example,

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".

curl -H "Authorization: basic aXZhbjoxMjM=" http://localhost:3000/api/customer

Password File​

VulcanSQL authenticates users via HTTP header with a password file.

Configuration​

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”:

htpasswd -bnBC 10 "andy" 123

If you want to add some attributes for these users, you can set them in vulcan.yaml. For example,

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”.

curl -H "Authorization: password-file YW5keToxMjM=" http://localhost:3000/api/customer

Simple Token​

Configuration​

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”.

curl -H "Authorization: simple-token another-secret" http://localhost:3000/api/customer