Bearer Lookup :: tilegroxy Docs

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). Supported datastores are postgresql and redis.

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. Must not be set for a postgresql datastore. See Redis	Redis	No	None

PostgreSQL

The query is executed with the auth token passed in as the $1 bind parameter. It must be a SELECT that returns zero or one rows. If zero or more than one rows 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.

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

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 an optional prefix. Authentication passes if the key exists. 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:"

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

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

Configuration options
Parameter	Description	Type	Required	Default
`keyPrefix`	Prepended to the token to form the key	string	No	Empty string
`userField`	The hash field containing the user ID	string	No	user
`tenantField`	The hash field containing the tenant ID	string	No	tenant