Authentication & Authorization

TKeeper authenticates & authorizes all requests to protected endpoints. The authentication mechanism is selected via the auth configuration section. Authorization is enforced using explicit permission identifiers.

Supported auth.type values

Request headers

JWT authentication

When auth.type = "jwt", TKeeper validates incoming requests using a JSON Web Key Set (JWKS) configured at auth.jwt.jwks-location. The JWKS is periodically refreshed.

Validation rules

A request is authenticated only if the presented token passes all checks:

• Key selection: token header contains a kid that matches a key in the JWKS.
• Signature verification: token signature validates under the selected key.
• Audience check: token aud includes (or equals) auth.jwt.audience.
• Subject: token has a sub claim (used as the principal identifier in audit records).

If authentication fails, the request is rejected as unauthenticated.

Permissions source

JWT tokens MUST carry a permissions claim (string list). TKeeper uses these permission strings for authorization checks (see Authorization via permissions).

Example payload fragment:

{
  "sub": "user:alice",
  "aud": "tkeeper",
  "permissions": [
    "tkeeper.system.health",
    "tkeeper.key.mykey.sign"
  ]
}

Configuration

auth {
  type = "jwt"
  jwt {
    jwks-location = "https://issuer.example.com/.well-known/jwks.json"
    audience = "tkeeper"
    refresh = 15m
  }
}

OIDC integration for the Control Plane UI

The Control Plane UI (/ui) can use an OpenID Connect (OIDC) provider to obtain a JWT for browser sessions. This is configured under auth.jwt.oidc.

OIDC properties

• client-id: OIDC client identifier registered with the provider.
• discovery-url: provider discovery document URL (typically https://<idp>/.well-known/openid-configuration).
• callback-url: redirect URI on TKeeper that receives the authorization response (must match provider registration).

Configuration

auth {
  type = "jwt"
  jwt {
    jwks-location = "https://issuer.example.com/.well-known/jwks.json"
    audience = "tkeeper"

    oidc {
      client-id = "tkeeper-ui"
      discovery-url = "https://issuer.example.com/.well-known/openid-configuration"
      callback-url = "https://tkeeper.example.com/ui/oidc/callback"
    }
  }
}

If the OIDC section is omitted, the UI can operate in token-paste mode (manual entry of a JWT).

Dev authentication

When auth.type = "dev", TKeeper authenticates requests using a static shared token provided via X-DEV-TOKEN. Authorization permissions are loaded from DevConfig.

Warning It is intended for local development and isolated test environments only.

Requirements

To use dev authentication you must:

1. Enable dev config loading
   • keeper.dev.enabled = true
2. Provide the dev config location via JVM system property
   • -Dkeeper.dev.config.location=...

DevConfig is intended for local development and controlled test environments.

DevConfig format

DevConfig must define:

• keeper.dev.token: token value that clients must send in X-DEV-TOKEN
• keeper.dev.permissions: list of permission identifiers

Example dev.conf:

keeper {
  dev {
    token = "dev-token-change-me"
    permissions = [
      "tkeeper.system.*",
      "tkeeper.key.*.sign"
    ]
  }
}

Example run:

java \
  -Dkeeper.dev.enabled=true \
  -Dkeeper.dev.config.location=/etc/tkeeper/dev.conf \
  -Dkeeper.config.location=/etc/tkeeper/application.conf \
  -jar tkeeper.jar

Authentication configuration reference

DevConfig is supplied via keeper.dev.* settings in a separate dev configuration file. See Configuration for DevConfig delivery and location rules.

Authorization via permissions

Authorization is evaluated using explicit permission identifiers attached to the authenticated principal.

Wildcard Permission Matching (since 1.0.3)

TKeeper always supported * when the whole segment is a wildcard.
Starting from 1.0.3, TKeeper also supports partial wildcards inside a segment (prefix*, *suffix, prefix*suffix).

Syntax

Permissions are dot-separated segments. Each segment supports at most one * wildcard. The deep wildcard ** is explicitly forbidden to enforce least-privilege.

Segment count must match exactly: tkeeper.key.*.sign does not match tkeeper.key.ns.wallet.sign.

Examples

# Grant signing with any wallet-prefixed key
tkeeper.key.wallet-*.sign

# Grant decryption with any custody key in prod
tkeeper.key.custody-*-prod.decrypt

# Grant public key retrieval for all keys
tkeeper.key.*.public

# Deny destroy on all master-prefixed keys
-tkeeper.key.master-*.destroy

Deny rules

Permissions prefixed with - act as deny rules. A permission is granted only if at least one allow pattern matches and no deny pattern matches.

# Allow signing with any key, but block master keys
tkeeper.key.*.sign
-tkeeper.key.master-*.sign

In this configuration, tkeeper.key.wallet-hot.sign is allowed, while tkeeper.key.master-root.sign is denied.

Invalid patterns

The following patterns are rejected at parse time with an error:

Scope patterns

Permissions are typically scoped by resource identifiers (for example key identifiers). Examples:

• Key-scoped:
  • tkeeper.key.<keyId>.sign
  • tkeeper.key.<keyId>.encrypt
• System-scoped:
  • tkeeper.system.init
  • tkeeper.system.unseal

A caller granted tkeeper.key.mykey.sign can sign only for mykey. A caller granted tkeeper.key.*.sign can sign for all keys.

Permission sources

• JWT mode: from token claims (for example permissions) and/or external policy enforcement in the identity provider.
• Dev mode: from keeper.dev.permissions in DevConfig.

If permission checks fail, the request is rejected as access denied.

Permission catalog

This section lists the permission identifiers used by TKeeper.

Key-scoped permissions

Replace <logicalId> with the key logicalId.

Key generation (DKG)

Replace <mode> with the key generation mode name in lowercase (create, rotate, refresh).

System and platform permissions