Introduction to Tratteria

Welcome to the documentation for Tratteria, an open-source Transaction Tokens (TraTs) Service. This guide will help you understand what Tratteria is, how it works, and how to implement it in your microservices architecture.

TraT

TraTs (Transaction Tokens) are short-lived JWTs that assure identity and context in a microservices call chain. Learn more about TraTs here. The example below describes the salient features of a TraT:

Tratteria Architecture

Tratteria is designed to facilitate secure and convenient TraT issuance and verification in microservices systems. It involves the Tratteria Service for issuing TraTs, the Tratteria Agent sidecar for verifying TraTs, and Tratteria Kubernetes resources for specifying generation and verification rules for TraTs.

Tratteria Modes

Tratteria can operate in two modes:

• The Interception Mode: Enables existing applications to adopt TraTs without (almost) any code changes. It injects Tratteria Agent sidecar containers into Kubernetes pods, and the application continues to operate the way it used to, except the path, query and body of each call are verified against an associated TraT.

  If a service needs to forward a TraT to a downstream service, then it needs to add the Txn-token HTTP header and include the TraT as the value of that header in outbound calls. If a microservice does not make any downstream calls, then it does not need to change.

• The Delegation Mode: In this approach, the application explicitly calls the Tratteria Agent within its Kubernetes pod to verify TraTs. As a result, the application needs to make this change to its code to use Tratteria. This mode is more secure than the interception mode, as it avoids scenarios where sidecar could potentially be bypassed. In addition, a delegation based approach allows the application to pack the call parameter information in the Txn-Token header, and can potentially eliminate having to send it separately through query parameters or the body.

  This mode is suitable for environments where intercepting incoming requests is not possible or desired, for example, in environments with a service mesh that is already intercepting incoming requests.

Tratteria Resource

Tratteria lets you define how to generate the TraT for an external API and how to verify the TraT for the resulting internal requests of the external API using Kubernetes resources. Additionally, it supports specifying access evaluation for external APIs.

Below is a sample Tratteria Kubernetes resource for the POST api/order/trade/{#stockId} external API. Hover your mouse over the text below to find out more about what each line means:

apiVersion: tratteria.io/v1alpha1
kind: TraT
metadata:
  name: trade-api-tratThe name of the TraT used for this external API. This uniquely identifies the TraT type within the Tratteria system.
  namespace: app-dev
spec:
  path: "api/order/trade/{#stockId}?action={#action}"The default URL path, which, together with the method field below, results in this type of TraT being generated or validated. The URL may used by external API services or internal microservices.
  method: "POST"The HTTP method for which this TraT resource is defined (see `path` above).
  purp: "stock-trade"The purpose of the TraT, which is included in the `purp` field of TraTs of this type.
  azdMapping:
    stockId:
      required: true
      value: "${stockId}"
    action:
      required: true
      value: "${action}"
    quantity:
      required: true
      value: "${body.quantity}"The immutable context preserved in this TraT and how to construct and verify it.
  services:
    - name: order
    - name: catalog
      path: "catalog/catalog-update/{#stockId}?update-type={#action}"The catalog service overrides just the path.
    - name: stocks
      path: "stocks/{#id}"The stocks service overrides the path, method and how it receives information that needs to be verified against the TraT content.
      method: "GET"As noted above, the stocks service overrides defaults for the HTTP method.
      azdMapping:
        stockId:
          required: trueAs noted above, the stocks service overrides defaults for TraT verification
          value: "{$id}"The list of microservice APIs that are invoked while processing this external API. They may use defaults specified above or override them.
  accessEvaluation:
    subject:
      id: "${subject_token.email}"
    action:
      name: "${body.orderType}"
    resource:
      stockId: "${stockId}"Tratteria can call out to an AuthZEN API to evaluate whether execution should proceed. This specifies how to construct the request for access evaluation.

The above specifies how to generate purpose and authorization details for the POST api/order/trade/{#stockId} API, and it specifies who (the order, catalog, and stocks services) and how to verify the generated TraT. Additionally, the accessEvaluation section specifies how to perform access evaluations for the API.

To quickly see Tratteria in action, checkout the Quickstart Guide.

To integrate Tratteria into your microservice application, start by installing Tratteria, which can be deployed in environments with or without a service mesh.

Acknowledgments

This documentation and the underlying technology are based on the concepts and draft developed by Atul Tulshibagwale (SGNL), George Fletcher (Capital One), and Pieter Kasselman (Microsoft).

Contact Us

For inquiries about Tratteria, please email us at: tratteria@sgnl.ai