diff --git a/pages/authzed/guides/_meta.ts b/pages/authzed/guides/_meta.ts new file mode 100644 index 0000000..845c8f7 --- /dev/null +++ b/pages/authzed/guides/_meta.ts @@ -0,0 +1,4 @@ +export default { + "picking-a-product": "Picking a Product", + cloud: "Getting Started with Authzed Cloud", +}; diff --git a/pages/authzed/guides/cloud.mdx b/pages/authzed/guides/cloud.mdx new file mode 100644 index 0000000..b9efb20 --- /dev/null +++ b/pages/authzed/guides/cloud.mdx @@ -0,0 +1,65 @@ +import { Callout } from "nextra/components"; +import YouTube from "react-youtube"; + +# Getting Started with AuthZed Cloud + +This page provides a guide on how to get up and running with a permission system in AuthZed Cloud. + +If you prefer a guide in video format, watch this: + + + +## Create a Permissions System on AuthZed Cloud + +Sign in to [AuthZed Cloud](https://app.authzed.cloud) and click on the **+Create** button to create a Permissions System (PS) and fill in the necessary details: + +- The type can be either "Production" or "Development". +- Give it a name. +- Choose the underlying datastore. +- The update channel can be either be `rapid` or `regular` which determines the behavior of automatic updates when new SpiceDB releases are made available: + - `rapid` gets the latest release immediately. + - `regular` is one release behind. +- Add SpiceDB deployments: + - Give them a name. + - Choose the region where the deployment will live. + - Choose the number of vCPUs for your deployment. The recommendation is to start with 2 vCPUs and then monitor the Metrics and change it based on your workload. + - Choose the number of replicas to deploy SpiceDB with primarily read workloads. The recommendation is 3 but will depend on your latency requirements. + +## Configuring Access + +Before using the Permissions System, let's configure access to it. +This functionality enables organizations to apply the principle of least-privilege to services accessing SpiceDB. +For example, read-only tokens can be created for services that should never need to write to SpiceDB. +Read more about it [here](https://authzed.com/docs/authzed/concepts/restricted-api-access) + +Let’s start by creating a **Service Account** which is something that represents your unique workload. +We recommend creating a Service Account for each application that will access the SpiceDB API. +Add a name such as `blog-app` and a description before hitting Save. + +Now let’s create a **token**. +Tokens are long-lived credentials for Service Accounts. +SpiceDB clients must provide a Token in the Authorization header of an API request to perform actions granted to the Service Account. +Click on the `blog-app` service account you just created and then the Tokens item in the menu. +Create a token by providing a name and description. + +Let’s now provide a **Role** and attach a **Policy** to that Role. +A Role defines rules for accessing the SpiceDB API. +Roles are bound to Service Accounts. +Click the Roles -> Create Role and provide a name and a description. +Add the following permissions for this demo: + +``` +ReadSchema +WriteSchema +DeleteRelationships +ReadRelationships +WriteRelationships +CheckPermission +``` + +Finally, let’s create a Policy. +Policies are what bind Roles to a Service Account. +Click on Policies -> Create policy. +Provide a name and a description and pick the Service Account and Role created in the steps above to bind the two. + +You’re now ready to use your Permissions System! diff --git a/pages/spicedb/concepts/commands.mdx b/pages/spicedb/concepts/commands.mdx index 9f6f505..daa3c64 100644 --- a/pages/spicedb/concepts/commands.mdx +++ b/pages/spicedb/concepts/commands.mdx @@ -27,13 +27,12 @@ A database that stores and computes permissions ### Children commands -- [spicedb datastore](#reference-spicedb-datastore) - datastore operations -- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol -- [spicedb man](#reference-spicedb-man) - Generate man page -- [spicedb serve](#reference-spicedb-serve) - serve the permissions database -- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore -- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB - +- [spicedb datastore](#reference-spicedb-datastore) - datastore operations +- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol +- [spicedb man](#reference-spicedb-man) - Generate man page +- [spicedb serve](#reference-spicedb-serve) - serve the permissions database +- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore +- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB ## Reference: `spicedb datastore` @@ -49,11 +48,10 @@ Operations against the configured datastore ### Children commands -- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection -- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available -- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations -- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair - +- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection +- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available +- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations +- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair ## Reference: `spicedb datastore gc` @@ -148,8 +146,6 @@ spicedb datastore gc [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore head` compute the head (latest) database migration revision available @@ -181,8 +177,6 @@ spicedb datastore head [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore migrate` Executes datastore schema migrations for the datastore. @@ -222,8 +216,6 @@ spicedb datastore migrate [revision] [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb datastore repair` Executes a repair operation for the datastore @@ -317,8 +309,6 @@ spicedb datastore repair [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb lsp` serve language server protocol @@ -342,12 +332,10 @@ spicedb lsp [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb man` Generate a man page for SpiceDB. - The output can be redirected to a file and installed to the system: +The output can be redirected to a file and installed to the system: ``` spicedb man > spicedb.1 @@ -355,7 +343,6 @@ Generate a man page for SpiceDB. sudo mandb # Update man page database ``` - ``` spicedb man ``` @@ -368,8 +355,6 @@ spicedb man --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb serve` start a SpiceDB server @@ -557,8 +542,6 @@ spicedb serve [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb serve-testing` An in-memory spicedb server which serves completely isolated datastores per client-supplied auth token used. @@ -620,8 +603,6 @@ spicedb serve-testing [flags] --skip-release-check if true, skips checking for new SpiceDB releases ``` - - ## Reference: `spicedb version` displays the version of SpiceDB @@ -643,6 +624,3 @@ spicedb version [flags] --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") --skip-release-check if true, skips checking for new SpiceDB releases ``` - - - diff --git a/pages/spicedb/getting-started/_meta.ts b/pages/spicedb/getting-started/_meta.ts index c4d9ea8..e75bf0b 100644 --- a/pages/spicedb/getting-started/_meta.ts +++ b/pages/spicedb/getting-started/_meta.ts @@ -5,6 +5,6 @@ export default { "client-libraries": "Client Libraries", "installing-zed": "Installing the CLI", "coming-from": "Coming From", - "protecting-a-blog": "Example: Protecting a Blog Application", + "protecting-a-blog": "Tutorial: Protecting a Blog Application", faq: "FAQ", }; diff --git a/pages/spicedb/getting-started/protecting-a-blog.mdx b/pages/spicedb/getting-started/protecting-a-blog.mdx index 23569d7..8fa18b1 100644 --- a/pages/spicedb/getting-started/protecting-a-blog.mdx +++ b/pages/spicedb/getting-started/protecting-a-blog.mdx @@ -1,15 +1,11 @@ import { Callout, Tabs } from "nextra/components"; -import YouTube from "react-youtube"; -# Protecting a Blog Application +# Tutorial: Protecting a Blog Application -This guide walks through the steps required to deeply integrate an application with Authzed or SpiceDB. -Not all software requires this level of integration, but it is preferable for greenfield applications or applications that are central in an architecture with multiple services. +This guide walks through the steps required to integrate end-to-end an application with SpiceDB. We are going to pretend that our application is a blog. Instead of introducing an unfamiliar example app and altering various locations in its code, this guide is written such that each step is a standalone snippet of code that demonstrates an integration point and finding where those points exist in your codebase is an exercise left to the reader. -Scroll to the bottom of this page for a video walkthrough of creating a Permissions System using AuthZed Cloud. - ## Prerequisites One of: @@ -29,77 +25,17 @@ docker run --rm -p 50051:50051 authzed/spicedb serve --grpc-preshared-key "t_you [SpiceDB]: https://github.com/authzed/spicedb [running instance]: /spicedb/getting-started/installing-spicedb -## Create a Permissions System on AuthZed Cloud - -Sign in to [AuthZed Cloud](https://app.authzed.cloud) and click on the **+Create** button to create a Permissions System (PS) and fill in the necessary details: - -- The type of the PS can be either Production or Development -- Give it a name -- Choose a datastore. -- The update channel can be either be `rapid` or `regular` which determines the behavior of automatic updates when new SpiceDB releases are made available -- The Deployments tab has the following options: - - The name of the deployment - - A dropdown for the region in which the deployment is made. - Currently `us-east-1` and `eu-central-1` are available - - The number of vCPUs for your deployment. - The recommendation is to start with 2 vCPUs and then monitor the Metrics and change it based on your workload - - The number of replicas to deploy SpiceDB with primarily read workloads. - The recommendation is 3 but will depend on your latency requirements. - -Click the Save button to create a Permissions System - -## Configuring Access - -Before using the Permissions System, let's configure access to it. -This functionality enables organizations to apply the principle of least-privilege to services accessing SpiceDB. -For example, read-only tokens can be created for services that should never need to write to SpiceDB. -Read more about it [here](https://authzed.com/docs/authzed/concepts/restricted-api-access) - -Let’s start by creating a **Service Account** which is something that represents your unique workload. -We recommend creating a Service Account for each application that will access the SpiceDB API. -Add a name such as `blog-app` and a description before hitting Save. - -Now let’s create a **token**. -Tokens are long-lived credentials for Service Accounts. -SpiceDB clients must provide a Token in the Authorization header of an API request to perform actions granted to the Service Account. -Click on the `blog-app` service account you just created and then the Tokens item in the menu. -Create a token by providing a name and description. - -Let’s now provide a **Role** and attach a **Policy** to that Role. -A Role defines rules for accessing the SpiceDB API. -Roles are bound to Service Accounts. -Click the Roles -> Create Role and provide a name and a description. -Add the following permissions for this demo: - -``` -ReadSchema -WriteSchema -DeleteRelationships -ReadRelationships -WriteRelationships -CheckPermission -``` - -Finally, let’s create a Policy. -Policies are what bind Roles to a Service Account. -Click on Policies -> Create policy. -Provide a name and a description and pick the Service Account and Role created in the steps above to bind the two. - -You’re now ready to use AuthZed Cloud Permissions System! - -## Client Installation +## Installing the Client The first step to integrating any software is ensuring you have an API client. Each client is installed with its ecosystem's package management tools: -You can also interact with the Permissions System using [zed](https://github.com/authzed/zed) - the command-line client for managing SpiceDB clusters. - ```sh brew install authzed/tap/zed -zed context set +zed context set ``` @@ -150,27 +86,21 @@ dependencies { -You can find the endpoint on the AuthZed Cloud dashboard. -Click on the Permissions System that's just been created and locate the **Connect** button. -Copy the zed command and paste it in your terminal. -It should look like this: + -``` -zed context set us-east-1 acme-permission-system-xyz.aws.authzed.cloud:443 -``` + If you are using [AuthZed Cloud], + click on the **Connect** button on the dashboard to get both the endpoint that you use to connect to your permission system, + and the full `zed` command needed to connect to it. -where `us-east-1` is the name of the PS followed by the endpoint. -Replace the `token-here` with the token that was generated in the earlier step. - -## Defining and Applying a Schema + -Regardless of whether or not you have a preexisting schema written, integrating a new application will typically require you add new definitions to the [Schema]. +## Writing a Schema -[Schema]: /spicedb/concepts/schema +[Schemas] define the objects in our application, their relations, and their checkable permissions that will be available to be used with the Permission System. -As a quick recap, Schemas define the objects, their relations, and their checkable permissions that will be available to be used with the Permission System. +[Schemas]: /spicedb/concepts/schema -We'll be using the following blog example throughout this guide: +We'll be using the following schema to model our blog application: ```zed definition user {} @@ -190,14 +120,9 @@ Feel free to modify and test your own experiments in the [playground]. [playground]: https://play.authzed.com/s/mVBBpf5poNd8/schema -With a schema designed, we can now move on to using our client to apply that schema to the Permission System. - - -Similar to applying schema changes for relational databases, all changes to a schema must be backwards compatible. - -In production environments where relations change, you will likely want to write data migrations and apply those changes using a schema migration toolchain. +With a schema designed, we can now move on to using our client to write that schema to the Permission System. - +[migration guide]: ../modeling/migrating-schema @@ -215,6 +140,11 @@ EOF ) ``` + + If, later on, you wish to make updates to this schema, please read the + [migration guide]. + + @@ -384,7 +314,7 @@ public class App { -## Storing Relationships +## Writing Relationships After a permission system has its schema applied, it is ready to have its relationships created, touched, or deleted. Relationships are live instances of relations between objects. @@ -715,31 +645,16 @@ Permissions Systems that have stored relationships are capable of performing per Checks not only test for the existence of direct relationships, but also compute and traverse transitive relationships. For example, in our example schema, writers have both write and read permissions, so there's no need to create a read relationship for a subject that is already a writer. - -In addition to checking _permissions_, it is also possible to perform checks on _relations_ to determine membership. - -However, this goes against best practice: permissions can be redefined in backwards compatible ways by changing the schema, so it's ideal to rely on permissions as the contract between SpiceDB and applications querying SpiceDB. - - - - -When doing a permission check, in order to get read-after-write consistency, you must provide a [ZedToken] from the WriteRelationships response or request [full consistency]. - -[ZedToken]: /spicedb/concepts/consistency#zedtokens -[full consistency]: /spicedb/concepts/consistency#fully-consistent - - - -The following examples demonstrate the transitive property of checks: +Let's perform some permission checks: ```sh -zed permission check post:1 read user:emilia --revision "zedtokenfromwriterel" # true -zed permission check post:1 write user:emilia --revision "zedtokenfromwriterel" # true -zed permission check post:1 read user:beatrice --revision "zedtokenfromwriterel" # true -zed permission check post:1 write user:beatrice --revision "zedtokenfromwriterel" # false +zed permission check post:1 read user:emilia # true +zed permission check post:1 write user:emilia # true +zed permission check post:1 read user:beatrice # true +zed permission check post:1 write user:beatrice # false ``` @@ -1110,6 +1025,17 @@ public class App { -Here's a video walkthrough of creating a Permissions System on AuthZed Cloud: + + In addition to checking _permissions_, it is also possible to perform checks on _relations_ to determine membership. + + However, this goes against best practice: permissions can be redefined in backwards compatible ways by changing the schema, so it's ideal to rely on permissions as the contract between SpiceDB and applications querying SpiceDB. - + + + + When doing a permission check, in order to get read-after-write consistency, you must provide a [ZedToken] from the WriteRelationships response or request [full consistency]. + + [ZedToken]: /spicedb/concepts/consistency#zedtokens + [full consistency]: /spicedb/concepts/consistency#fully-consistent + + diff --git a/pages/spicedb/ops/_meta.ts b/pages/spicedb/ops/_meta.ts index 841b291..532c6bf 100644 --- a/pages/spicedb/ops/_meta.ts +++ b/pages/spicedb/ops/_meta.ts @@ -5,7 +5,10 @@ export default { data: "Writing data to SpiceDB", performance: "Improving Performance", observability: "Observability Tooling", - "spicedb-langchain-langgraph-rag": "Secure your RAG Pipelines using LangChain & LangGraph", - "ai-agent-authorization": "Tutorial: Authorization for AI Agents using SpiceDB", - "secure-rag-pipelines": "Tutorial: Securing RAG Pipelines with SpiceDB" + "load-testing": "Load Testing", + "spicedb-langchain-langgraph-rag": + "Secure your RAG Pipelines using LangChain & LangGraph", + "ai-agent-authorization": + "Tutorial: Authorization for AI Agents using SpiceDB", + "secure-rag-pipelines": "Tutorial: Securing RAG Pipelines with SpiceDB", }; diff --git a/pages/spicedb/ops/spicedb-langchain-langgraph-rag.mdx b/pages/spicedb/ops/spicedb-langchain-langgraph-rag.mdx index cc54186..3602929 100644 --- a/pages/spicedb/ops/spicedb-langchain-langgraph-rag.mdx +++ b/pages/spicedb/ops/spicedb-langchain-langgraph-rag.mdx @@ -22,7 +22,7 @@ The library implements **post-filter authorization**, meaning: 1. Retrieve the best semantic matches. 2. Filter them using SpiceDB permission checks. -3. Feed *only authorized documents* to the LLM. +3. Feed _only authorized documents_ to the LLM. --- @@ -56,7 +56,6 @@ sys.path.append("/path/to/spicedb-rag-authorization") ### Create a SpiceDB schema - We will use the [zed](https://github.com/authzed/zed) CLI to write schema and relationships. In your production application, this would be replaced with an API call. @@ -175,9 +174,9 @@ LangGraph is ideal for more advanced AI systems, such as conversational RAG assi Our [library](https://github.com/sohanmaheshwar/spicedb-rag-authorization) provides: -- `RAGAuthState` — a TypedDict defining the required state fields -- `create_auth_node()` — auto-configured authorization node -- `AuthorizationNode` — reusable class-based node +- `RAGAuthState` — a TypedDict defining the required state fields +- `create_auth_node()` — auto-configured authorization node +- `AuthorizationNode` — reusable class-based node --- @@ -329,16 +328,16 @@ graph.add_node("auth_kb", kb_auth) The library exposes: -- number of retrieved documents -- number authorized -- denied resource IDs -- latency per SpiceDB check +- number of retrieved documents +- number authorized +- denied resource IDs +- latency per SpiceDB check ### In LangChain ```python auth = SpiceDBAuthFilter(..., subject_id="alice", return_metrics=True) -result = await auth.ainvoke(docs) +result = await auth.ainvoke(docs) print(result.authorized_documents) print(result.total_authorized) @@ -368,7 +367,7 @@ print(result["auth_results"]["check_latency_ms"]) ## 7. Complete Example -See the full example in the [repo here]() +See the full example in the [repo here](https://github.com/sohanmaheshwar/spicedb-rag-authorization) - `langchain_example.py` - `README_langchain.md` @@ -379,4 +378,4 @@ See the full example in the [repo here](