api-keys Guard

Available in Zilla Plus

Defines a guard with API Keys support.

The api-keys guard authorizes requests by extracting a key and a secret from the credential string using the format pattern, then verifying the secret against a remotely fetched JSON keys document.

The keys document is an array of records. The record whose key path matches the key from the credential supplies the secret to verify, and optionally the session identity, roles and attributes — each addressed by a configured path within that record, so the guard makes no assumption about the document's structure beyond it being an array.

[
  {
    "key": "zp_test",
    "secret": "SECRET",
    "id": "alice",
    "roles": [ "read:pets/*" ],
    "plan": { "id": "plan-123" }
  }
]

guards:
  my_api_keys_guard:
    type: api-keys
    options:
      format: "{key}:{secret}"
      endpoint: https://example.com/keys.json
      credentials:
        headers:
          authorization: "Bearer token-123"
      interval: 300
      identity: id
      roles: roles
      attributes:
        plan_id: plan.id

Configuration (* required)

store

string

The name of the store used by this guard.

options*

object

The api-keys specific options.

options:
  format: "{key}:{secret}"
  endpoint: https://example.com/keys.json
  credentials:
    headers:
      authorization: "Bearer token-123"
  interval: 300
  key: key
  secret: secret
  identity: id
  roles: roles
  attributes:
    plan_id: plan.id

options.format*

string

Pattern used to parse the incoming credential string. {key} and {secret} name the two parts: {key} selects the record, {secret} is compared against that record's secret.

options:
  format: "{key}:{secret}"

options.endpoint*

string

URL of the JSON document listing the valid API keys, as an array of records. The document is fetched on startup and re-fetched continuously.

Each request sends Prefer: wait=N, and If-None-Match whenever an ETag is held. An endpoint honoring both blocks until the document changes; an endpoint honoring neither answers immediately and is paced by interval.

The fetched document is rejected, and the previously fetched document retained, if it is not an array, if any member is not an object, if any member has no value at the key path, or if two members carry the same key.

options:
  endpoint: https://example.com/keys.json

options.credentials

object

HTTP request configuration used when fetching the keys document.

credentials.headers

object as map of named string properties

HTTP headers sent with each request to the endpoint, for example to pass an authorization token.

options:
  credentials:
    headers:
      authorization: "Bearer token-123"

options.interval

integer | Default: 300

Delay in seconds between the end of one request to the endpoint and the start of the next.

This is not a polling period. When the endpoint honors Prefer: wait=N, the request has already blocked by the time it answers, so interval is trailing overhead only. When the endpoint answers immediately, interval is what paces the loop.

options:
  interval: 60

options.key

string | Default: key

Path, within each record, to the value matched against the key parsed from the credential string. Records are indexed by this value when the document is fetched, so it must be present and unique across the document.

options:
  key: id

options.secret

string | Default: secret

Path to the secret within the matched record. The value at this path must equal the secret parsed from the credential string for the request to be authorized.

options:
  secret: token

options.identity

string

Path to the session identity within the matched record. When absent, the key parsed from the credential string is used as the identity.

options:
  identity: id

options.roles

string

Path to an array of role strings within the matched record, granted to the authorized session. When absent, the session is granted no roles, so any guarded route requiring a role is denied.

options:
  roles: roles

options.attributes

object as map of named string properties

Maps attribute names to paths within the matched record. Resolved attribute values are available to downstream bindings after authorization.

options:
  attributes:
    plan_id: plan.id