From d5564c1881c2b6b9ebaadefa30889798ecccbab5 Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Mon, 8 Jun 2026 15:49:42 +0200 Subject: [PATCH 01/10] fix: update installation guides and sidebar paths for kratos --- AGENTS.md | 2 + docs/_common/install.mdx | 63 ++++++++++++--------------- docs/identities/get-started/setup.mdx | 32 ++++++++++---- docs/kratos/install.mdx | 4 ++ docs/oel/kratos/install.mdx | 20 +++++++++ sidebars-oel.ts | 2 +- sidebars-oss.ts | 1 - 7 files changed, 78 insertions(+), 46 deletions(-) create mode 100644 docs/oel/kratos/install.mdx diff --git a/AGENTS.md b/AGENTS.md index ccd4e0ac7e..dc615efa5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -186,6 +186,8 @@ import MyPartial from "@site/src/components/Shared/kratos/index.mdx" - Can’t find a page → check `docs/network`, `docs/oel`, `docs/oss` - Duplicate content → always set canonical URLs - Adding a page → update the correct sidebar +- Deleting a page → never delete without adding a Vercel redirect from the old + URL to a relevant replacement ## When in Doubt diff --git a/docs/_common/install.mdx b/docs/_common/install.mdx index 3b49621fba..7dd0c9dab7 100644 --- a/docs/_common/install.mdx +++ b/docs/_common/install.mdx @@ -1,50 +1,41 @@ Ory software runs on any operating system (FreeBSD, macOS, Linux, Windows, ...) and supports all major CPU platforms (ARM64, ARMv7, x86_64, x86, ...). -Ory provides pre-built binaries, Docker Images and support various package managers: - -```mdx-code-block -import TOCInline from '@theme/TOCInline' - - -``` - -## Linux - ```mdx-code-block +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' import Linux from '@site/src/components/Install/Linux' - - -``` - -## macOS - -```mdx-code-block import MacOS from '@site/src/components/Install/MacOS' - - -``` - -## Windows - -```mdx-code-block import Windows from '@site/src/components/Install/Windows' - - -``` - -## Docker - -```mdx-code-block import Docker from '@site/src/components/Install/Docker' - + + + + + + + + + + + + + + + A list of available Helm Charts for Kubernetes can be found at k8s.ory.com/helm. + + ``` -## Kubernetes - -A list of available Helm Charts for Kubernetes can be found at [k8s.ory.com/helm](https://k8s.ory.com/helm/). - ## Download Binaries

diff --git a/docs/identities/get-started/setup.mdx b/docs/identities/get-started/setup.mdx index 357b8a5030..0591671e91 100644 --- a/docs/identities/get-started/setup.mdx +++ b/docs/identities/get-started/setup.mdx @@ -9,6 +9,9 @@ import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" import CodeBlock from '@theme/CodeBlock' import { FrameworkCodeTabs } from '@site/src/components/GuidesComponents' +import Linux from '@site/src/components/Install/Linux' +import MacOS from '@site/src/components/Install/MacOS' +import Windows from '@site/src/components/Install/Windows' import nextDevSetup from '!!raw-loader!./_common/code-examples/nextjs/ory.ts' import goSetup from '!!raw-loader!./_common/code-examples/go/ory_client.go' import jsDevSetup from '!!raw-loader!./_common/code-examples/js/setupDev.js' @@ -69,16 +72,13 @@ For local development, you'll need to use Ory Tunnel to connect your local appli values={[ {label: 'macOS', value: 'macos'}, {label: 'Linux', value: 'linux'}, + {label: 'Windows', value: 'windows'}, ]}> ``` -```shell -# Install Ory CLI using Homebrew -brew install ory/tap/cli - -# Verify installation -ory help +```mdx-code-block + ``` ```mdx-code-block @@ -86,6 +86,19 @@ ory help ``` +```mdx-code-block + +``` + +```mdx-code-block + + +``` + +```mdx-code-block + +``` + ```mdx-code-block @@ -94,10 +107,13 @@ ory help After installing the CLI, start the tunnel to connect your local application with Ory's APIs: ```shell -# Start the tunnel (replace with your project id) -ory tunnel --project $PROJECT_ID http://localhost:3000 +ory tunnel --project $ORY_PROJECT_ID --port 4000 http://localhost:3000 ``` +This proxies Ory's APIs on `http://localhost:4000` and forwards all other traffic to your application at `http://localhost:3000`. +Running the tunnel is required for local development because Ory's session cookies must be set on the same domain as your +application. + :::tip To learn more about the Ory Tunnel, read the [dedicated section of the Ory CLI documentation](../../guides/cli/proxy-and-tunnel). diff --git a/docs/kratos/install.mdx b/docs/kratos/install.mdx index fa0bec39d7..9362a8cce8 100644 --- a/docs/kratos/install.mdx +++ b/docs/kratos/install.mdx @@ -3,6 +3,10 @@ id: install title: Installation --- + + + + ```mdx-code-block import Secure from '../_common/secure.mdx' diff --git a/docs/oel/kratos/install.mdx b/docs/oel/kratos/install.mdx new file mode 100644 index 0000000000..d4038dfbdc --- /dev/null +++ b/docs/oel/kratos/install.mdx @@ -0,0 +1,20 @@ +--- +id: install +title: Installation +--- + + + + + +```mdx-code-block +import Secure from '@site/docs/_common/secure.mdx' + + +``` + +```mdx-code-block +import Install from '@site/docs/_common/install.mdx' + + +``` diff --git a/sidebars-oel.ts b/sidebars-oel.ts index e9bf9182e9..6c6e84902a 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -50,7 +50,7 @@ const oelSidebar = [ className: "sidebar-icon sidebar-icon-kratos", items: [ "oel/kratos/intro", - "kratos/install", + "oel/kratos/install", "self-hosted/oel/kratos/upgrade", "self-hosted/oel/kratos/changelog", "oel/kratos/quickstart", diff --git a/sidebars-oss.ts b/sidebars-oss.ts index 6f6ae58d1c..409a2339c3 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -60,7 +60,6 @@ const ossSidebar = [ "oss/kratos/intro", "kratos/install", "kratos/guides/upgrade", - "self-hosted/oel/kratos/changelog", "oss/kratos/quickstart", { type: "category", From 9ffba800faa24452034610a44c261721ab0ef6cd Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Thu, 11 Jun 2026 14:20:18 +0200 Subject: [PATCH 02/10] fix: move kratos oss setup instruction path --- docs/{ => oss}/kratos/install.mdx | 4 ++-- sidebars-oss.ts | 2 +- vercel.json | 5 +++++ 3 files changed, 8 insertions(+), 3 deletions(-) rename docs/{ => oss}/kratos/install.mdx (69%) diff --git a/docs/kratos/install.mdx b/docs/oss/kratos/install.mdx similarity index 69% rename from docs/kratos/install.mdx rename to docs/oss/kratos/install.mdx index 9362a8cce8..d4038dfbdc 100644 --- a/docs/kratos/install.mdx +++ b/docs/oss/kratos/install.mdx @@ -8,13 +8,13 @@ title: Installation ```mdx-code-block -import Secure from '../_common/secure.mdx' +import Secure from '@site/docs/_common/secure.mdx' ``` ```mdx-code-block -import Install from '../_common/install.mdx' +import Install from '@site/docs/_common/install.mdx' ``` diff --git a/sidebars-oss.ts b/sidebars-oss.ts index 409a2339c3..92bbf662c8 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -58,7 +58,7 @@ const ossSidebar = [ className: "sidebar-icon sidebar-icon-kratos", items: [ "oss/kratos/intro", - "kratos/install", + "oss/kratos/install", "kratos/guides/upgrade", "oss/kratos/quickstart", { diff --git a/vercel.json b/vercel.json index f1c8c78264..0eabbfcf2b 100644 --- a/vercel.json +++ b/vercel.json @@ -107,6 +107,11 @@ "destination": "https://www.ory.com/docs/network/keto", "permanent": false }, + { + "source": "/docs/kratos/install", + "destination": "/docs/oss/kratos/install", + "permanent": true + }, { "source": "/kratos/docs", "destination": "https://www.ory.com/docs/kratos", From 7de10ba3727f5e6907ee9c4ffabba52908191c8c Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Mon, 15 Jun 2026 15:26:02 +0100 Subject: [PATCH 03/10] fix: update installation paths to shared component for consistency --- docs/hydra/self-hosted/install.mdx | 2 +- docs/keto/install.mdx | 2 +- docs/oathkeeper/install.mdx | 2 +- docs/oel/kratos/install.mdx | 2 +- docs/oss/kratos/install.mdx | 2 +- {docs/_common => src/components/Shared}/install.mdx | 0 6 files changed, 5 insertions(+), 5 deletions(-) rename {docs/_common => src/components/Shared}/install.mdx (100%) diff --git a/docs/hydra/self-hosted/install.mdx b/docs/hydra/self-hosted/install.mdx index 9f73fce352..7d17a1ea32 100644 --- a/docs/hydra/self-hosted/install.mdx +++ b/docs/hydra/self-hosted/install.mdx @@ -10,7 +10,7 @@ import Secure from '../../_common/secure.mdx' ``` ```mdx-code-block -import Install from '../../_common/install.mdx' +import Install from '@site/src/components/Shared/install.mdx' ``` diff --git a/docs/keto/install.mdx b/docs/keto/install.mdx index 4341925d6b..66e9955527 100644 --- a/docs/keto/install.mdx +++ b/docs/keto/install.mdx @@ -10,7 +10,7 @@ import Secure from '../_common/secure.mdx' ``` ```mdx-code-block -import Install from '../_common/install.mdx' +import Install from '@site/src/components/Shared/install.mdx' ``` diff --git a/docs/oathkeeper/install.mdx b/docs/oathkeeper/install.mdx index 3fd5477d2c..4a1ef1094e 100644 --- a/docs/oathkeeper/install.mdx +++ b/docs/oathkeeper/install.mdx @@ -4,7 +4,7 @@ title: Installation --- ```mdx-code-block -import Install from '../_common/install.mdx' +import Install from '@site/src/components/Shared/install.mdx' ``` diff --git a/docs/oel/kratos/install.mdx b/docs/oel/kratos/install.mdx index d4038dfbdc..c4fab297d2 100644 --- a/docs/oel/kratos/install.mdx +++ b/docs/oel/kratos/install.mdx @@ -14,7 +14,7 @@ import Secure from '@site/docs/_common/secure.mdx' ``` ```mdx-code-block -import Install from '@site/docs/_common/install.mdx' +import Install from '@site/src/components/Shared/install.mdx' ``` diff --git a/docs/oss/kratos/install.mdx b/docs/oss/kratos/install.mdx index d4038dfbdc..c4fab297d2 100644 --- a/docs/oss/kratos/install.mdx +++ b/docs/oss/kratos/install.mdx @@ -14,7 +14,7 @@ import Secure from '@site/docs/_common/secure.mdx' ``` ```mdx-code-block -import Install from '@site/docs/_common/install.mdx' +import Install from '@site/src/components/Shared/install.mdx' ``` diff --git a/docs/_common/install.mdx b/src/components/Shared/install.mdx similarity index 100% rename from docs/_common/install.mdx rename to src/components/Shared/install.mdx From bb5053d07443e7dbc482782de3d7bbc93caae101 Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Mon, 15 Jun 2026 15:45:09 +0100 Subject: [PATCH 04/10] fix: reorganize keto installation docs --- docs/keto/install.mdx | 16 ---------------- docs/oel/keto/install.mdx | 20 ++++++++++++++++++++ docs/oss/keto/install.mdx | 20 ++++++++++++++++++++ sidebars-oel.ts | 2 +- sidebars-oss.ts | 6 +----- vercel.json | 5 +++++ 6 files changed, 47 insertions(+), 22 deletions(-) delete mode 100644 docs/keto/install.mdx create mode 100644 docs/oel/keto/install.mdx create mode 100644 docs/oss/keto/install.mdx diff --git a/docs/keto/install.mdx b/docs/keto/install.mdx deleted file mode 100644 index 66e9955527..0000000000 --- a/docs/keto/install.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: install -title: Installation ---- - -```mdx-code-block -import Secure from '../_common/secure.mdx' - - -``` - -```mdx-code-block -import Install from '@site/src/components/Shared/install.mdx' - - -``` diff --git a/docs/oel/keto/install.mdx b/docs/oel/keto/install.mdx new file mode 100644 index 0000000000..7cfb639691 --- /dev/null +++ b/docs/oel/keto/install.mdx @@ -0,0 +1,20 @@ +--- +id: install +title: Installation +--- + + + + + +```mdx-code-block +import Secure from '@site/docs/_common/secure.mdx' + + +``` + +```mdx-code-block +import Install from '@site/docs/_common/install.mdx' + + +``` diff --git a/docs/oss/keto/install.mdx b/docs/oss/keto/install.mdx new file mode 100644 index 0000000000..7cfb639691 --- /dev/null +++ b/docs/oss/keto/install.mdx @@ -0,0 +1,20 @@ +--- +id: install +title: Installation +--- + + + + + +```mdx-code-block +import Secure from '@site/docs/_common/secure.mdx' + + +``` + +```mdx-code-block +import Install from '@site/docs/_common/install.mdx' + + +``` diff --git a/sidebars-oel.ts b/sidebars-oel.ts index 6c6e84902a..c91856a919 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -130,7 +130,7 @@ const oelSidebar = [ className: "sidebar-icon sidebar-icon-keto", items: [ "oel/keto/index", - "keto/install", + "oel/keto/install", "keto/guides/v0.7-migration", "keto/guides/migrating-legacy-policies", "keto/guides/upgrade", diff --git a/sidebars-oss.ts b/sidebars-oss.ts index 92bbf662c8..a40835f71b 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -137,12 +137,11 @@ const ossSidebar = [ className: "sidebar-icon sidebar-icon-keto", items: [ "oss/keto/index", - "keto/install", + "oss/keto/install", "keto/guides/v0.7-migration", "keto/guides/migrating-legacy-policies", "keto/guides/upgrade", "oss/keto/quickstart", - "self-hosted/oel/keto/changelog", { type: "category", label: "Configuration", @@ -186,7 +185,6 @@ const ossSidebar = [ "self-hosted/oel/oauth2/revert-database-migrations", "self-hosted/oel/oauth2/upgrade", "hydra/self-hosted/upgrade", - "self-hosted/oel/oauth2/changelog", "oel/hydra/quickstart", { type: "category", @@ -254,7 +252,6 @@ const ossSidebar = [ items: [ "oss/polis/index", "polis/install", - "self-hosted/oel/polis/changelog", "oel/polis/quickstart", { type: "category", @@ -431,7 +428,6 @@ const ossSidebar = [ "oss/oathkeeper/index", "oathkeeper/install", "self-hosted/oel/oathkeeper/upgrade-oathkeeper", - "self-hosted/oel/oathkeeper/changelog", { type: "category", label: "Configure", diff --git a/vercel.json b/vercel.json index 0eabbfcf2b..e96bd20786 100644 --- a/vercel.json +++ b/vercel.json @@ -112,6 +112,11 @@ "destination": "/docs/oss/kratos/install", "permanent": true }, + { + "source": "/docs/keto/install", + "destination": "/docs/oss/keto/install", + "permanent": true + }, { "source": "/kratos/docs", "destination": "https://www.ory.com/docs/kratos", From 9f05ad830c46f63d17963da2b41f836bc2db4756 Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Wed, 17 Jun 2026 17:12:51 +0200 Subject: [PATCH 05/10] fix: formatting --- src/components/Shared/install.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/src/components/Shared/install.mdx b/src/components/Shared/install.mdx index 7dd0c9dab7..c0284f4284 100644 --- a/src/components/Shared/install.mdx +++ b/src/components/Shared/install.mdx @@ -1,5 +1,5 @@ -Ory software runs on any operating system (FreeBSD, macOS, Linux, Windows, ...) and supports all major CPU platforms (ARM64, -ARMv7, x86_64, x86, ...). +Ory software runs on any operating system (FreeBSD, macOS, Linux, Windows, ...) +and supports all major CPU platforms (ARM64, ARMv7, x86_64, x86, ...). ```mdx-code-block import Tabs from '@theme/Tabs' @@ -40,8 +40,9 @@ import Docker from '@site/src/components/Install/Docker'

You can download the client and server binaries on our{" "} - Github releases page. No installer is available. You have to add - the binary to the PATH in your environment yourself, for example by putting it into + Github releases{" "} + page. No installer is available. You have to add the binary to the PATH in + your environment yourself, for example by putting it into /usr/local/bin or something comparable.

@@ -55,12 +56,13 @@ import CodeBlock from '@theme/CodeBlock' ## Building from source -If you wish to compile the binary yourself, you need to install and set up [Go 1.17+](https://golang.org/) and add `$GOPATH/bin` -to your `$PATH`. +If you wish to compile the binary yourself, you need to install and set up +[Go 1.17+](https://golang.org/) and add `$GOPATH/bin` to your `$PATH`. :::danger -Please note that this will check out the latest commit, which might be not yet released and unstable. +Please note that this will check out the latest commit, which might be not yet +released and unstable. ::: From 0b15757299fadd10d4bea8a34811affbe7034eb3 Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Thu, 18 Jun 2026 13:43:27 +0200 Subject: [PATCH 06/10] fix: update installation and upgrade guides across deployment models --- docs/hydra/self-hosted/install.mdx | 2 +- docs/keto/quickstart.mdx | 174 ------------------ docs/oathkeeper/install.mdx | 2 +- docs/oel/keto/guides/upgrade.mdx | 14 ++ docs/oel/keto/install.mdx | 8 +- docs/oel/kratos/guides/upgrade.mdx | 14 ++ docs/oel/kratos/install.mdx | 8 +- docs/oss/keto/guides/upgrade.mdx | 14 ++ docs/oss/keto/install.mdx | 2 +- docs/oss/kratos/guides/upgrade.mdx | 14 ++ docs/oss/kratos/install.mdx | 2 +- docs/oss/upgrading.mdx | 2 +- docs/solutions/overview.mdx | 6 +- sidebars-oel.ts | 4 +- sidebars-oss.ts | 6 +- src/components/Shared/install-oel.mdx | 55 ++++++ .../Shared/{install.mdx => install-oss.mdx} | 0 .../Shared}/keto/guides/upgrade.mdx | 15 +- src/components/Shared/keto/quickstart.mdx | 140 +++++++------- .../Shared}/kratos/guides/upgrade.mdx | 13 +- vercel.json | 19 +- 21 files changed, 215 insertions(+), 299 deletions(-) delete mode 100644 docs/keto/quickstart.mdx create mode 100644 docs/oel/keto/guides/upgrade.mdx create mode 100644 docs/oel/kratos/guides/upgrade.mdx create mode 100644 docs/oss/keto/guides/upgrade.mdx create mode 100644 docs/oss/kratos/guides/upgrade.mdx create mode 100644 src/components/Shared/install-oel.mdx rename src/components/Shared/{install.mdx => install-oss.mdx} (100%) rename {docs => src/components/Shared}/keto/guides/upgrade.mdx (70%) rename {docs => src/components/Shared}/kratos/guides/upgrade.mdx (78%) diff --git a/docs/hydra/self-hosted/install.mdx b/docs/hydra/self-hosted/install.mdx index 7d17a1ea32..ae3397dd7c 100644 --- a/docs/hydra/self-hosted/install.mdx +++ b/docs/hydra/self-hosted/install.mdx @@ -10,7 +10,7 @@ import Secure from '../../_common/secure.mdx' ``` ```mdx-code-block -import Install from '@site/src/components/Shared/install.mdx' +import Install from '@site/src/components/Shared/install-oel.mdx' ``` diff --git a/docs/keto/quickstart.mdx b/docs/keto/quickstart.mdx deleted file mode 100644 index bf5d69fba8..0000000000 --- a/docs/keto/quickstart.mdx +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: "Quickstart: Cat Videos Example" ---- - -```mdx-code-block -import Help from '@site/docs/_common/need-selfhosted-support.mdx' - - -``` - -This example describes a video sharing service. The individual videos are organized in directories. Every directory has an owner -and every video has the same owner as it's parent directory. The owner has elevated privileges about the video files that aren't -modeled individually in Ory Keto. The only other privilege modeled in this example is "view access." Every owner has view access -to their objects, and this privilege can be granted to other users as well. The video sharing application interprets the special -`*` user ID as any user, including anonymous users. Note that Ory Keto doesn't interpret this subject any differently from other -subjects. It also doesn't know anything about directory structures or induced ownership. - -The "Keto client" is the application interacting with Keto. In this case we refer to the video sharing service backend as the Keto -client. - -## Starting the example - -First, [install Keto](./install.mdx). - -Now you can start the example using either `docker-compose` or a bash script. The bash script requires you to have the `keto` -binary in your `$PATH`. - -Alternatively, use Docker to automatically get the required images. - -```shell -# clone the repository if you don't have it yet -git clone git@github.com:ory/keto.git && cd keto - -# Alternatively, you can use 'https' to clone if ssh cloning gives permission denied error. (Configure ssh keys in github to resolve the issue.) -git clone https://github.com/ory/keto.git && cd keto - -docker-compose -f contrib/cat-videos-example/docker-compose.yml up -# or -./contrib/cat-videos-example/up.sh - -# output: all initially created relationships - -# NAMESPACE OBJECT RELATION NAME SUBJECT -# Video /cats/1.mp4 owner Video:/cats#owner -# Video /cats/1.mp4 view Video:/cats/1.mp4#owner -# Video /cats/1.mp4 view User:* -# Video /cats/2.mp4 owner Video:/cats#owner -# Video /cats/2.mp4 view Video:/cats/2.mp4#owner -# Video /cats owner User:Alice -# Video /cats view Video:/cats#owner -``` - -## State of the system - -At the current state only `User:Alice` has added videos. Both videos are in the `/cats` directory owned by `User:Alice`. The file -`File:/cats/1.mp4` can be viewed by anyone (`User:*`), while `Video:/cats/2.mp4` has no extra sharing options, and can therefore -only be viewed by its owner, `User:Alice`. The relationship definitions are located in the -`contrib/cat-videos-example/relation-tuples` directory. - -## Simulating the video sharing application - -Now you can open a second terminal to run the queries against, just like the video service client would do. In this example we -will use the Keto CLI client. - -If you want to run the Keto CLI within **Docker**, set the alias - -```shell -alias keto="docker run -it --network cat-videos-example_default -e KETO_READ_REMOTE=\"keto:4466\" oryd/keto:v25.4.0" -``` - -in your terminal session. Alternatively, you need to set the remote endpoint so that the Keto CLI knows where to connect to (not -necessary if using Docker): - -```shell -export KETO_READ_REMOTE="127.0.0.1:4466" -``` - -### Check incoming requests - -First off, we get a request by an anonymous user that would like to view `/cats/2.mp4`. The client now has to ask Keto if that -operation should be allowed or denied. - -```shell -# Is "*" allowed to "view" the object "videos":"/cats/2.mp4"? -keto check "User:*" view Video /cats/2.mp4 --insecure-disable-transport-security -# output: - -# Denied -``` - -We already discussed that this request should be denied, but it's always good to see this in action. - -Now `User:Alice` wants to change some view permissions of `Video:/cats/1.mp4`. For this, the video service application has to show -all users that are allowed to view the video. It uses Keto's [expand-API](./concepts/25_api-overview.mdx#expand-subject-sets) to -get these data: - -```shell -# Who is allowed to "view" the object "videos":"/cats/2.mp4"? -keto expand view Video /cats/1.mp4 --insecure-disable-transport-security -# output: -``` - -```keto-tuples -# or :#@Video:/cats/1.mp4#view -# ├──∋ :#@User:*️ -# └──or :#@Video:/cats/1.mp4#owner -# └──or :#@Video:/cats#owner -# └──∋ :#@User:Alice️ -``` - -Here we can see the full subject set expansion. The second branch - -```keto-tuples -Video:/cats/1.mp4#owner -``` - -indicates that every owner of the object is allowed to view the Object. - -In the next step we see that the object's owners are the owners of `Video:/cats` - -```keto-tuples -Video:/cats#owner -``` - -On the last line, we see that `User:Alice` is the owner of `Video:/cats`. - -Note that there is no direct relationship that would grant `Alice` view access on `/cats/1.mp4` as this is indirectly defined via -the ownership relation. - -The special user `User:*` on the other hand was directly granted view access on the object, as it's a first-level leaf of the -expansion tree. The following CLI command proves that this is the case: - -```shell -# Is "*" allowed to "view" the object "Video":"/cats/1.mp4"? -keto check "User:*" view Video /cats/1.mp4 --insecure-disable-transport-security -# output: - -# Allowed -``` - -```mdx-code-block -import Mermaid from "@site/src/theme/Mermaid" - - r2 - r1 ----- sub1(["User:Alice"]) - r1 -.-> r4 - obj1 ---- r4((owner)) - r3 --- all(["User:* (anyone)"]) - r4 -.-> r3 - obj1[Video:/cats/1.mp4] --- r3((view)) - obj2 --- r6((view)) - r1 -.-> r5 - obj2[Video:/cats/2.mp4] ---- r5((owner)) - r5 -.-> r6 - style sub1 fill:green,color:white - style all fill:green,color:white - style r1 fill:darkgreen,color:white - style r2 fill:darkgreen,color:white - style r3 fill:darkgreen,color:white - style r4 fill:darkgreen,color:white - style r5 fill:darkgreen,color:white - style r6 fill:darkgreen,color:white -`} -/> -``` - - - -Updating the view permissions will be added here at a later stage. diff --git a/docs/oathkeeper/install.mdx b/docs/oathkeeper/install.mdx index 4a1ef1094e..1d018c47e8 100644 --- a/docs/oathkeeper/install.mdx +++ b/docs/oathkeeper/install.mdx @@ -4,7 +4,7 @@ title: Installation --- ```mdx-code-block -import Install from '@site/src/components/Shared/install.mdx' +import Install from '@site/src/components/Shared/install-oss.mdx' ``` diff --git a/docs/oel/keto/guides/upgrade.mdx b/docs/oel/keto/guides/upgrade.mdx new file mode 100644 index 0000000000..4d04a5591c --- /dev/null +++ b/docs/oel/keto/guides/upgrade.mdx @@ -0,0 +1,14 @@ +--- +id: upgrade +title: Apply upgrades +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/keto/guides/upgrade.mdx" + + +``` diff --git a/docs/oel/keto/install.mdx b/docs/oel/keto/install.mdx index 7cfb639691..aeeadbc2b2 100644 --- a/docs/oel/keto/install.mdx +++ b/docs/oel/keto/install.mdx @@ -8,13 +8,7 @@ title: Installation ```mdx-code-block -import Secure from '@site/docs/_common/secure.mdx' - - -``` - -```mdx-code-block -import Install from '@site/docs/_common/install.mdx' +import Install from '@site/src/components/Shared/install-oel.mdx' ``` diff --git a/docs/oel/kratos/guides/upgrade.mdx b/docs/oel/kratos/guides/upgrade.mdx new file mode 100644 index 0000000000..cbcb1fd94b --- /dev/null +++ b/docs/oel/kratos/guides/upgrade.mdx @@ -0,0 +1,14 @@ +--- +id: upgrade +title: Apply upgrades +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/guides/upgrade.mdx" + + +``` diff --git a/docs/oel/kratos/install.mdx b/docs/oel/kratos/install.mdx index c4fab297d2..91a352e1b4 100644 --- a/docs/oel/kratos/install.mdx +++ b/docs/oel/kratos/install.mdx @@ -8,13 +8,7 @@ title: Installation ```mdx-code-block -import Secure from '@site/docs/_common/secure.mdx' - - -``` - -```mdx-code-block -import Install from '@site/src/components/Shared/install.mdx' +import Install from '@site/src/components/Shared/install-oel.mdx' ``` diff --git a/docs/oss/keto/guides/upgrade.mdx b/docs/oss/keto/guides/upgrade.mdx new file mode 100644 index 0000000000..4d04a5591c --- /dev/null +++ b/docs/oss/keto/guides/upgrade.mdx @@ -0,0 +1,14 @@ +--- +id: upgrade +title: Apply upgrades +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/keto/guides/upgrade.mdx" + + +``` diff --git a/docs/oss/keto/install.mdx b/docs/oss/keto/install.mdx index 7cfb639691..c2bd0e56a3 100644 --- a/docs/oss/keto/install.mdx +++ b/docs/oss/keto/install.mdx @@ -14,7 +14,7 @@ import Secure from '@site/docs/_common/secure.mdx' ``` ```mdx-code-block -import Install from '@site/docs/_common/install.mdx' +import Install from '@site/src/components/Shared/install-oss.mdx' ``` diff --git a/docs/oss/kratos/guides/upgrade.mdx b/docs/oss/kratos/guides/upgrade.mdx new file mode 100644 index 0000000000..cbcb1fd94b --- /dev/null +++ b/docs/oss/kratos/guides/upgrade.mdx @@ -0,0 +1,14 @@ +--- +id: upgrade +title: Apply upgrades +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/guides/upgrade.mdx" + + +``` diff --git a/docs/oss/kratos/install.mdx b/docs/oss/kratos/install.mdx index c4fab297d2..5cb4b316e1 100644 --- a/docs/oss/kratos/install.mdx +++ b/docs/oss/kratos/install.mdx @@ -14,7 +14,7 @@ import Secure from '@site/docs/_common/secure.mdx' ``` ```mdx-code-block -import Install from '@site/src/components/Shared/install.mdx' +import Install from '@site/src/components/Shared/install-oss.mdx' ``` diff --git a/docs/oss/upgrading.mdx b/docs/oss/upgrading.mdx index e437960dd6..7b47cddcd1 100644 --- a/docs/oss/upgrading.mdx +++ b/docs/oss/upgrading.mdx @@ -14,7 +14,7 @@ changes. We know that breaking changes are annoying so we want to make upgrading We document changelogs and upgrade guides for Ory services: -- Ory Kratos: [upgrade guide](../kratos/guides/upgrade), [changelog](https://github.com/ory/kratos/blob/master/CHANGELOG.md) +- Ory Kratos: [upgrade guide](./kratos/guides/upgrade), [changelog](https://github.com/ory/kratos/blob/master/CHANGELOG.md) - Ory Hydra: [upgrade guide](https://github.com/ory/hydra/blob/master/UPGRADE.md), [changelog](https://github.com/ory/hydra/blob/master/CHANGELOG.md) - Ory Oathkeeper: [upgrade guide](https://github.com/ory/oathkeeper/blob/master/UPGRADE.md), diff --git a/docs/solutions/overview.mdx b/docs/solutions/overview.mdx index 7321bd3a25..b784e07acc 100644 --- a/docs/solutions/overview.mdx +++ b/docs/solutions/overview.mdx @@ -18,7 +18,7 @@ business needs. @@ -27,7 +27,7 @@ business needs. @@ -36,7 +36,7 @@ business needs. diff --git a/sidebars-oel.ts b/sidebars-oel.ts index c91856a919..82a5342816 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -78,7 +78,7 @@ const oelSidebar = [ items: [ "kratos/guides/docker", "kratos/guides/deploy-kratos-example", - "kratos/guides/upgrade", + "oel/kratos/guides/upgrade", "kratos/guides/production", "kratos/guides/multi-tenancy-multitenant", "oel/kratos/scalability", @@ -133,7 +133,7 @@ const oelSidebar = [ "oel/keto/install", "keto/guides/v0.7-migration", "keto/guides/migrating-legacy-policies", - "keto/guides/upgrade", + "oel/keto/guides/upgrade", "oel/keto/quickstart", "self-hosted/oel/keto/changelog", { diff --git a/sidebars-oss.ts b/sidebars-oss.ts index a40835f71b..1091962b4f 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -59,7 +59,7 @@ const ossSidebar = [ items: [ "oss/kratos/intro", "oss/kratos/install", - "kratos/guides/upgrade", + "oss/kratos/guides/upgrade", "oss/kratos/quickstart", { type: "category", @@ -85,7 +85,7 @@ const ossSidebar = [ items: [ "kratos/guides/docker", "kratos/guides/deploy-kratos-example", - "kratos/guides/upgrade", + "oss/kratos/guides/upgrade", "kratos/guides/production", "kratos/guides/multi-tenancy-multitenant", "oel/kratos/scalability", @@ -140,7 +140,7 @@ const ossSidebar = [ "oss/keto/install", "keto/guides/v0.7-migration", "keto/guides/migrating-legacy-policies", - "keto/guides/upgrade", + "oss/keto/guides/upgrade", "oss/keto/quickstart", { type: "category", diff --git a/src/components/Shared/install-oel.mdx b/src/components/Shared/install-oel.mdx new file mode 100644 index 0000000000..c6f5126424 --- /dev/null +++ b/src/components/Shared/install-oel.mdx @@ -0,0 +1,55 @@ +Ory software runs on any operating system (FreeBSD, macOS, Linux, Windows, ...) +and supports all major CPU platforms (ARM64, ARMv7, x86_64, x86, ...). + +```mdx-code-block +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' +import Linux from '@site/src/components/Install/Linux' +import MacOS from '@site/src/components/Install/MacOS' +import Windows from '@site/src/components/Install/Windows' +import Docker from '@site/src/components/Install/Docker' + + + + + + + + + + + + + + + + A list of available Helm Charts for Kubernetes can be found at k8s.ory.com/helm. + + +``` + +## Download Binaries + +

+ You can download the client and server binaries on our{" "} + Github releases{" "} + page. No installer is available. You have to add the binary to the PATH in + your environment yourself, for example by putting it into + /usr/local/bin or something comparable. +

+ +Once installed, you should be able to run: + +```mdx-code-block +import CodeBlock from '@theme/CodeBlock' + +{`${props.repo} help`} +``` diff --git a/src/components/Shared/install.mdx b/src/components/Shared/install-oss.mdx similarity index 100% rename from src/components/Shared/install.mdx rename to src/components/Shared/install-oss.mdx diff --git a/docs/keto/guides/upgrade.mdx b/src/components/Shared/keto/guides/upgrade.mdx similarity index 70% rename from docs/keto/guides/upgrade.mdx rename to src/components/Shared/keto/guides/upgrade.mdx index 42cc857d82..454ff89c62 100644 --- a/docs/keto/guides/upgrade.mdx +++ b/src/components/Shared/keto/guides/upgrade.mdx @@ -1,8 +1,3 @@ ---- -id: upgrade -title: Apply upgrades ---- - Follow this guide when upgrading Ory Keto to a newer version. :::danger @@ -14,9 +9,9 @@ Back up your data! Applying upgrades can lead to data loss if handled incorrectl 1. Review breaking changes. Visit the [CHANGELOG.md](https://github.com/ory/keto/blob/master/CHANGELOG.md) to see if breaking changes have been introduced in the version you are upgrading to. 1. Backup your data. -1. Update the [Ory Keto SDK](../sdk/01_overview.md) if used in your application. -1. [Install](../install.mdx) the new version of Ory Keto. -1. Run [`keto migrate`](../cli/keto-migrate.md) to run the SQL migrations to the new database schema. +1. Update the [Ory Keto SDK](/docs/keto/sdk/overview) if used in your application. +1. Install the new version of Ory Keto. +1. Run [`keto migrate`](/docs/keto/cli/keto-migrate) to run the SQL migrations to the new database schema. Should you run into problems with the upgrade, consider a stepped upgrade and please visit the community [chat](https://slack.ory.com/) or start a [discussion](https://github.com/ory/keto/discussions). @@ -24,11 +19,11 @@ Should you run into problems with the upgrade, consider a stepped upgrade and pl ## Migrating to Keto 0.7 Ory Keto v0.6 used the table-separated namespaces database schema described in the Google Zanzibar paper. However, we found for -various reasons outlined in that this isn't ideal for Keto. Visit [migrating to Keto v0.7](./v0.7-migration) guide for more +various reasons outlined in that this isn't ideal for Keto. Visit [migrating to Keto v0.7](/docs/keto/guides/v0.7-migration) guide for more information ## Migrating Keto policies from 0.5 version In [Ory Keto 0.6](https://github.com/ory/keto/blob/v0.6.0-alpha.1/CHANGELOG.md#060-alpha1pre0-2021-04-01) Ory Access Control -Policy DSL modeled after AWS IAM Policies became obsolete. Visit [migrating legacy policies](./migrating-legacy-policies) guide +Policy DSL modeled after AWS IAM Policies became obsolete. Visit [migrating legacy policies](/docs/keto/guides/migrating-legacy-policies) guide for more information. diff --git a/src/components/Shared/keto/quickstart.mdx b/src/components/Shared/keto/quickstart.mdx index 2181bb9fb6..896f8016d9 100644 --- a/src/components/Shared/keto/quickstart.mdx +++ b/src/components/Shared/keto/quickstart.mdx @@ -4,26 +4,22 @@ import Help from '@site/docs/_common/need-selfhosted-support.mdx' ``` -This example describes a video sharing service. The individual videos are -organized in directories. Every directory has an owner and every video has the -same owner as it's parent directory. The owner has elevated privileges about the -video files that aren't modeled individually in Ory Keto. The only other -privilege modeled in this example is "view access." Every owner has view access -to their objects, and this privilege can be granted to other users as well. The -video sharing application interprets the special `*` user ID as any user, -including anonymous users. Note that Ory Keto doesn't interpret this subject any -differently from other subjects. It also doesn't know anything about directory -structures or induced ownership. - -The "Keto client" is the application interacting with Keto. In this case we -refer to the video sharing service backend as the Keto client. +This example describes a video sharing service. The individual videos are organized in directories. Every directory has an owner +and every video has the same owner as it's parent directory. The owner has elevated privileges about the video files that aren't +modeled individually in Ory Keto. The only other privilege modeled in this example is "view access." Every owner has view access +to their objects, and this privilege can be granted to other users as well. The video sharing application interprets the special +`*` user ID as any user, including anonymous users. Note that Ory Keto doesn't interpret this subject any differently from other +subjects. It also doesn't know anything about directory structures or induced ownership. + +The "Keto client" is the application interacting with Keto. In this case we refer to the video sharing service backend as the Keto +client. ## Starting the example -First, [install Keto](../../../../docs/keto/install). +First, install Keto. -Now you can start the example using either `docker-compose` or a bash script. -The bash script requires you to have the `keto` binary in your `$PATH`. +Now you can start the example using either `docker-compose` or a bash script. The bash script requires you to have the `keto` +binary in your `$PATH`. Alternatively, use Docker to automatically get the required images. @@ -40,38 +36,36 @@ docker-compose -f contrib/cat-videos-example/docker-compose.yml up # output: all initially created relationships -# NAMESPACE OBJECT RELATION NAME SUBJECT -# videos /cats/1.mp4 owner videos:/cats#owner -# videos /cats/1.mp4 view videos:/cats/1.mp4#owner -# videos /cats/1.mp4 view * -# videos /cats/2.mp4 owner videos:/cats#owner -# videos /cats/2.mp4 view videos:/cats/2.mp4#owner -# videos /cats owner cat lady -# videos /cats view videos:/cats#owner +# NAMESPACE OBJECT RELATION NAME SUBJECT +# Video /cats/1.mp4 owner Video:/cats#owner +# Video /cats/1.mp4 view Video:/cats/1.mp4#owner +# Video /cats/1.mp4 view User:* +# Video /cats/2.mp4 owner Video:/cats#owner +# Video /cats/2.mp4 view Video:/cats/2.mp4#owner +# Video /cats owner User:Alice +# Video /cats view Video:/cats#owner ``` ## State of the system -At the current state only one user with the username `cat lady` has added -videos. Both videos are in the `/cats` directory owned by `cat lady`. The file -`/cats/1.mp4` can be viewed by anyone (`*`), while `/cats/2.mp4` has no extra -sharing options, and can therefore only be viewed by its owner, `cat lady`. The -relationship definitions are located in the +At the current state only `User:Alice` has added videos. Both videos are in the `/cats` directory owned by `User:Alice`. The file +`File:/cats/1.mp4` can be viewed by anyone (`User:*`), while `Video:/cats/2.mp4` has no extra sharing options, and can therefore +only be viewed by its owner, `User:Alice`. The relationship definitions are located in the `contrib/cat-videos-example/relation-tuples` directory. ## Simulating the video sharing application -Now you can open a second terminal to run the queries against, just like the -video service client would do. In this example we will use the Keto CLI client. +Now you can open a second terminal to run the queries against, just like the video service client would do. In this example we +will use the Keto CLI client. If you want to run the Keto CLI within **Docker**, set the alias ```shell -alias keto="docker run -it --network cat-videos-example_default -e KETO_READ_REMOTE=\"keto:4466\" oryd/keto:v0.7.0-alpha.1" +alias keto="docker run -it --network cat-videos-example_default -e KETO_READ_REMOTE=\"keto:4466\" oryd/keto:v25.4.0" ``` -in your terminal session. Alternatively, you need to set the remote endpoint so -that the Keto CLI knows where to connect to (not necessary if using Docker): +in your terminal session. Alternatively, you need to set the remote endpoint so that the Keto CLI knows where to connect to (not +necessary if using Docker): ```shell export KETO_READ_REMOTE="127.0.0.1:4466" @@ -79,70 +73,62 @@ export KETO_READ_REMOTE="127.0.0.1:4466" ### Check incoming requests -First off, we get a request by an anonymous user that would like to view -`/cats/2.mp4`. The client now has to ask Keto if that operation should be -allowed or denied. +First off, we get a request by an anonymous user that would like to view `/cats/2.mp4`. The client now has to ask Keto if that +operation should be allowed or denied. ```shell # Is "*" allowed to "view" the object "videos":"/cats/2.mp4"? -keto check "*" view videos /cats/2.mp4 +keto check "User:*" view Video /cats/2.mp4 --insecure-disable-transport-security # output: # Denied ``` -We already discussed that this request should be denied, but it's always good to -see this in action. +We already discussed that this request should be denied, but it's always good to see this in action. -Now `cat lady` wants to change some view permissions of `/cats/1.mp4`. For this, -the video service application has to show all users that are allowed to view the -video. It uses Keto's -[expand-API](../../../../docs/keto/concepts/api-overview#expand-subject-sets) to +Now `User:Alice` wants to change some view permissions of `Video:/cats/1.mp4`. For this, the video service application has to show +all users that are allowed to view the video. It uses Keto's [expand-API](/docs/keto/concepts/api-overview#expand-subject-sets) to get these data: ```shell # Who is allowed to "view" the object "videos":"/cats/2.mp4"? -keto expand view videos /cats/1.mp4 +keto expand view Video /cats/1.mp4 --insecure-disable-transport-security # output: - -# ∪ videos:/cats/1.mp4#view -# ├─ ∪ videos:/cats/1.mp4#owner -# │ ├─ ∪ videos:/cats#owner -# │ │ ├─ ☘ cat lady️ -# ├─ ☘ *️ ``` -Here we can see the full subject set expansion. The first branch - -```keto-relation-tuples -videos:/cats/1.mp4#view +```keto-tuples +# or :#@Video:/cats/1.mp4#view +# ├──∋ :#@User:*️ +# └──or :#@Video:/cats/1.mp4#owner +# └──or :#@Video:/cats#owner +# └──∋ :#@User:Alice️ ``` -indicates that every owner of the object is allowed to view +Here we can see the full subject set expansion. The second branch -```keto-relation-tuples -videos:/cats/1.mp4#owner +```keto-tuples +Video:/cats/1.mp4#owner ``` -In the next step we see that the object's owners are the owners of `/cats` +indicates that every owner of the object is allowed to view the Object. + +In the next step we see that the object's owners are the owners of `Video:/cats` -```keto-relation-tuples -videos:/cats#owner +```keto-tuples +Video:/cats#owner ``` -We see that `cat lady` is the owner of `/cats`. +On the last line, we see that `User:Alice` is the owner of `Video:/cats`. -Note that there is no direct relationship that would grant `cat lady` view -access on `/cats/1.mp4` as this is indirectly defined via the ownership -relation. +Note that there is no direct relationship that would grant `Alice` view access on `/cats/1.mp4` as this is indirectly defined via +the ownership relation. -The special user `*` on the other hand was directly granted view access on the -object, as it's a first-level leaf of the expansion tree. The following CLI -command proves that this is the case: +The special user `User:*` on the other hand was directly granted view access on the object, as it's a first-level leaf of the +expansion tree. The following CLI command proves that this is the case: ```shell -# Is "*" allowed to "view" the object "videos":"/cats/1.mp4"? -keto check "*" view videos /cats/1.mp4 +# Is "*" allowed to "view" the object "Video":"/cats/1.mp4"? +keto check "User:*" view Video /cats/1.mp4 --insecure-disable-transport-security # output: # Allowed @@ -154,21 +140,21 @@ import Mermaid from "@site/src/theme/Mermaid" r2 - r1 ----- sub1(["cat lady"]) + r1 ----- sub1(["User:Alice"]) r1 -.-> r4 obj1 ---- r4((owner)) - r3 --- all(["* (anyone)"]) + r3 --- all(["User:* (anyone)"]) r4 -.-> r3 - obj1[videos:/cats/1.mp4] --- r3((view)) + obj1[Video:/cats/1.mp4] --- r3((view)) obj2 --- r6((view)) r1 -.-> r5 - obj2[videos/cats/2.mp4] ---- r5((owner)) + obj2[Video:/cats/2.mp4] ---- r5((owner)) r5 -.-> r6 - style sub1 fill:lightgreen - style all fill:lightgreen + style sub1 fill:green,color:white + style all fill:green,color:white style r1 fill:darkgreen,color:white style r2 fill:darkgreen,color:white style r3 fill:darkgreen,color:white diff --git a/docs/kratos/guides/upgrade.mdx b/src/components/Shared/kratos/guides/upgrade.mdx similarity index 78% rename from docs/kratos/guides/upgrade.mdx rename to src/components/Shared/kratos/guides/upgrade.mdx index 5ca412d93e..7bfa5c29da 100644 --- a/docs/kratos/guides/upgrade.mdx +++ b/src/components/Shared/kratos/guides/upgrade.mdx @@ -1,8 +1,3 @@ ---- -id: upgrade -title: Apply upgrades ---- - Follow this guide when upgrading Ory Kratos to a newer version. :::danger @@ -14,12 +9,12 @@ Back up your data! Applying upgrades can lead to data loss if handled incorrectl 1. Review breaking changes. Visit the [CHANGELOG.md](https://github.com/ory/kratos/blob/master/CHANGELOG.md) to see if breaking changes have been introduced in the version you are upgrading to. 1. Backup your data. -1. Update the [Ory Kratos SDK](../sdk/01_overview.md) if used in your application. -1. [Install](../install.mdx) the new version of Ory Kratos. -1. Run [`kratos migrate sql`](../cli/kratos-migrate-sql.md) to run the SQL migrations to the new database schema. +1. Update the [Ory Kratos SDK](/docs/kratos/sdk/overview) if used in your application. +1. Install the new version of Ory Kratos. +1. Run [`kratos migrate sql`](/docs/kratos/cli/kratos-migrate-sql) to run the SQL migrations to the new database schema. 1. If you are upgrading to a version that introduces phone number normalization, run `kratos migrate normalize-phone-numbers` after the new version is deployed and serving traffic. This rewrites existing phone identifiers to E.164 format. See the - [phone normalization guide](./normalize-phone-numbers.mdx) for the recommended rollout sequence. + [phone normalization guide](/docs/kratos/guides/normalize-phone-numbers) for the recommended rollout sequence. Should you run into problems with the upgrade, consider a stepped upgrade and please visit the community [chat](https://slack.ory.com/) or start a [discussion](https://github.com/ory/kratos/discussions). diff --git a/vercel.json b/vercel.json index e96bd20786..936fbe597b 100644 --- a/vercel.json +++ b/vercel.json @@ -109,12 +109,27 @@ }, { "source": "/docs/kratos/install", - "destination": "/docs/oss/kratos/install", + "destination": "/docs/oel/kratos/install", "permanent": true }, { "source": "/docs/keto/install", - "destination": "/docs/oss/keto/install", + "destination": "/docs/oel/keto/install", + "permanent": true + }, + { + "source": "/docs/kratos/guides/upgrade", + "destination": "/docs/oss/kratos/guides/upgrade", + "permanent": true + }, + { + "source": "/docs/keto/guides/upgrade", + "destination": "/docs/oss/keto/guides/upgrade", + "permanent": true + }, + { + "source": "/docs/keto/quickstart", + "destination": "/docs/oss/keto/quickstart", "permanent": true }, { From 19730adc7469a5a732b54f5cdc09044ba90814e9 Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Fri, 19 Jun 2026 11:41:55 +0200 Subject: [PATCH 07/10] fix: format --- src/components/Shared/keto/guides/upgrade.mdx | 36 ++++++---- src/components/Shared/keto/quickstart.mdx | 67 +++++++++++-------- .../Shared/kratos/guides/upgrade.mdx | 48 ++++++++----- 3 files changed, 93 insertions(+), 58 deletions(-) diff --git a/src/components/Shared/keto/guides/upgrade.mdx b/src/components/Shared/keto/guides/upgrade.mdx index 454ff89c62..b73ed3b795 100644 --- a/src/components/Shared/keto/guides/upgrade.mdx +++ b/src/components/Shared/keto/guides/upgrade.mdx @@ -2,28 +2,38 @@ Follow this guide when upgrading Ory Keto to a newer version. :::danger -Back up your data! Applying upgrades can lead to data loss if handled incorrectly. +Back up your data! Applying upgrades can lead to data loss if handled +incorrectly. ::: -1. Review breaking changes. Visit the [CHANGELOG.md](https://github.com/ory/keto/blob/master/CHANGELOG.md) to see if breaking - changes have been introduced in the version you are upgrading to. +1. Review breaking changes. Visit the + [CHANGELOG.md](https://github.com/ory/keto/blob/master/CHANGELOG.md) to see + if breaking changes have been introduced in the version you are upgrading to. 1. Backup your data. -1. Update the [Ory Keto SDK](/docs/keto/sdk/overview) if used in your application. -1. Install the new version of Ory Keto. -1. Run [`keto migrate`](/docs/keto/cli/keto-migrate) to run the SQL migrations to the new database schema. +1. Update the [Ory Keto SDK](/docs/keto/sdk/overview) if used in your + application. +1. Install the new version + of Ory Keto. +1. Run [`keto migrate`](/docs/keto/cli/keto-migrate) to run the SQL migrations + to the new database schema. -Should you run into problems with the upgrade, consider a stepped upgrade and please visit the community -[chat](https://slack.ory.com/) or start a [discussion](https://github.com/ory/keto/discussions). +Should you run into problems with the upgrade, consider a stepped upgrade and +please visit the community [chat](https://slack.ory.com/) or start a +[discussion](https://github.com/ory/keto/discussions). ## Migrating to Keto 0.7 -Ory Keto v0.6 used the table-separated namespaces database schema described in the Google Zanzibar paper. However, we found for -various reasons outlined in that this isn't ideal for Keto. Visit [migrating to Keto v0.7](/docs/keto/guides/v0.7-migration) guide for more +Ory Keto v0.6 used the table-separated namespaces database schema described in +the Google Zanzibar paper. However, we found for various reasons outlined in +that this isn't ideal for Keto. Visit +[migrating to Keto v0.7](/docs/keto/guides/v0.7-migration) guide for more information ## Migrating Keto policies from 0.5 version -In [Ory Keto 0.6](https://github.com/ory/keto/blob/v0.6.0-alpha.1/CHANGELOG.md#060-alpha1pre0-2021-04-01) Ory Access Control -Policy DSL modeled after AWS IAM Policies became obsolete. Visit [migrating legacy policies](/docs/keto/guides/migrating-legacy-policies) guide -for more information. +In +[Ory Keto 0.6](https://github.com/ory/keto/blob/v0.6.0-alpha.1/CHANGELOG.md#060-alpha1pre0-2021-04-01) +Ory Access Control Policy DSL modeled after AWS IAM Policies became obsolete. +Visit [migrating legacy policies](/docs/keto/guides/migrating-legacy-policies) +guide for more information. diff --git a/src/components/Shared/keto/quickstart.mdx b/src/components/Shared/keto/quickstart.mdx index 896f8016d9..9d26742ac7 100644 --- a/src/components/Shared/keto/quickstart.mdx +++ b/src/components/Shared/keto/quickstart.mdx @@ -4,22 +4,26 @@ import Help from '@site/docs/_common/need-selfhosted-support.mdx' ``` -This example describes a video sharing service. The individual videos are organized in directories. Every directory has an owner -and every video has the same owner as it's parent directory. The owner has elevated privileges about the video files that aren't -modeled individually in Ory Keto. The only other privilege modeled in this example is "view access." Every owner has view access -to their objects, and this privilege can be granted to other users as well. The video sharing application interprets the special -`*` user ID as any user, including anonymous users. Note that Ory Keto doesn't interpret this subject any differently from other -subjects. It also doesn't know anything about directory structures or induced ownership. - -The "Keto client" is the application interacting with Keto. In this case we refer to the video sharing service backend as the Keto -client. +This example describes a video sharing service. The individual videos are +organized in directories. Every directory has an owner and every video has the +same owner as it's parent directory. The owner has elevated privileges about the +video files that aren't modeled individually in Ory Keto. The only other +privilege modeled in this example is "view access." Every owner has view access +to their objects, and this privilege can be granted to other users as well. The +video sharing application interprets the special `*` user ID as any user, +including anonymous users. Note that Ory Keto doesn't interpret this subject any +differently from other subjects. It also doesn't know anything about directory +structures or induced ownership. + +The "Keto client" is the application interacting with Keto. In this case we +refer to the video sharing service backend as the Keto client. ## Starting the example First, install Keto. -Now you can start the example using either `docker-compose` or a bash script. The bash script requires you to have the `keto` -binary in your `$PATH`. +Now you can start the example using either `docker-compose` or a bash script. +The bash script requires you to have the `keto` binary in your `$PATH`. Alternatively, use Docker to automatically get the required images. @@ -48,15 +52,17 @@ docker-compose -f contrib/cat-videos-example/docker-compose.yml up ## State of the system -At the current state only `User:Alice` has added videos. Both videos are in the `/cats` directory owned by `User:Alice`. The file -`File:/cats/1.mp4` can be viewed by anyone (`User:*`), while `Video:/cats/2.mp4` has no extra sharing options, and can therefore -only be viewed by its owner, `User:Alice`. The relationship definitions are located in the +At the current state only `User:Alice` has added videos. Both videos are in the +`/cats` directory owned by `User:Alice`. The file `File:/cats/1.mp4` can be +viewed by anyone (`User:*`), while `Video:/cats/2.mp4` has no extra sharing +options, and can therefore only be viewed by its owner, `User:Alice`. The +relationship definitions are located in the `contrib/cat-videos-example/relation-tuples` directory. ## Simulating the video sharing application -Now you can open a second terminal to run the queries against, just like the video service client would do. In this example we -will use the Keto CLI client. +Now you can open a second terminal to run the queries against, just like the +video service client would do. In this example we will use the Keto CLI client. If you want to run the Keto CLI within **Docker**, set the alias @@ -64,8 +70,8 @@ If you want to run the Keto CLI within **Docker**, set the alias alias keto="docker run -it --network cat-videos-example_default -e KETO_READ_REMOTE=\"keto:4466\" oryd/keto:v25.4.0" ``` -in your terminal session. Alternatively, you need to set the remote endpoint so that the Keto CLI knows where to connect to (not -necessary if using Docker): +in your terminal session. Alternatively, you need to set the remote endpoint so +that the Keto CLI knows where to connect to (not necessary if using Docker): ```shell export KETO_READ_REMOTE="127.0.0.1:4466" @@ -73,8 +79,9 @@ export KETO_READ_REMOTE="127.0.0.1:4466" ### Check incoming requests -First off, we get a request by an anonymous user that would like to view `/cats/2.mp4`. The client now has to ask Keto if that -operation should be allowed or denied. +First off, we get a request by an anonymous user that would like to view +`/cats/2.mp4`. The client now has to ask Keto if that operation should be +allowed or denied. ```shell # Is "*" allowed to "view" the object "videos":"/cats/2.mp4"? @@ -84,11 +91,14 @@ keto check "User:*" view Video /cats/2.mp4 --insecure-disable-transport-security # Denied ``` -We already discussed that this request should be denied, but it's always good to see this in action. +We already discussed that this request should be denied, but it's always good to +see this in action. -Now `User:Alice` wants to change some view permissions of `Video:/cats/1.mp4`. For this, the video service application has to show -all users that are allowed to view the video. It uses Keto's [expand-API](/docs/keto/concepts/api-overview#expand-subject-sets) to -get these data: +Now `User:Alice` wants to change some view permissions of `Video:/cats/1.mp4`. +For this, the video service application has to show all users that are allowed +to view the video. It uses Keto's +[expand-API](/docs/keto/concepts/api-overview#expand-subject-sets) to get these +data: ```shell # Who is allowed to "view" the object "videos":"/cats/2.mp4"? @@ -120,11 +130,12 @@ Video:/cats#owner On the last line, we see that `User:Alice` is the owner of `Video:/cats`. -Note that there is no direct relationship that would grant `Alice` view access on `/cats/1.mp4` as this is indirectly defined via -the ownership relation. +Note that there is no direct relationship that would grant `Alice` view access +on `/cats/1.mp4` as this is indirectly defined via the ownership relation. -The special user `User:*` on the other hand was directly granted view access on the object, as it's a first-level leaf of the -expansion tree. The following CLI command proves that this is the case: +The special user `User:*` on the other hand was directly granted view access on +the object, as it's a first-level leaf of the expansion tree. The following CLI +command proves that this is the case: ```shell # Is "*" allowed to "view" the object "Video":"/cats/1.mp4"? diff --git a/src/components/Shared/kratos/guides/upgrade.mdx b/src/components/Shared/kratos/guides/upgrade.mdx index 7bfa5c29da..814da57bdd 100644 --- a/src/components/Shared/kratos/guides/upgrade.mdx +++ b/src/components/Shared/kratos/guides/upgrade.mdx @@ -2,31 +2,45 @@ Follow this guide when upgrading Ory Kratos to a newer version. :::danger -Back up your data! Applying upgrades can lead to data loss if handled incorrectly. +Back up your data! Applying upgrades can lead to data loss if handled +incorrectly. ::: -1. Review breaking changes. Visit the [CHANGELOG.md](https://github.com/ory/kratos/blob/master/CHANGELOG.md) to see if breaking - changes have been introduced in the version you are upgrading to. +1. Review breaking changes. Visit the + [CHANGELOG.md](https://github.com/ory/kratos/blob/master/CHANGELOG.md) to see + if breaking changes have been introduced in the version you are upgrading to. 1. Backup your data. -1. Update the [Ory Kratos SDK](/docs/kratos/sdk/overview) if used in your application. -1. Install the new version of Ory Kratos. -1. Run [`kratos migrate sql`](/docs/kratos/cli/kratos-migrate-sql) to run the SQL migrations to the new database schema. -1. If you are upgrading to a version that introduces phone number normalization, run `kratos migrate normalize-phone-numbers` - after the new version is deployed and serving traffic. This rewrites existing phone identifiers to E.164 format. See the - [phone normalization guide](/docs/kratos/guides/normalize-phone-numbers) for the recommended rollout sequence. - -Should you run into problems with the upgrade, consider a stepped upgrade and please visit the community -[chat](https://slack.ory.com/) or start a [discussion](https://github.com/ory/kratos/discussions). +1. Update the [Ory Kratos SDK](/docs/kratos/sdk/overview) if used in your + application. +1. Install the new version + of Ory Kratos. +1. Run [`kratos migrate sql`](/docs/kratos/cli/kratos-migrate-sql) to run the + SQL migrations to the new database schema. +1. If you are upgrading to a version that introduces phone number normalization, + run `kratos migrate normalize-phone-numbers` after the new version is + deployed and serving traffic. This rewrites existing phone identifiers to + E.164 format. See the + [phone normalization guide](/docs/kratos/guides/normalize-phone-numbers) for + the recommended rollout sequence. + +Should you run into problems with the upgrade, consider a stepped upgrade and +please visit the community [chat](https://slack.ory.com/) or start a +[discussion](https://github.com/ory/kratos/discussions). #### v0.7 Changed cookie behavior -In [Ory Kratos v0.7](https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes) the cookie behavior has -changed. Review +In +[Ory Kratos v0.7](https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes) +the cookie behavior has changed. Review [changes in the exemplary self-service user interface](https://github.com/ory/kratos-selfservice-ui-node/commit/e7fa292968111e06401fcfc9b1dd0e8e285a4d87). -Visit the [Cookie Settings](https://www.ory.com/kratos/docs/guides/multi-domain-cookies/#cookies) document for more information. +Visit the +[Cookie Settings](https://www.ory.com/kratos/docs/guides/multi-domain-cookies/#cookies) +document for more information. #### v0.10.0 Authenticator assurance level (AAL) in session -Since [Ory Kratos v0.10.0](https://github.com/ory/kratos/blob/v0.10.0/CHANGELOG.md#breaking-changes), the AAL is part of the -session. When upgrading, sessions need to be reissued to observe a higher AAL due to multi-factor methods. +Since +[Ory Kratos v0.10.0](https://github.com/ory/kratos/blob/v0.10.0/CHANGELOG.md#breaking-changes), +the AAL is part of the session. When upgrading, sessions need to be reissued to +observe a higher AAL due to multi-factor methods. From 80a99251ee89017780a905bfa3b82cdb062cf4bd Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Tue, 23 Jun 2026 14:15:41 +0200 Subject: [PATCH 08/10] fix: revert to master --- src/components/Shared/keto/quickstart.mdx | 101 +++++++++++----------- 1 file changed, 52 insertions(+), 49 deletions(-) diff --git a/src/components/Shared/keto/quickstart.mdx b/src/components/Shared/keto/quickstart.mdx index 9d26742ac7..2181bb9fb6 100644 --- a/src/components/Shared/keto/quickstart.mdx +++ b/src/components/Shared/keto/quickstart.mdx @@ -20,7 +20,7 @@ refer to the video sharing service backend as the Keto client. ## Starting the example -First, install Keto. +First, [install Keto](../../../../docs/keto/install). Now you can start the example using either `docker-compose` or a bash script. The bash script requires you to have the `keto` binary in your `$PATH`. @@ -40,22 +40,22 @@ docker-compose -f contrib/cat-videos-example/docker-compose.yml up # output: all initially created relationships -# NAMESPACE OBJECT RELATION NAME SUBJECT -# Video /cats/1.mp4 owner Video:/cats#owner -# Video /cats/1.mp4 view Video:/cats/1.mp4#owner -# Video /cats/1.mp4 view User:* -# Video /cats/2.mp4 owner Video:/cats#owner -# Video /cats/2.mp4 view Video:/cats/2.mp4#owner -# Video /cats owner User:Alice -# Video /cats view Video:/cats#owner +# NAMESPACE OBJECT RELATION NAME SUBJECT +# videos /cats/1.mp4 owner videos:/cats#owner +# videos /cats/1.mp4 view videos:/cats/1.mp4#owner +# videos /cats/1.mp4 view * +# videos /cats/2.mp4 owner videos:/cats#owner +# videos /cats/2.mp4 view videos:/cats/2.mp4#owner +# videos /cats owner cat lady +# videos /cats view videos:/cats#owner ``` ## State of the system -At the current state only `User:Alice` has added videos. Both videos are in the -`/cats` directory owned by `User:Alice`. The file `File:/cats/1.mp4` can be -viewed by anyone (`User:*`), while `Video:/cats/2.mp4` has no extra sharing -options, and can therefore only be viewed by its owner, `User:Alice`. The +At the current state only one user with the username `cat lady` has added +videos. Both videos are in the `/cats` directory owned by `cat lady`. The file +`/cats/1.mp4` can be viewed by anyone (`*`), while `/cats/2.mp4` has no extra +sharing options, and can therefore only be viewed by its owner, `cat lady`. The relationship definitions are located in the `contrib/cat-videos-example/relation-tuples` directory. @@ -67,7 +67,7 @@ video service client would do. In this example we will use the Keto CLI client. If you want to run the Keto CLI within **Docker**, set the alias ```shell -alias keto="docker run -it --network cat-videos-example_default -e KETO_READ_REMOTE=\"keto:4466\" oryd/keto:v25.4.0" +alias keto="docker run -it --network cat-videos-example_default -e KETO_READ_REMOTE=\"keto:4466\" oryd/keto:v0.7.0-alpha.1" ``` in your terminal session. Alternatively, you need to set the remote endpoint so @@ -85,7 +85,7 @@ allowed or denied. ```shell # Is "*" allowed to "view" the object "videos":"/cats/2.mp4"? -keto check "User:*" view Video /cats/2.mp4 --insecure-disable-transport-security +keto check "*" view videos /cats/2.mp4 # output: # Denied @@ -94,52 +94,55 @@ keto check "User:*" view Video /cats/2.mp4 --insecure-disable-transport-security We already discussed that this request should be denied, but it's always good to see this in action. -Now `User:Alice` wants to change some view permissions of `Video:/cats/1.mp4`. -For this, the video service application has to show all users that are allowed -to view the video. It uses Keto's -[expand-API](/docs/keto/concepts/api-overview#expand-subject-sets) to get these -data: +Now `cat lady` wants to change some view permissions of `/cats/1.mp4`. For this, +the video service application has to show all users that are allowed to view the +video. It uses Keto's +[expand-API](../../../../docs/keto/concepts/api-overview#expand-subject-sets) to +get these data: ```shell # Who is allowed to "view" the object "videos":"/cats/2.mp4"? -keto expand view Video /cats/1.mp4 --insecure-disable-transport-security +keto expand view videos /cats/1.mp4 # output: -``` -```keto-tuples -# or :#@Video:/cats/1.mp4#view -# ├──∋ :#@User:*️ -# └──or :#@Video:/cats/1.mp4#owner -# └──or :#@Video:/cats#owner -# └──∋ :#@User:Alice️ +# ∪ videos:/cats/1.mp4#view +# ├─ ∪ videos:/cats/1.mp4#owner +# │ ├─ ∪ videos:/cats#owner +# │ │ ├─ ☘ cat lady️ +# ├─ ☘ *️ ``` -Here we can see the full subject set expansion. The second branch +Here we can see the full subject set expansion. The first branch -```keto-tuples -Video:/cats/1.mp4#owner +```keto-relation-tuples +videos:/cats/1.mp4#view ``` -indicates that every owner of the object is allowed to view the Object. +indicates that every owner of the object is allowed to view + +```keto-relation-tuples +videos:/cats/1.mp4#owner +``` -In the next step we see that the object's owners are the owners of `Video:/cats` +In the next step we see that the object's owners are the owners of `/cats` -```keto-tuples -Video:/cats#owner +```keto-relation-tuples +videos:/cats#owner ``` -On the last line, we see that `User:Alice` is the owner of `Video:/cats`. +We see that `cat lady` is the owner of `/cats`. -Note that there is no direct relationship that would grant `Alice` view access -on `/cats/1.mp4` as this is indirectly defined via the ownership relation. +Note that there is no direct relationship that would grant `cat lady` view +access on `/cats/1.mp4` as this is indirectly defined via the ownership +relation. -The special user `User:*` on the other hand was directly granted view access on -the object, as it's a first-level leaf of the expansion tree. The following CLI +The special user `*` on the other hand was directly granted view access on the +object, as it's a first-level leaf of the expansion tree. The following CLI command proves that this is the case: ```shell -# Is "*" allowed to "view" the object "Video":"/cats/1.mp4"? -keto check "User:*" view Video /cats/1.mp4 --insecure-disable-transport-security +# Is "*" allowed to "view" the object "videos":"/cats/1.mp4"? +keto check "*" view videos /cats/1.mp4 # output: # Allowed @@ -151,21 +154,21 @@ import Mermaid from "@site/src/theme/Mermaid" r2 - r1 ----- sub1(["User:Alice"]) + r1 ----- sub1(["cat lady"]) r1 -.-> r4 obj1 ---- r4((owner)) - r3 --- all(["User:* (anyone)"]) + r3 --- all(["* (anyone)"]) r4 -.-> r3 - obj1[Video:/cats/1.mp4] --- r3((view)) + obj1[videos:/cats/1.mp4] --- r3((view)) obj2 --- r6((view)) r1 -.-> r5 - obj2[Video:/cats/2.mp4] ---- r5((owner)) + obj2[videos/cats/2.mp4] ---- r5((owner)) r5 -.-> r6 - style sub1 fill:green,color:white - style all fill:green,color:white + style sub1 fill:lightgreen + style all fill:lightgreen style r1 fill:darkgreen,color:white style r2 fill:darkgreen,color:white style r3 fill:darkgreen,color:white From 739d7795538000c3f158ddd9da79dcbf2b303dc0 Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Tue, 23 Jun 2026 14:15:49 +0200 Subject: [PATCH 09/10] fix: update installation link format in quickstart guide --- src/components/Shared/keto/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/Shared/keto/quickstart.mdx b/src/components/Shared/keto/quickstart.mdx index 2181bb9fb6..9af1fb797f 100644 --- a/src/components/Shared/keto/quickstart.mdx +++ b/src/components/Shared/keto/quickstart.mdx @@ -20,7 +20,7 @@ refer to the video sharing service backend as the Keto client. ## Starting the example -First, [install Keto](../../../../docs/keto/install). +First, install Keto. Now you can start the example using either `docker-compose` or a bash script. The bash script requires you to have the `keto` binary in your `$PATH`. From 38819a93ff3d52f4c3f35b6d208f5e4789fd9a0f Mon Sep 17 00:00:00 2001 From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com> Date: Tue, 23 Jun 2026 14:38:34 +0200 Subject: [PATCH 10/10] fix: remove outdated redirect for keto quickstart guide --- vercel.json | 5 ----- 1 file changed, 5 deletions(-) diff --git a/vercel.json b/vercel.json index 936fbe597b..48e788c73c 100644 --- a/vercel.json +++ b/vercel.json @@ -1572,11 +1572,6 @@ "destination": "/docs/network/keto/overview", "permanent": false }, - { - "source": "/docs/keto/quickstart", - "destination": "/docs/network/keto/quickstart", - "permanent": false - }, { "source": "/docs/keto/examples/olymp-file-sharing", "destination": "/docs/network/keto/file-sharing-example",