Skip to content

Latest commit

 

History

History
112 lines (94 loc) · 5.74 KB

configuration.md

File metadata and controls

112 lines (94 loc) · 5.74 KB
Raw

Server configuration

Warrant requires certain configuration variables to be set via either a warrant.yaml config file or via environment variables. There is a set of common variables as well as datastore-specific configuration.

Common variables

Variable Description Required? Default YAML ENV VAR
port Port where the server runs. no 8000 port: VALUE WARRANT_PORT=VALUE
logLevel Log level (e.g. Debug, Info etc.) for the server. Warrant uses zerolog, valid log levels are defined here. no 0 logLevel: VALUE WARRANT_LOGLEVEL=VALUE
enableAccessLog Determines whether the built-in request logger is enabled or not. no true enableAccessLog: VALUE WARRANT_ENABLEACCESSLOG=VALUE
autoMigrate If set to true, the server will apply datastore migrations before starting up. no false autoMigrate: VALUE WARRANT_AUTOMIGRATE=VALUE
check.concurrency The default concurrency setting for access checks. no 4 concurrency: VALUE WARRANT_CHECK_CONCURRENCY=VALUE
check.maxConcurrency The max concurrency setting for access checks. no 1000 maxConcurrency: VALUE WARRANT_CHECK_MAXCONCURRENCY=VALUE
check.timeout Access check global timeout. no 1m timeout: VALUE WARRANT_CHECK_TIMEOUT=VALUE

Warrant Server Authentication

Warrant supports two types of authentication: API key and JWT authentication tokens.

API Key Authentication

By default, you must configure an API key that Warrant will use to authenticate all requests. You should follow standard security practices for generating and storing your API key.

Variable Description Required? Default YAML ENV VAR
authentication.apiKey The unique API key that all clients must pass to the server via the Authorization: ApiKey VALUE header yes - authentication:
 apiKey: VALUE		 WARRANT_AUTHENTICATION_APIKEY=VALUE

3rd-party Auth Provider Token Authentication

You can optionally configure Warrant to allow access check requests made to the /v2/authorize endpoint using JWT authentication tokens generated by your application or a 3rd-party authentication provider (e.g. Auth0, Firebase, etc). You can also configure the claims in the JWT token that specify the userId and tenantId of the user being authenticated. These claims will be used to automatically populate the subject and context for the access check(s) being made, so any requests using JWTs will be scoped to the user and tenant specified in the token.

Variable Description Required? Default YAML ENV VAR
authentication.provider The authentication provider used to generate the auth tokens. yes - authentication:
 provider: VALUE		 WARRANT_AUTHENTICATION_PROVIDER=VALUE
authentication.publicKey The signing certificate used to sign the auth token. Currently only RSA signed tokens are supported. yes - authentication:
 publicKey: VALUE		 WARRANT_AUTHENTICATION_PUBLICKEY=VALUE
authentication.userIdClaim The claim containing the user id of the user being authenticated. no sub authentication:
 userIdClaim: VALUE		 WARRANT_AUTHENTICATION_USERIDCLAIM=VALUE
authentication.tenantIdClaim The claim containing the tenant id of the user being authenticated. no - authentication:
 tenantIdClaim: VALUE		 WARRANT_AUTHENTICATION_TENANTIDCLAIM=VALUE

If you are using Firebase as your authentication provider, the public key value is optional.

Set up datastore

Warrant is a stateful service that runs with an accompanying datastore. Currently, MySQL, PostgreSQL and SQLite (file and in-memory) are supported. Refer to these guides to set up your desired database(s):

Here is an example of a full server config using mysql for the datastore:

Sample warrant.yaml config (place file in same dir as server binary)

port: 8000
logLevel: 1
enableAccessLog: true
autoMigrate: true
check:
    concurrency: 4
    maxConcurrency: 1000
    timeout: 1m
authentication:
    apiKey: your_api_key
datastore:
  mysql:
    username: replace_with_username
    password: replace_with_password
    hostname: replace_with_hostname
    database: warrant

Sample warrant.yaml config with JWT authentication config

port: 8000
logLevel: 1
enableAccessLog: true
autoMigrate: true
check:
    concurrency: 4
    maxConcurrency: 1000
    timeout: 1m
authentication:
    apiKey: your_api_key
    provider: auth0
    publicKey: |
        -----BEGIN CERTIFICATE-----
        your_public_signing_key
        -----END CERTIFICATE-----
    userIdClaim: sub
    tenantIdClaim: aud
datastore:
  mysql:
    username: replace_with_username
    password: replace_with_password
    hostname: replace_with_hostname
    database: warrant

Sample environment variables config

export WARRANT_PORT=8000
export WARRANT_LOGLEVEL=1
export WARRANT_ENABLEACCESSLOG=true
export WARRANT_AUTOMIGRATE=true
export WARRANT_CHECK_CONCURRENCY=4
export WARRANT_CHECK_MAXCONCURRENCY=1000
export WARRANT_CHECK_TIMEOUT="1m"
export WARRANT_AUTHENTICATION_APIKEY="replace_with_api_key"
export WARRANT_DATASTORE_MYSQL_USERNAME="replace_with_username"
export WARRANT_DATASTORE_MYSQL_PASSWORD="replace_with_password"
export WARRANT_DATASTORE_MYSQL_HOSTNAME="replace_with_hostname"
export WARRANT_DATASTORE_MYSQL_DATABASE="warrant"