Skip to main content

Verifier plugin

Example Request Before Using a Biscuit Verifier​

Original Request (Token in Header)​

GET /api/resource HTTP/1.1
Host: example.com
Authorization: Biscuit BISCUIT_TOKEN...originalTokenData

Using a Biscuit Verifier​

  1. Extract Token: The Authorization header contains the Biscuit token.
  2. Create a Verifier: Instantiate a Biscuit verifier and attach specific constraints (e.g., check user roles, request path, or expiration).
  3. Validate the Token: Use the verifier to validate the token against the attached constraints. If valid, proceed; otherwise, deny the request.

Step 1 : Create the Otoroshi Route​

Step 2 : Select the Biscuit verifier plugin​

Step 3 : Add the plugin to your Route​

Step 4 : Configure the Plugin​

  • Select a Biscuit Verifier entity you would like to use.

  • Choose the location of the Biscuit Token to be extracted (in headers, in query params or in cookies)

  • Finally, choose the name of the extractor (Example : could be Authorization for headers)

Example : Verifier Plugin configuration​

Here is a demo configuration :

  {
    "verifier_ref": "YOUR_BISCUIT_VERIFIER_ENTITY_REF",
    "rbac_ref": "RBAC_POLICY_ENTITY_REF" // optional
    "enforce": true, // true or false
    "extractor_type": "header", // header, query or cookies
    "extractor_name": "Authorization"
  }

Biscuit Token: Default Facts in Authorization

Default Facts Table​

Biscuit Verifier Default Facts

In the context of a Biscuit Verifier, the following data points are typically used to verify requests, ensuring proper authorization and access control. The facts are provided by the authorizer and give insight into the request, the user, and the environment to assess the legitimacy of the request.

Common Default Facts​

1. Resource Information​

  • Purpose: Identifies the resource being accessed, such as a service, domain, or a specific API endpoint. This helps the verifier determine whether the request is targeting an authorized resource.

2. Request Metadata​

  • Purpose: Contains details like the HTTP method, requested path, and the domain name from which the request originated. This is crucial for ensuring the right HTTP request is processed according to rules.

3. User Context​

  • Purpose: Identifies the user or entity making the request, including details like their assigned permissions. It helps verify if the requester has the proper authorization to access the requested resource.

4. Temporal Information​

  • Purpose: Captures timestamps related to the request. This is helpful for enforcing time-based access control policies, ensuring that requests are within a valid timeframe.

5. Route Identifiers​

  • Purpose: Associates requests with unique route descriptors for more granular access control. This enables detailed access control based on the specific path or service the request is targeting.

Default Facts Table​

Fact NameDefinitionExample
hostnameThe hostname of the server processing the request.hostname("server-123.example.com")
req_pathThe path being requested.req_path("/documents")
req_domainThe domain name of the requested service.req_domain("api.example.com")
req_methodThe HTTP method used in the request.req_method("post")
route_idThe unique identifier of the route descriptor.route_id("route_518e34e7a-e2cb-4687-952c-37a3d98b8001")
ip_addressThe IP address of the requester.ip_address("192.168.1.1")
user_name (if present)The authenticated username of the requester.user_name("alice")
user_email (if present)The authenticated email of the requester.user_email("alice@example.com")
user_tag (if present)The user's associated tag for additional categorization.user_tag("premium_user")
user_metadata (if present)Additional metadata associated with the user.user_metadata({"role": "admin", "department": "HR"})
apikey_client_id (if present)The unique identifier of the API key's client.apikey_client_id("client_1234")
apikey_client_name (if present)The name of the client associated with the API key.apikey_client_name("ClientOne")
apikey_tag (if present)A tag associated with the API key for categorization.apikey_tag("v1_api_key")
apikey_metadata (if present)Additional metadata associated with the API key.apikey_metadata({"scope": "read", "region": "US"})
req_headersThe HTTP headers sent with the request, including various key details like authorization tokens, user-agent, etc.req_headers("custom-header", "<value>")
req_headers("remote-address", "192.168.1.1:56246")
req_headers("authorization", "Bearer <token>")
req_headers("request-start-time", "<timestamp>")
req_headers("accept-encoding", "gzip, deflate")

Explanation of Key Facts for Biscuit Verifier​

hostname​

  • Explanation: This represents the specific server handling the request. By using the hostname, the verifier can ensure the request is being processed by the correct server within the authorized infrastructure.

req_path​

  • Explanation: This is the path the request is targeting. It is essential to verify that the request is trying to access a valid and permitted path, based on the verifier's rules.

req_domain​

  • Explanation: The domain helps verify if the request is targeting the right service. The verifier checks the domain to ensure the request is aligned with the expected API or service domain.

req_method​

  • Explanation: The HTTP method (GET, POST, PUT, DELETE, etc.) tells the verifier what kind of operation is being requested. Some methods may be restricted based on the user's permissions or resource settings.

route_id​

  • Explanation: A unique identifier for the route that can be associated with specific access control rules. By using route_id, the verifier can enforce policies that are specific to a particular route or service.

ip_address​

  • Explanation: The IP address allows the verifier to track where the request is coming from. In some cases, geographical or network restrictions might be applied based on the IP.

user_name (if present)​

  • Explanation: This is the authenticated username of the requester. It is used by the verifier to determine whether the user is authorized to perform the requested action based on their permissions.

user_email (if present)​

  • Explanation: If the user’s email is present, it can help identify the user uniquely and enable further context about their authentication and permissions.

user_tag (if present)​

  • Explanation: The user's associated tag provides additional categorization of the user, which may be used for access control or other policies.

user_metadata (if present)​

  • Explanation: Additional metadata tied to the user, offering further context such as roles, groups, or other important attributes.

apikey_client_id (if present)​

  • Explanation: The client ID associated with the API key. It is important for verifying the specific client making the request.

apikey_client_name (if present)​

  • Explanation: The name of the client associated with the API key, often used for easier identification and access control.

apikey_tag (if present)​

  • Explanation: A tag tied to the API key, which might be used to distinguish between different versions or categories of API keys.

apikey_metadata (if present)​

  • Explanation: Metadata related to the API key, providing extra details such as the scope of access or permissions granted.

req_headers​

  • Explanation: This contains various HTTP headers that can hold important context about the request. Key headers used in Biscuit Verifiers include:
    • Authorization: Used for passing authorization tokens (like Biscuit tokens) to verify the user’s credentials and permissions.
    • Remote-address: Denotes the IP address and port of the requester.
    • Request Start Time: Can be used for validating time-based conditions in access control.
    • Accept-Encoding: Specifies what encoding methods the client supports, which might impact how the server processes the request.