diff --git a/docs/generating-and-verifying-trats/index.html b/docs/generating-and-verifying-trats/index.html index 171a591..d401aae 100644 --- a/docs/generating-and-verifying-trats/index.html +++ b/docs/generating-and-verifying-trats/index.html @@ -337,7 +337,7 @@
In Delegation Mode, requests are not intercepted; instead, Tratteria agents’ trat-verification API must be called with request data to verify TraTs. This mode is suitable for environments where intercepting requests is not possible or desired, for example, in environments with a service mesh that is already intercepting incoming requests.
+In Delegation Mode, requests are not intercepted; instead, Tratteria agents’ trat-verification API must be called with request data to verify TraTs. 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.
For details on how to verify TraTs using Tratteria agents, visit Tratteria agents readme.
diff --git a/docs/index.html b/docs/index.html index 3bc55ec..c8d0415 100644 --- a/docs/index.html +++ b/docs/index.html @@ -183,38 +183,56 @@Welcome to the documentation for Tratteria, an open-source Transaction Tokens (TraTs) Service. TraTs 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:
+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.
+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 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 provides two ways of verifying TraTs: An interception option and a delegation option
+Tratteria can operate in two modes:
The interception option: Enables existing applications to adopt TraTs without (almost) any code changes. It injects Tratteria sidecar containers into each Kubernetes pod, 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.
+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 approach: 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 approach is more secure, because it does not suffer from the sidecar bypass attack that Kubernetes sidecars in general suffer from. 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.
+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 approach is more secure, because it does not suffer from the sidecar bypass attack that Kubernetes sidecars in general suffer from. 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 is designed to facilitate secure and convenient TraTs issuance and verification in microservices systems.
- -Tratteria supports TraTs generation and verification using Kubernetes resources and Tratteria sidecar agents. 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. Additionally, Tratteria supports access evaluation for external APIs.
+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:
On this page: