diff --git a/src/current/_includes/v26.1/sidebar-data/integrate.json b/src/current/_includes/v26.1/sidebar-data/integrate.json index 275792e2114..7064fc2e04f 100644 --- a/src/current/_includes/v26.1/sidebar-data/integrate.json +++ b/src/current/_includes/v26.1/sidebar-data/integrate.json @@ -2,21 +2,16 @@ "title": "Integrate", "is_top_level": true, "items": [ + { + "title": "AuthZed", + "urls": [ + "/${VERSION}/authzed-integration-guide.html" + ] + }, { "title": "Ory", - "items": [ - { - "title": "Ory Overview", - "urls": [ - "/${VERSION}/ory-overview.html" - ] - }, - { - "title": "Integrate with Ory", - "urls": [ - "/${VERSION}/ory-integration-guide.html" - ] - } + "urls": [ + "/${VERSION}/ory-integration-guide.html" ] } ] diff --git a/src/current/images/v26.1/integrate-ory-hydra-flow.png b/src/current/images/v26.1/integrate-ory-hydra-flow.png deleted file mode 100644 index fbf9703207a..00000000000 Binary files a/src/current/images/v26.1/integrate-ory-hydra-flow.png and /dev/null differ diff --git a/src/current/images/v26.1/integrate-ory-kratos-registration.png b/src/current/images/v26.1/integrate-ory-kratos-registration.png deleted file mode 100644 index 75d40743527..00000000000 Binary files a/src/current/images/v26.1/integrate-ory-kratos-registration.png and /dev/null differ diff --git a/src/current/images/v26.1/integrate-ory-oauth2-flow.png b/src/current/images/v26.1/integrate-ory-oauth2-flow.png deleted file mode 100644 index ec6c3cd4ad3..00000000000 Binary files a/src/current/images/v26.1/integrate-ory-oauth2-flow.png and /dev/null differ diff --git a/src/current/images/v26.1/integrate-ory-permission-graph.png b/src/current/images/v26.1/integrate-ory-permission-graph.png deleted file mode 100644 index cc7eccd5e85..00000000000 Binary files a/src/current/images/v26.1/integrate-ory-permission-graph.png and /dev/null differ diff --git a/src/current/v26.1/authzed-integration-guide.md b/src/current/v26.1/authzed-integration-guide.md new file mode 100644 index 00000000000..03d68c058c6 --- /dev/null +++ b/src/current/v26.1/authzed-integration-guide.md @@ -0,0 +1,164 @@ +--- +title: Integrate CockroachDB with AuthZed +summary: Learn how to provision a joint AuthZed and CockroachDB environment. +toc: true +docs_area: Integrate +--- + +[AuthZed](https://authzed.com/) is an authorization platform. In contrast to authentication, which verifies a user's identity, authorization decides a user's access rights for resources once their identity is known. AuthZed centralizes, unifies, and scales this core security layer so that developers don’t have to implement their own permission logic in every application. + +SpiceDB is the core engine behind all AuthZed products. It is designed to be entirely agnostic to authentication solutions and identity providers. SpiceDB is a graph engine that centrally stores authorization data (relationships and permissions). + +CockroachDB's scalability and resiliency make it well-suited to serve as SpiceDB's [underlying datastore](https://authzed.com/docs/spicedb/concepts/datastores#cockroachdb). AuthZed has standardized its managed services on CockroachDB, and they recommend CockroachDB for self-hosted, multi-region deployments. + +This page describes how to configure CockroachDB to work with AuthZed. + +## Before you begin + +Before configuring CockroachDB for AuthZed, refer to the [AuthZed documentation](https://authzed.com/docs) to understand AuthZed's architecture and requirements. + +You will need: + +- A [supported CockroachDB binary]({% link {{ page.version.version }}/install-cockroachdb.md %}) for client connections +- Network access from your SpiceDB runtime to CockroachDB on port `26257` of your CockroachDB host. + +## Step 1. Provision a CockroachDB cluster + +First you need to provision the CockroachDB cluster that AuthZed will use for its services. Choose one of the following methods to create a new CockroachDB cluster, or use an existing cluster and skip to Step 2. + +Be sure to create a **secure** cluster. This is necessary for the user creation step of this tutorial. + +#### Deploy a CockroachDB Self-hosted cluster +You can manually deploy a multi-node, self-hosted CockroachDB cluster, either on-premises or on various cloud platforms. + +Learn how to [deploy a self-hosted CockroachDB cluster]({% link {{ page.version.version }}/manual-deployment.md %}). + +#### Deploy a CockroachDB Cloud cluster +CockroachDB Cloud is a fully-managed service run by Cockroach Labs, which simplifies the deployment and management of CockroachDB. + +[Sign up for a CockroachDB Cloud account](https://cockroachlabs.cloud) and [create a cluster]({% link cockroachcloud/create-your-cluster.md %}) using [trial credits]({% link cockroachcloud/free-trial.md %}). + +#### Deploy a cluster locally +If you have the CockroachDB binary installed locally, you can manually deploy a multi-node, self-hosted CockroachDB cluster on your local machine. + +Learn how to [deploy a CockroachDB cluster locally]({% link {{ page.version.version }}/secure-a-cluster.md %}). + +## Step 2. Create a database and user for AuthZed + +1. Connect to your CockroachDB cluster using the SQL client. Replace `{certs-dir}` with your certificates directory and `{cluster-host}` with your cluster hostname: + + {% include_cached copy-clipboard.html %} + ~~~shell + cockroach sql --certs-dir={certs-dir} --host={cluster-host}:26257 + ~~~ + +1. [Create a database]({% link {{page.version.version}}/create-database.md %}) for AuthZed: + + {% include_cached copy-clipboard.html %} + ~~~sql + CREATE DATABASE spicedb; + ~~~ + +1. [Create a user]({% link {{page.version.version}}/create-user.md %}) for AuthZed and [grant privileges]({% link {{page.version.version}}/grant.md %}) on the database: + + {% include_cached copy-clipboard.html %} + ~~~sql + CREATE USER authzed_user WITH PASSWORD 'your_secure_password'; + GRANT ALL ON DATABASE spicedb TO authzed_user; + ~~~ + +## Step 3. Configure the connection string + +When configuring SpiceDB to use CockroachDB, you will need to provide a connection URI. The connection string format for CockroachDB is: + +~~~ +postgres://authzed_user:your_secure_password@{cluster-host}:26257/spicedb?sslmode=verify-full&sslcert={client-cert}&sslkey={client-key}&sslrootcert={ca-cert} +~~~ + +Replace the following placeholders: + +- `{cluster-host}`: Your CockroachDB cluster hostname or load balancer address +- `{client-cert}`: Path to the client certificate file +- `{client-key}`: Path to the client key file +- `{ca-cert}`: Path to the CA certificate file + +For CockroachDB {{ site.data.products.cloud }} clusters, refer to [Connect to a CockroachDB {{ site.data.products.cloud }} Cluster]({% link cockroachcloud/connect-to-your-cluster.md %}) for connection details. + +## Step 4. Install and configure SpiceDB + +For instructions on installing and configuring SpiceDB with CockroachDB as the datastore, refer to AuthZed's SpiceDB documentation: + +- Install SpiceDB ([macOS](https://authzed.com/docs/spicedb/getting-started/install/macos), [Docker](https://authzed.com/docs/spicedb/getting-started/install/docker), [Kubernetes](https://authzed.com/docs/spicedb/getting-started/install/kubernetes), [Ubuntu/Debian](https://authzed.com/docs/spicedb/getting-started/install/debian), [RHEL/CentOS](https://authzed.com/docs/spicedb/getting-started/install/rhel), [Windows](https://authzed.com/docs/spicedb/getting-started/install/windows)) +- [Configure SpiceDB to use CockroachDB](https://authzed.com/docs/spicedb/concepts/datastores#cockroachdb) +- [Deploy SpiceDB with CockroachDB](https://authzed.com/docs/spicedb/concepts/datastores#deployment-process) + +Make sure to use the connection string defined in [Step 3](#step-3-configure-the-connection-string) in your SpiceDB configuration. + + +## Step 5. Define authorization data + +Once SpiceDB is deployed with CockroachDB, you can use AuthZed's CLI and API endpoints to define authorization schemas, create relationships, and check permissions. To learn how to define this authorization data, refer to the [SpiceDB documentation](https://authzed.com/docs/spicedb/getting-started/first-steps). + +## Step 6. Verify the integration + +After configuring SpiceDB to use CockroachDB, and using AuthZed's tools to define authorization data, you can verify that the authorization data has been stored in CockroachDB: + +1. Connect to your CockroachDB cluster using the [SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}): + + {% include_cached copy-clipboard.html %} + ~~~shell + cockroach sql --certs-dir={certs-dir} --host={cluster-host}:26257 + ~~~ + +1. Run the following query to verify the accessibilty of the AuthZed schema in CockroachDB: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SELECT namespace, serialized_config FROM public.namespace_config; + ~~~ + + The result set contains data about the permission: + + ~~~ + -[ RECORD 1 ] + namespace | document + serialized_config | \x0a08646f63756d656e7412610a06656469746f721a130a110a04757365722a04080310151a032e2e2e22340a320a2c747970652e676f6f676c65617069732e636f6d2f696d706c2e76312e52656c6174696f6e4d65746164617461120208012a04080310043a06656469746f7212610a067669657765721a130a110a04757365722a04080410151a032e2e2e22340a320a2c747970652e676f6f676c65617069732e636f6d2f696d706c2e76312e52656c6174696f6e4d65746164617461120208012a04080410043a06766965776572125f0a0561646d696e1a130a110a04757365722a04080510141a032e2e2e22340a320a2c747970652e676f6f676c65617069732e636f6d2f696d706c2e76312e52656c6174696f6e4d65746164617461120208012a04080510043a0561646d696e1294010a0476696577123d2204080710160a350a102a0408071016120812067669657765720a102a040807101f12081206656469746f720a0f2a04080710281207120561646d696e22340a320a2c747970652e676f6f676c65617069732e636f6d2f696d706c2e76312e52656c6174696f6e4d65746164617461120208022a04080710043a1125363135613339316264643736396537311282010a0465646974122b2204080810160a230a102a040808101612081206656469746f720a0f2a040808101f1207120561646d696e22340a320a2c747970652e676f6f676c65617069732e636f6d2f696d706c2e76312e52656c6174696f6e4d65746164617461120208022a04080810043a11253164396466303630383264376535353212790a0672656d6f766512192204080910180a110a0f2a04080910181207120561646d696e22340a320a2c747970652e676f6f676c65617069732e636f6d2f696d706c2e76312e52656c6174696f6e4d65746164617461120208022a0408091004320561646d696e3a11253964363065336431613866616231663722020802 + -[ RECORD 2 ] + namespace | user + serialized_config | \x0a04757365722200 + + Time: 4ms total (execution 4ms / network 0ms) + ~~~ + +1. Run the following query to verify the accessibilty of AuthZed access control data using CockroachDB: + + {% include_cached copy-clipboard.html %} + ~~~ sql + SELECT namespace, object_id, relation, userset_namespace, userset_object_id, timestamp, expires_at FROM public.relation_tuple; + ~~~ + + The result set contains permissions data. This data should match the authorization data you defined with AuthZed: + + ~~~ + namespace | object_id | relation | userset_namespace | userset_object_id | timestamp | expires_at + ------------+-----------+----------+-------------------+-------------------+----------------------------+------------- + document | doc1 | admin | user | alice | 2026-01-06 18:28:21.12613 | NULL + document | doc1 | viewer | user | bob | 2026-01-06 18:28:23.226998 | NULL + (2 rows) + + Time: 4ms total (execution 3ms / network 0ms) + ~~~ + + In this example, user `alice` has been defined as an `admin` for `doc1`, and user `bob` has been defined as a `viewer` for `doc1`. + +If the Cockroach SQL result set matches the authorization data define in [Step 5](#step-5-define-authorization-data), you have verified that CockroachDB has successfully been deployed as the datastore for SpiceDB. + +## Next steps + +Your CockroachDB/AuthZed integration is ready for use in your application. You can begin building authorization and access control features with CockroachDB and AuthZed. + +## See also + +- [Deploy a Local Cluster from Binary (Secure)]({% link {{ page.version.version }}/secure-a-cluster.md %}) +- [Deploy CockroachDB on AWS EC2]({% link {{ page.version.version }}/deploy-cockroachdb-on-aws.md %}) +- [cockroach sql]({% link {{ page.version.version }}/cockroach-sql.md %}) diff --git a/src/current/v26.1/ory-integration-guide.md b/src/current/v26.1/ory-integration-guide.md index 79aaba89e8e..519835121a7 100644 --- a/src/current/v26.1/ory-integration-guide.md +++ b/src/current/v26.1/ory-integration-guide.md @@ -5,13 +5,19 @@ toc: true docs_area: Integrate --- -This tutorial demonstrates how to set up a CockroachDB environment that uses [Ory]({% link {{ page.version.version }}/ory-overview.md %}) for Identity and Access Management (IAM). This page describes the architecture of the integration, then walks through how to perform and test it. +[Ory](https://www.ory.com/) is an open-source identity and access management (IAM) platform that provides modular components for authentication and authorization in distributed systems. Key components include: -By the end of this tutorial, you will have a working environment where Ory’s services (Hydra, Kratos, and Keto) use a CockroachDB cluster for storage. +- [Ory Hydra](https://www.ory.com/hydra) is a server implementation of the [OAuth 2.0 authorization framework](https://oauth.net/2/) and the [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0-final.html). It tracks clients, consent requests, and tokens with strong consistency to prevent replay attacks and duplicate authorizations. +- [Ory Kratos](https://www.ory.com/kratos) stores user identity records, recovery flows, sessions, and login attempts in transactional tables. +- [Ory Keto](https://www.ory.com/keto) provides scalable, relationship-based access control (ReBAC). + +The following diagram shows the relationship between Ory Hydra, Kratos and Keto: + +Ory Architecture Overview ## Integration Architecture Overview -This example environment integrates [Ory Hydra]({% link {{ page.version.version }}/ory-overview.md %}#ory-hydra), [Ory Kratos]({% link {{ page.version.version }}/ory-overview.md %}#ory-kratos), and [Ory Keto]({% link {{ page.version.version }}/ory-overview.md %}#ory-keto). +This example environment integrates Ory Hydra, Ory Kratos, and Ory Keto. In a CockroachDB/Ory integration, each of these components relies on CockroachDB to store their state in a consistent and durable way, enabling them to function correctly even in the presence of partial outages or regional network partitions. Each Ory component is deployed as a stateless service, with its only persistence requirement being a backing SQL database. @@ -39,12 +45,10 @@ In this example environment, both Ory and CockroachDB are deployed within the `u ## Set up a joint CockroachDB/Ory environment -This tutorial walks you through the manual setup of a joint CockroachDB/Ory environment. +This tutorial walks you through the manual setup of a joint CockroachDB/Ory environment. By the end of this tutorial, you will have a working environment where Ory’s services (Hydra, Kratos, and Keto) use a CockroachDB cluster for storage. ### Before you begin -Before starting this tutorial, read the [Ory overview]({% link {{ page.version.version }}/ory-overview.md %}). - To complete this tutorial, you will need: - An [AWS account](https://aws.amazon.com/resources/create-account/) with permissions to create EKS clusters and EC2 resources. @@ -85,9 +89,9 @@ CockroachDB Cloud is a fully-managed service run by Cockroach Labs, which simpli Before integrating Ory components with CockroachDB, you will need to set up separate databases for each service. Each Ory service manages its own schema and migrations: -- [Ory Hydra]({% link {{ page.version.version }}/ory-overview.md %}#ory-hydra) manages OAuth2 clients, consent sessions, access/refresh tokens -- [Ory Kratos]({% link {{ page.version.version }}/ory-overview.md %}#ory-kratos) handles identity, credentials, sessions, verification tokens -- [Ory Keto]({% link {{ page.version.version }}/ory-overview.md %}#ory-keto) stores relation tuples (RBAC/ABAC data) for permissions +- Ory Hydra manages OAuth2 clients, consent sessions, access/refresh tokens +- Ory Kratos handles identity, credentials, sessions, verification tokens +- Ory Keto stores relation tuples (RBAC/ABAC data) for permissions Keeping these in separate databases simplifies maintenance and ensures isolation between identity, OAuth2, and authorization data. @@ -905,7 +909,6 @@ The tests above confirm that each Ory component in this deployment is properly c ## See also -- [Ory Overview]({% link {{ page.version.version }}/ory-overview.md %}) - [Deploy a Local Cluster from Binary (Secure)]({% link {{ page.version.version }}/secure-a-cluster.md %}) - [Deploy CockroachDB on AWS EC2]({% link {{ page.version.version }}/deploy-cockroachdb-on-aws.md %}) - [cockroach sql]({% link {{ page.version.version }}/cockroach-sql.md %}) diff --git a/src/current/v26.1/ory-overview.md b/src/current/v26.1/ory-overview.md deleted file mode 100644 index d7b157fa549..00000000000 --- a/src/current/v26.1/ory-overview.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Ory Overview -summary: Learn about Ory and its component services - Hydra, Kratos, and Keto -toc: true -docs_area: Integrate ---- - -[Ory](https://www.ory.com/) is an open-source identity and access management (IAM) platform that provides modular components for authentication and authorization in distributed systems. Key components include: - -- [Ory Hydra](https://www.ory.com/hydra) for OAuth2 and OIDC flows. -- [Ory Kratos](https://www.ory.com/kratos) for identity management (including users, groups, and organizations). -- [Ory Keto](https://www.ory.com/keto) for fine-grained authorization and relationship-based access control (ReBAC, inspired by Google Zanzibar). - -The following diagram shows the relationship between Ory Hydra, Kratos and Keto: - -Ory Architecture Overview - -## Ory components - -### Ory Hydra - -Ory Hydra is a server implementation of the [OAuth 2.0 authorization framework](https://oauth.net/2/) and the [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0-final.html). It tracks clients, consent requests, and tokens with strong consistency to prevent replay attacks and duplicate authorizations. - -The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. - -The following diagram shows the series of requests made between a user, an application client, and an underlying authorization server: - -OAuth2 Flow - -This sequence diagram illustrates the OAuth 2.0 authorization flow as a series of requests and responses, using Ory Hydra as the authorization server: - -Interaction flow using Ory Hydra - -The diagram depicts the interactions between four key components: - -- **Client**: An application seeking access to protected resources. -- **Resource Owner**: The user. -- **Ory Hydra**: The authorization server. -- **Resource Server**: The API or service that hosts protected resources. - -The flow begins when the Client initiates a request for authorization from the Resource Owner. This typically takes the form of a redirect to a login or consent screen provided by Ory Hydra. The Resource Owner reviews the request and, upon granting access, provides an authorization grant (often an authorization code) to the Client. - -The Client then uses this authorization grant to request an access token from Hydra. Along with the grant, the Client also authenticates itself (using credentials such as a Client ID and secret). Hydra validates the authorization grant and Client credentials. If everything checks out, it responds by issuing an access token to the Client. - -Armed with the access token, the Client then makes a request to the Resource Server, presenting the token as proof of authorization. The Resource Server validates the access token, often by introspecting it via Hydra or verifying its signature if it’s a [JSON Web Token (JWT)](https://www.jwt.io/introduction#what-is-json-web-token) and, if valid, serves the requested protected resource to the Client. - -This flow encapsulates the standard Authorization Code Grant pattern in OAuth 2.0, with Ory Hydra fulfilling the role of an authorization server that manages token issuance, validation, and policy enforcement. - -### Ory Kratos - -Ory Kratos stores user identity records, recovery flows, sessions, and login attempts in transactional tables. - -Each identity can be associated with one or more credentials, stored in the `identity_credentials` table. These credentials define how a user authenticates with the system, such as through a password, social login, or other mechanisms. - -Kratos enables users to sign up and manage their profiles without administrative help. It implements the following flows: - -- Registration -- Login -- Logout -- User Settings -- Account Recovery -- Address Verification -- User-Facing Error -- 2FA / MFA - -The following diagram demonstrates how an API Client might interact with Ory Kratos: - -Kratos Registration - -### Ory Keto - -Ory Keto provides scalable, relationship-based access control (ReBAC). - -In Keto, authorization is checked by evaluating whether a relation tuple exists (directly or through recursive expansion) that permits a given subject to perform a relation on an object in a namespace. This data model is designed for high scalability and flexibility, enabling complex access patterns like group membership, role inheritance, and hierarchical access rights. - -A permission model is a set of rules that define which relations are checked in the database during a permission check. - -Permission checks are answered based on: - -- The data available in CockroachDB, for example: "user Bob is the owner of document X". - -- Permission rules, for example: "All owners of a document can view it". - -When you ask Keto, "Is user Bob allowed to view document X?" the system checks whether Bob has view permission, and then checks whether Bob is the owner of document X. The permission model tells Ory Keto what to check in the database. - -The following diagram illustrates the object relationships that Ory Keto enables: - -Permission Graph - -## Integrate with Ory - -Ory services can use CockroachDB clusters as their persistent data store. Learn how to [create a joint CockroachDB/Ory environment]({% link {{ page.version.version }}/ory-integration-guide.md %}). - -## See also - -- [Integrate CockroachDB with Ory]({% link {{ page.version.version }}/ory-integration-guide.md %})