Skip to main content

Verifiers

A Biscuit Verifier is a key component in the Biscuit token framework, used to validate and enforce additional constraints on a Biscuit token.

While Biscuit tokens inherently carry embedded rules and checks, a verifier allows you to apply context-specific restrictions during token validation without modifying the token itself.

Using a verifier means you don’t need to modify or reissue tokens for every new constraint. Instead, constraints can be added at runtime when validating the token.

Overview​

Key Features​

  • Dynamic Constraint Management: Add new constraints at runtime without altering the original token.
  • Enhanced Security: Enforce strict validation policies tailored to specific contexts.
  • Extensibility: Easily integrate with various APIs and frameworks.

Common Use Cases​

  • Limiting token usage to specific timeframes.
  • Restricting token access to particular resources.
  • Enforcing domain-specific rules dynamically.

Example Configuration​

The following JSON configuration defines a Biscuit Verifier with a time constraint:

{
  "enabled": true,
  "id": "biscuit_verifier_6f5f20a5-2c65-4860-8ad1-7b6495ee03bf",
  "keypair_ref": "biscuit_keypair_e42033bc-f181-485f-857d-576e4728f6f9",
  "name": "Biscuit Verifier",
  "description": "Biscuit Verifier",
  "strict": true,
  "tags": [],
  "config": {
    "checks": [
      "check if time($date), $date <= 2024-12-30T19:00:10Z;"
    ],
    "facts": [],
    "resources": [],
    "rules": [],
    "revocation_ids": []
  },
  "kind": "biscuit.extensions.cloud-apim.com/BiscuitVerifier"
}

Explanation of Fields​

  • enabled: Indicates if the verifier is active.
  • id: Unique identifier for the verifier.
  • keypair_ref: Reference to the cryptographic keypair used for token verification.
  • name: Human-readable name for the verifier.
  • description: Description of the verifier’s purpose.
  • strict: Enforces strict checking of constraints.
  • tags: Metadata tags for organizing verifiers.
  • config: Contains the specific rules, checks, facts, and other configurations applied by the verifier.
    • checks: Constraints enforced during validation (e.g., time-based restrictions).
    • facts: Contextual facts provided to the verifier.
    • resources: Specifies resources associated with the token.
    • rules: Defines custom rules for validation.
    • revocation_ids: List of IDs marking revoked tokens.
  • kind: Specifies the resource type for integration with APIs.

Creating a Biscuit Verifier from Command Line​

You can create a Biscuit Verifier using the Otoroshi API with the following curl command:

curl -X POST -H 'Content-Type: application/json' \
  'http://otoroshi-api.oto.tools:8080/apis/biscuit.extensions.cloud-apim.com/v1/biscuit-verifiers' \
  -u admin-api-apikey-id:admin-api-apikey-secret \
  -d '{
    "enabled": true,
    "id": "biscuit_verifier_6f5f20a5-2c65-4860-8ad1-7b6495ee03bf",
    "keypair_ref": "biscuit_keypair_e42033bc-f181-485f-857d-576e4728f6f9",
    "name": "Biscuit Verifier CURL",
    "description": "A Biscuit Verifier created from Otoroshi API",
    "strict": true,
    "tags": [],
    "config": {
      "checks": [
        "check if time($date), $date <= 2024-12-30T19:00:10Z;"
      ],
      "facts": [],
      "resources": [],
      "rules": [],
      "revocation_ids": []
    },
    "kind": "biscuit.extensions.cloud-apim.com/BiscuitVerifier"
  }'

Bulk creation​

curl -X POST -H 'Content-Type: application/x-ndjson' \
  'http://otoroshi-api.oto.tools:8080/apis/biscuit.extensions.cloud-apim.com/v1/biscuit-verifiers/_bulk' \
  -u admin-api-apikey-id:admin-api-apikey-secret \
  -d '{"enabled":true,"id":"verifier_bulk_1","keypair_ref":"biscuit_keypair_e42033bc-f181-485f-857d-576e4728f6f9","name":"Biscuit Verifier FROM CURL BULK 1","description":"A Biscuit Verifier created from Otoroshi API","strict":true,"tags":[],"config.checks":["check if time($date), $date <= 2024-12-30T19:00:10Z;"],"config.facts":[],"config.resources":[],"config.rules":[],"config.revocation_ids":[],"kind":"biscuit.extensions.cloud-apim.com/BiscuitVerifier"}
{"enabled":true,"id":"verifier_bulk_2","keypair_ref":"biscuit_keypair_e42033bc-f181-485f-857d-576e4728f6f9","name":"Biscuit Verifier FROM CURL BULK 2","description":"A Biscuit Verifier created from Otoroshi API","strict":true,"tags":[],"config.checks":["check if time($date), $date <= 2024-12-30T19:00:10Z;"],"config.facts":[],"config.resources":[],"config.rules":[],"config.revocation_ids":[],"kind":"biscuit.extensions.cloud-apim.com/BiscuitVerifier"}'

Response​

{"status":201,"created":true,"id":"verifier_bulk_1","id_field":"id"}
{"status":201,"created":true,"id":"verifier_bulk_2","id_field":"id"}

Configuration Examples​

Rules​

Rules are logical expressions used to define conditions under which certain actions are authorized. They can combine facts, predicates, and other rules to evaluate permissions.

Example Rule​

The following rule determines whether a user is allowed to perform an operation on a resource:

is_allowed($user, $res, $op) <- 
    user($user),          // Declares the user
    resource($res),       // Declares the resource
    operation($op),       // Declares the operation
    right($user, $res, $op); // Verifies the user has the necessary rights

In this example:

  • user($user) identifies the user.
  • resource($res) identifies the resource being accessed.
  • operation($op) specifies the action (e.g., read, write).
  • right($user, $res, $op) asserts that the user has the permission for the operation on the resource.

Facts​

Facts are data points or assertions stored in the Biscuit token. They are used as inputs to evaluate the rules. For example:

user("alice");
resource("file1");
operation("read");
right("alice", "file1", "read");

These facts state that:

  • Alice is the user.
  • The resource is "file1".
  • The operation is "read".
  • Alice has the right to perform the read operation on file1.

Policies​

Policies are used to define the decision logic for allowing or denying access. Biscuit tokens support allow and deny policies to control access.

Example Policy​

The following policy allows access if the is_allowed rule evaluates to true:

allow if is_allowed($user, $resource, $op);

This policy specifies that:

  • Access is granted (allow) if the is_allowed rule matches.

Combining Policies​

Policies can also include deny conditions, such as:

deny if user($user), resource($res), operation($op), not right($user, $res, $op);

This policy denies access if:

  • A user, resource, and operation are defined.
  • The user does not have the corresponding right for the resource and operation.

Contextual Restrictions​

Biscuit tokens support additional contextual restrictions using caveats. Caveats allow tokens to impose extra conditions that must be satisfied for access to be granted.

Example of Caveats​

To restrict access to a specific time range:

time($t), $t <= 1672531200, $t >= 1672444800;

Here:

  • $t represents the current time.
  • Access is allowed only if the current time falls between the specified timestamps.

Example with IP Restriction​

To restrict access based on IP address:

ip("192.168.1.1");

Access is allowed only if the IP matches 192.168.1.1.

Advanced Examples​

Hierarchical Rights​

Defining a hierarchy where admin users have access to all resources and operations:

right($user, $res, $op) <- role($user, "admin");

Read-Only Role​

Defining a "read-only" role:

right($user, $res, "read") <- role($user, "read-only");

Resource-Specific Rights​

Granting a user specific rights on a specific resource:

right("bob", "file2", "write");

Example as CURL call with Rules and Policies​

curl -X POST -H 'Content-Type: application/json' \
  'http://otoroshi-api.oto.tools:8080/apis/biscuit.extensions.cloud-apim.com/v1/biscuit-verifiers' \
  -u admin-api-apikey-id:admin-api-apikey-secret \
  -d '{
    "enabled": true,
    "keypair_ref": "biscuit_keypair_e42033bc-f181-485f-857d-576e4728f6f9",
    "name": "Biscuit Verifier FROM CURL 1",
    "description": "A Biscuit Verifier created from Otoroshi API",
    "strict": true,
    "tags": [],
    "config": {
      "checks": [
        "check if time($date), $date <= 2025-12-30T19:00:10Z;"
      ],
      "facts": [
        "user(\"alice\");",
        "resource(\"file1\");",
        "operation(\"read\");",
        "right(\"alice\",\"file1\",\"read\");"
      ],
      "resources": [],
      "rules": [
        "is_allowed($user, $res, $op) <- user($user), resource($res), operation($op), right($user, $res, $op);"
      ],
      "policies": [
         "allow if is_allowed($user, $resource, $op);"
      ],
      "revokedIds": []
    },
    "kind": "biscuit.extensions.cloud-apim.com/BiscuitVerifier"
  }'