Bearer Lookup

Requires a postgresql or redis datastore to supply the connection.

Description

This lets you validate API keys you already manage in your own database. It can associate a user ID and tenant ID with the request, but does not support authorization options (allowed layers or bounding box).

Lookup results can optionally be cached in memory to decrease database load. Use this with caution since a revoked token can keep working until the cache entry expires. Rejections are cached too, but outright errors (such as an inability to connect to the database) are not.

Configuration

Configuration options
Parameter	Description	Type	Required	Default
`datastore`	The ID of the datastore to use	string	Yes	None
`headerName`	The header to extract the token from. If this is `Authorization` the value must start with Bearer ` which is removed. Make sure this is in "canonical case" e.g. `X-Api-Key, otherwise auth will always fail	string	No	Authorization
`tokenEncoding`	An encoding to apply to the token before looking it up. One of `base64`, `base64urlsafe`, or `base36`. `base64urlsafe` omits the trailing `=` padding	string	No	None
`cacheSize`	How many lookup results to keep in memory. Set to -1 to disable	int	No	-1
`cacheTTL`	How many seconds a lookup result is reused before the datastore is checked again	uint32	No	600
`postgresql`	Options for a postgresql datastore. Required with a postgresql datastore and must not be set for a redis datastore. See PostgreSQL	PostgreSQL	Conditional	None
`redis`	Options for a redis datastore. Required with a redis datastore and must not be set for a postgresql datastore. See Redis	Redis	Conditional	None

PostgreSQL

The query is executed with the auth token passed in as the $1 bind parameter. It should be a SELECT that returns a single row. If no rows or more than one row are returned, authentication fails.

The returned row should have a mix of the columns in the following table. Any other columns are ignored. A column that is present but has the wrong data type causes a warning to be logged and authentication to fail.

Example

YAML
JSON

datastores:
  - name: postgresql
    id: auth_db
    host: pg.example.com
    user: tilegroxy
    password: env.PGPASSWORD
    database: accounts

authentication:
  name: bearer
  datastore: auth_db
  postgresql:
    query: SELECT user_id, tenant_id FROM api_keys WHERE token_hash = $1 AND revoked = false

{
  "datastores": [
    {
      "name": "postgresql",
      "id": "auth_db",
      "host": "pg.example.com",
      "user": "tilegroxy",
      "password": "env.PGPASSWORD",
      "database": "accounts"
    }
  ],
  "authentication": {
    "name": "bearer",
    "datastore": "auth_db",
    "postgresql": {
      "query": "SELECT user_id, tenant_id FROM api_keys WHERE token_hash = $1 AND revoked = false"
    }
  }
}

Configuration

Result columns
Column	Meaning
`valid`	A boolean used as an additional check. Authentication passes if true and fails if false or NULL
`user_id`	A string used as the user identifier, if non-null
`tenant_id`	A string used as the tenant identifier, if non-null. See How to: Serve Multiple Tenants

Configuration options
Parameter	Description	Type	Required	Default
`query`	The SQL used to look up the token. Must reference the token as `$1`	string	Yes	None

Redis

The auth token is used as a key, with a required prefix. Authentication passes if the key exists and is of the right data type. Setting a user ID and tenant ID requires the entry to be a Hash.

Example

YAML
JSON

datastores:
  - name: redis
    id: auth_redis
    host: redis.example.com

authentication:
  name: bearer
  datastore: auth_redis
  redis:
    keyPrefix: "apikey:"
    allowedType: hash

{
  "datastores": [
    {
      "name": "redis",
      "id": "auth_redis",
      "host": "redis.example.com"
    }
  ],
  "authentication": {
    "name": "bearer",
    "datastore": "auth_redis",
    "redis": {
      "keyPrefix": "apikey:",
      "allowedType": "hash"
    }
  }
}

A matching token can be created with HSET apikey:abc123 user alice tenant acme.

Configuration

Configuration options
Parameter	Description	Type	Required	Default
`keyPrefix`	Prepended to the token to form the key. Only keys starting with this prefix can be used as tokens, so use one that nothing else in the database shares	string	Yes	None
`userField`	The hash field containing the user ID	string	No	user
`tenantField`	The hash field containing the tenant ID	string	No	tenant
`allowedType`	The type of key that is accepted as a token. One of `string`, `hash`, `list`, `set`, `zset`, or `stream`. A key of any other type is rejected	string	No	Any type

Description

Configuration

PostgreSQL

Example

Configuration

Redis

Example

Configuration

Related Articles