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/authzed_schema.png b/src/current/images/v26.1/authzed_schema.png new file mode 100644 index 00000000000..2a91ab9d1d2 Binary files /dev/null and b/src/current/images/v26.1/authzed_schema.png differ 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..e4e7a8a46a1 --- /dev/null +++ b/src/current/v26.1/authzed-integration-guide.md @@ -0,0 +1,404 @@ +--- +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 a platform focused exclusively on *authorization*. 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 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). Authorization requests (for example, checkPermission, lookupResources) are resolved via a dispatcher that traverses the permission graph. + +SpiceDB is available in multiple forms depending on deployment and support needs: + +- [SpiceDB (Open Source)](https://authzed.com/spicedb): The foundational, community-driven version of the authorization engine, free to use and self-hosted under the Apache 2.0 license. +- [SpiceDB Enterprise](https://authzed.com/products/spicedb-enterprise): A self-managed enterprise edition that includes audit logging, fine-grained API control, FIPS-validated cryptography, and dedicated support. +- [AuthZed Dedicated](https://authzed.com/products/authzed-dedicated): A fully managed, single-tenant SaaS offering that provides all enterprise features along with global, regionally distributed deployments and integrated APIs for permission filtering. +- [AuthZed Cloud](https://authzed.com/products/authzed-cloud): A multi-tenant managed platform designed for teams that want to start quickly without operational overhead. + +Across all these tiers, CockroachDB provides resiliency and scalability as SpiceDB's underlying datastore. + +## Set up a joint CockroachDB/AuthZed environment + +Imagine that you’re building a global content management application that uses SpiceDB, as the access control system backed by CockroachDB across multiple regions. This tutorial walks you through the manual setup of a joint CockroachDB/AuthZed environment. + +### Before you begin + +To complete this tutorial, you will need: + +- A local copy of a [supported CockroachDB binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). +- Network access from your SpiceDB runtime to port `26257`. + +### 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. + +#### Create a secure 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 %}). + +#### Create a CockroachDB Self-Hosted cluster on AWS +You can manually deploy a multi-node, self-hosted CockroachDB cluster on Amazon's AWS EC2 platform, using AWS's managed load-balancing service to distribute client traffic. + +Learn how to [deploy a CockroachDB cluster on AWS]({% link {{ page.version.version }}/deploy-cockroachdb-on-aws.md %}). + +#### Create 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 %}). + +### Step 2. Create a database for AuthZed + +Before integrating AuthZed with CockroachDB, you will need to set up a dedicated database. + +1. Replace `{certs-dir}` with the certificates directory that you established during the cluster setup, and `{crdb-fqdn}` with your CockroachDB load balancer domain name. Then run the following command: + + {% include_cached copy-clipboard.html %} + ~~~shell + cockroach sql --certs-dir={certs-dir} --host={crdb-fqdn}:26257 + ~~~ + +1. Once connected to the SQL shell, [create the following database]({% link {{page.version.version}}/create-database.md %}): + + {% include_cached copy-clipboard.html %} + ~~~sql + CREATE DATABASE spicedb; + ~~~ + +1. [Create a user]({% link {{page.version.version}}/create-user.md %}) `authz` and [grant them privileges]({% link {{page.version.version}}/grant.md %}) for the `spicedb` database: + + {% include_cached copy-clipboard.html %} + ~~~sql + CREATE USER authz WITH PASSWORD 'securepass'; + GRANT ALL ON DATABASE spicedb TO authz; + ~~~ + +### Step 3. Install and configure SpiceDB + +1. Install the SpiceDB binary for your given system (supported systems include [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), and [Windows](https://authzed.com/docs/spicedb/getting-started/install/windows)). + +2. Define your CockroachDB cluster as the datastore for SpiceDB. Replace the `{crdb-uri}` placeholder with your cluster URI, and replace the `{client-authz-cert}`, `{client-authz-key}`, and `{ca-cert}` placeholders with paths to the relevant certificate files in your certs directory: + + {% include_cached copy-clipboard.html %} + ~~~ shell + spicedb datastore migrate head \ + --datastore-engine=cockroachdb \ + --datastore-conn-uri="postgres://authz:securepass@{crdb-uri}:26257/spicedb?sslmode=verify-full&sslcert={client-authz-cert}&sslkey={client-authz-key}&sslrootcert={ca-cert}" + ~~~ + +3. Start the SpiceDB service pointing at your CockroachDB URI. Replace the same placeholders as those in the preceding command. In addition, define a `{preshared-key}`, to be used in further commands: + + {% include_cached copy-clipboard.html %} + ~~~ shell + spicedb serve \ + --grpc-preshared-key="{preshared-key}" \ + --http-enabled=true \ + --datastore-engine=cockroachdb \ + --datastore-conn-uri="postgres://authz:securepass@{crdb-uri}:26257/spicedb?sslmode=verify-full&sslcert={client-authz-cert}&sslkey={client-authz-key}&sslrootcert={ca-cert}" + ~~~ + +### Step 4. Install the AuthZed CLI + +1. To interact with SpiceDB through the zed (AuthZed) CLI, [install the latest binary releases of zed](https://authzed.com/docs/spicedb/getting-started/installing-zed). + +2. Once installed, connect to the SpiceDB instance exposed in the client with the following command. For local development, you can use the `--insecure` flag to connect over plaintext. Be sure to use the same `{preshared-key}` that you used in the preceding step. Replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance: + + {% include_cached copy-clipboard.html %} + ~~~ shell + zed context set my_context {spicedb-ip}:50051 {preshared-key} --insecure + ~~~ + +3. Check that the command worked by running: + + {% include_cached copy-clipboard.html %} + ~~~ shell + zed version + ~~~ + + If the output indicates that the server version is `unknown`, then your CLI was unable to connect. You may need to verify the values in previous steps, such as the `{preshared-key}`, the IP or the port that your SpiceDB instance is running on. + + When successfully executed, `zed version` should output something similar to the following: + + ~~~ + client: zed v0.31.1 + service: v1.45.4 + ~~~ + +You can interact with SpiceDB using the AuthZed CLI, with the [HTTP API](https://authzed.com/docs/spicedb/api/http-api) or with the [gRPC API](https://buf.build/authzed/api/docs/main:authzed.api.v1). The remaining instructions will demonstrate how to use both the AuthZed CLI and the HTTP API to complete the integration. + +### Step 5. Define the authorization schema + +The first step in developing an authorization relationship schema is defining one or more object types. For example, you could define the following object relationships: + +AuthZed sample schema diagram + +The main two items in this example are the `user` and `document` objects. The `user` can be a `viewer`, an `editor` or an `admin`. The definition gives the `remove` permission to the `admin` role only. To `edit` a file the user must be either an `editor` or an `admin`. The permission to `view` a document is set for the `viewer`, `editor` and `admin` roles. + +#### Use the AuthZed CLI + +1. Define the schema by writing the following file: + + {% include_cached copy-clipboard.html %} + ~~~ + definition user {} + + definition document { + relation editor: user + relation viewer: user + relation admin: user + + permission view = viewer + editor + admin + permission edit = editor + admin + permission remove = admin + } + ~~~ + + Save this file as `schema.zed`. + +1. Apply the schema to SpiceDB, pointing to the saved `schema.zed` file. + + {% include_cached copy-clipboard.html %} + ~~~ shell + zed schema write ./schema.zed + ~~~ + +1. To verify that this has worked, run the following command, which should print the applied schema: + + {% include_cached copy-clipboard.html %} + ~~~ shell + zed schema read + ~~~ + +#### Use the HTTP API + +Embed the schema definition within a [`WriteSchemaRequest`](https://authzed.com/docs/spicedb/api/http-api#/Schema/SchemaService_WriteSchema) body, making sure to replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance, and the `{preshared-key}` placeholder with value defined in [Step 3](#step-3-install-and-configure-spicedb): + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --location 'http://{spicedb-ip}:8443/v1/schema/write' \ +--header 'Content-Type: application/json' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer {preshared-key}' \ +--data '{ +"schema": "definition user {} \n definition document { \n relation editor: user \n relation viewer: user \n relation admin: user \n permission view = viewer + editor + admin \n permission edit = editor + admin \n permission remove = admin \n}" +}' +~~~ + +If successful, that request will return a response which includes a token: + +~~~ +{"writtenAt":{"token":"GhUKEzE3NTgxMjkyOTM0MDE2MDYxNDA="}} +~~~ + +### Step 6. Define authorization relationships + +In SpiceDB, relationships are represented as tuples. Each tuple contains a _resource_, a _relation_ and a _subject_. In this example, the resource is the name of a `document`, the relation is either `admin`, `viewer` or `editor`, and the subject is the name of a `user`. + +In this scenario, make user `alice` an `admin` for `doc1`. This means that she can `view`, `edit`, and `remove` the document. Then make user `bob` a `viewer` for `doc1`. This means he can `view` the document. + +#### Use the AuthZed CLI + +Define a new relationship for a `document` called `doc1`. Use the following command to make `alice` an `admin` for `doc1`: + +{% include_cached copy-clipboard.html %} +~~~ shell +zed relationship touch document:doc1 admin user:alice +~~~ + +Define a new relationship for `doc1`. Use the following command to make `bob` a `viewer` for `doc1`: + +{% include_cached copy-clipboard.html %} +~~~ shell +zed relationship touch document:doc1 viewer user:bob +~~~ + +#### Use the HTTP API + +Define the relationships in a [`WriteRelationshipsRequest`](https://authzed.com/docs/spicedb/api/http-api#/Permissions/PermissionsService_WriteRelationships) body, making sure to replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance, and the `{preshared-key}` placeholder with value defined in [Step 3](#step-3-install-and-configure-spicedb): + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --location 'http://{spicedb-ip}:8443/v1/relationships/write' \ +--header 'Content-Type: application/json' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer {preshared-key}' \ +--data '{ + "updates": [ + { + "operation": "OPERATION_TOUCH", + "relationship": { + "resource": { + "objectType": "document", + "objectId": "doc1" + }, + "relation": "admin", + "subject": { + "object": { + "objectType": "user", + "objectId": "alice" + } + } + } + }, + { + "operation": "OPERATION_TOUCH", + "relationship": { + "resource": { + "objectType": "document", + "objectId": "doc1" + }, + "relation": "viewer", + "subject": { + "object": { + "objectType": "user", + "objectId": "bob" + } + } + } + } + ] +}' +~~~ + +If successful, that request will return a response which includes a token: + +~~~ +{"writtenAt":{"token":"GhUKEzE3NTgxMjk3MDg2NTc4MDQ5ODk="}} +~~~ + +## Test the CockroachDB/AuthZed Integration + +Once both CockroachDB and AuthZed are provisioned and configured, and the authorization relationships have been defined in SpiceDB, validate that the relationships are accessible in the CockroachDB data store. + +### Check user permissions + +Verify that AuthZed has captured the authorization data that you have defined. + +#### Use the AuthZed CLI + +To check that our schema is working correctly, issue `check` requests. As `bob` is only a `viewer` for `doc1`, you can expect him to have the `view` permission but not the `edit` or `remove` permissions: + +{% include_cached copy-clipboard.html %} +~~~ shell +zed permission check document:doc1 view user:bob +# true +~~~ + +{% include_cached copy-clipboard.html %} +~~~ shell +zed permission check document:doc1 edit user:bob +# false +~~~ + +Because `alice` is an `admin`, she has all permissions: + +{% include_cached copy-clipboard.html %} +~~~ shell +zed permission check document:doc1 view user:alice +# true +~~~ + +{% include_cached copy-clipboard.html %} +~~~ shell +zed permission check document:doc1 remove user:alice +# true +~~~ + +{% include_cached copy-clipboard.html %} +~~~ shell +zed permission check document:doc1 edit user:alice +# true +~~~ + +#### Use the HTTP API + +Define the permission that you want to check within a [`CheckPermissionRequest`](https://authzed.com/docs/spicedb/api/http-api#/Permissions/PermissionsService_CheckPermission) body. This check includes a `user`, a `resource`, and an `action`. Make sure to replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance, and the `{preshared-key}` placeholder with value defined in [Step 3](#step-3-install-and-configure-spicedb): + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --location 'http://{spicedb-ip}:8443/v1/permissions/check' \ +--header 'Content-Type: application/json' \ +--header 'Accept: application/json' \ +--header 'Authorization: Bearer {preshared-key}' \ +--data '{ + "consistency": { + "minimizeLatency": true + }, + "resource": { + "objectType": "document", + "objectId": "doc1" + }, + "permission": "view", + "subject": { + "object": { + "objectType": "user", + "objectId": "bob" + } + } +}' +~~~ + +If successful, that request will return a response which includes a token. That token will include a `permissionship` item, that explains whether the given `user` has permission to perform the given `action` on the given `resource`: + +~~~ +{"checkedAt":{"token":"GhUKEzE3NTgxMjk5NTAwMDAwMDAwMDA="}, "permissionship":"PERMISSIONSHIP_NO_PERMISSION"} +~~~ + +Send another `CheckPermissionRequest` for each permission that you want to check. + +### Access AuthZed data with CockroachDB SQL + +To demonstrate that CockroachDB is being used as the data store for this SpiceDB instance, access the same authorization data using CockroachDB SQL. + +1. Go to your [CockroachDB SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}). + +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. Much of this data, including `object_id`, `relation`, and `userset_object_id`, should match that provided in the relation tuple in [Step 6](#step-6-define-authorization-relationships) of the setup instructions: + + ~~~ + 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) + ~~~ + +### Next steps +These tests confirm that AuthZed is successfully using CockroachDB as its data store. If you get the expected results from these tests, then your 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 %})