Skip to content

Commit 5a0d0cc

Browse files
zepatrikzepatrik
authored
feat: add basic Keto guides (#850)
1 parent 8beed9b commit 5a0d0cc

File tree

3 files changed

+236
-0
lines changed

3 files changed

+236
-0
lines changed

‎docs/guides/permissions/overview.mdx

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
id: overview
3+
title: Overview
4+
---
5+
6+
The Ory Permission Service ([Keto](https://github.com/ory/keto)) implements Google Zanzibar. It might differ a bit from
7+
other authorization services you know, so let's first clarify a few concepts.
8+
9+
:::note Ory Cloud Availability
10+
11+
The Permission Service is available to all Ory Cloud users without additional fees or setup. The API is in a production-ready state. The documentation, integration, and UI are under active development.
12+
13+
:::
14+
15+
## Relations and Relation Tuples
16+
17+
The data model used by the Permission Service are so-called [relation tuples](/keto/concepts/relation-tuples.mdx) that encode relations between [subjects](/keto/concepts/subjects.mdx) and [objects](/keto/concepts/objects.mdx).
18+
19+
:::tip
20+
21+
Read the dedicated documents to learn more about [subjects](/keto/concepts/subjects.mdx) and [objects](/keto/concepts/objects.mdx).
22+
23+
:::
24+
25+
Examples of relation tuples are:
26+
27+
- `user1` is `member` of `groups:group1`
28+
- `member` of `groups:group1` is `reader` of `files:file1`
29+
30+
As you can see, the subject of a relation tuple can either be a specific subject ID, or subjects defined through an [indirection](https://en.wikipedia.org/wiki/Indirection)
31+
(all members of a certain group). The object is referenced by its ID.
32+
33+
## Checking Permissions
34+
35+
Permissions are just another form of relations. Therefore, a permission check is a request to check whether a subject has a
36+
certain relation to an object, possibly through one or more indirections.
37+
38+
As a very simple example, we assume the following tuples exist:
39+
40+
- `user1` is `member` of `groups:group1`
41+
- `member` of `groups:group1` is `reader` of `files:file1`
42+
43+
Now, one could ask:
44+
45+
- Is `user1` a `reader` of `files:file1`? - Yes, because `user1` is a `member` of `groups:group1` and all `member`s of `groups:group1` are `reader` of `files:file1`.
46+
- Is `user2` a `member` of `groups:group1`? - No.
47+
48+
## Example
49+
50+
This example setup demonstrates the basics of relation tuple management and usage of the Check API.
51+
52+
### Defining Namespaces
53+
54+
Relation tuples reside in [namespaces](/keto/concepts/namespaces.mdx). To create relation tuples, you must define their namespace first.
55+
56+
````mdx-code-block
57+
import CodeBlock from '@theme/CodeBlock'
58+
import Tabs from '@theme/Tabs';
59+
import TabItem from '@theme/TabItem';
60+
61+
<Tabs>
62+
<TabItem value="cloud" label="Ory CLI" default>
63+
64+
```shell
65+
ory patch permission-config <your-project-id> \
66+
--add '/namespaces/-={"id": 0, "name": "resources"}' \
67+
--add '/namespaces/-={"id": 1, "name": "groups"}'
68+
```
69+
70+
</TabItem>
71+
<TabItem value="self-hosted" label="Self-Hosted Ory Keto Config" default>
72+
73+
```yaml title=path/to/keto.yml
74+
namespaces:
75+
- id: 0
76+
name: resources
77+
- id: 1
78+
name: groups
79+
```
80+
81+
</TabItem>
82+
</Tabs>
83+
````
84+
85+
### Creating Relation Tuples
86+
87+
After creating the namespaces, you can use the [relation tuple APIs](/reference/api.mdx#operation/createRelationTuple) to create a relation tuple.
88+
89+
````mdx-code-block
90+
<Tabs>
91+
<TabItem value="cloud" label="Ory Cloud" default>
92+
93+
```shell
94+
ORY_PAT="<your ory personal access token from the console>"
95+
ORY_SDK_URL="<your ory project sdk url from the console>"
96+
97+
echo '[
98+
{
99+
"action": "insert",
100+
"relation_tuple": {
101+
"subject_id": "user1",
102+
"relation": "member",
103+
"namespace": "groups",
104+
"object": "group1"
105+
}
106+
}, {
107+
"action": "insert",
108+
"relation_tuple": {
109+
"subject_set": {
110+
"relation": "member",
111+
"namespace": "groups",
112+
"object": "group1"
113+
},
114+
"relation": "owner",
115+
"namespace": "resources",
116+
"object": "file1"
117+
}
118+
}
119+
]' > relationtuple.json
120+
121+
curl -X PATCH \
122+
-H "Content-Type: application/json" \
123+
-H "Authorization: Bearer $ORY_PAT" \
124+
-d @relationtuple.json \
125+
"$ORY_SDK_URL/admin/relation-tuples"
126+
```
127+
128+
</TabItem>
129+
<TabItem value="self-hosted" label="Self-Hosted Ory Keto" default>
130+
131+
```shell
132+
KETO_WRITE_URL="<your keto write url>"
133+
134+
echo '[
135+
{
136+
"action": "insert"
137+
"relation_tuple": {
138+
"subject_id": "user1",
139+
"relation": "member",
140+
"namespace": "groups",
141+
"object": "group1"
142+
}
143+
}, {
144+
"action": "insert"
145+
"relation_tuple": {
146+
"subject_set": {
147+
"relation": "member",
148+
"namespace": "groups",
149+
"object": "group1"
150+
},
151+
"relation": "owner",
152+
"namespace": "resources",
153+
"object": "file1"
154+
}
155+
}
156+
]' > relationtuple.json
157+
158+
curl -X PUT \
159+
-H "Content-Type: application/json" \
160+
-d @relationtuple.json \
161+
"$KETO_WRITE_URL/admin/relation-tuples"
162+
```
163+
164+
</TabItem>
165+
</Tabs>
166+
````
167+
168+
### Checking Permissions
169+
170+
Permission checks are requests that check whether a subject has a relation to an object.
171+
This relation can be directly defined, or constructed following indirections (e.g. members of a group).
172+
173+
The [Check API](/reference/api.mdx#operation/postCheck) allows to perform such checks:
174+
175+
````mdx-code-block
176+
<Tabs>
177+
<TabItem value="cloud" label="Ory Cloud" default>
178+
179+
```shell
180+
ORY_PAT="<your ory personal access token from the console>"
181+
ORY_SDK_URL="<your ory project sdk url from the console>"
182+
183+
echo '{
184+
"subject_id": "user1",
185+
"relation": "owner",
186+
"namespace": "resources",
187+
"object": "file1"
188+
}' > query.json
189+
190+
curl -X POST \
191+
-H "Content-Type: application/json" \
192+
-H "Authorization: Bearer $ORY_PAT" \
193+
-d @query.json \
194+
"$ORY_SDK_URL/relation-tuples/check"
195+
# should print:
196+
# {"allowed":true}
197+
```
198+
199+
</TabItem>
200+
<TabItem value="self-hosted" label="Self-Hosted Ory Keto" default>
201+
202+
```shell
203+
KETO_WRITE_URL="<your keto write url>"
204+
205+
echo '{
206+
"subject_id": "user1",
207+
"relation": "owner",
208+
"namespace": "resources",
209+
"object": "file1"
210+
}' > query.json
211+
212+
curl -X POST \
213+
-H "Content-Type: application/json" \
214+
-d @query.json \
215+
"$KETO_WRITE_URL/relation-tuples/check"
216+
# should print:
217+
# {"allowed":true}
218+
```
219+
220+
</TabItem>
221+
</Tabs>
222+
````

‎docs/welcome.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,13 @@ Ory Cloud incorporates the open source [Ory Kratos](https://www.ory.sh/kratos) p
7373
accept tos, shipping address, gender, ...) and create your own login, registration, profile settings, recovery, and verification
7474
screen using our easy to use SDKs and REST APIs.
7575

76+
### Permission Services
77+
78+
Ory Cloud incorporates the open source [Ory Keto](https://www.ory.sh/keto) project and offers:
79+
80+
- **Permission management** to get, create, update, and delete permissions.
81+
- **Permission checking** to check if a user has a permission.
82+
7683
## Ory Open Source
7784

7885
Ory is the largest open source ecosystem in the area of authentication, authorization, access control, and zero trust networking

‎src/sidebar.js

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,13 @@ module.exports = {
8989
'guides/manage-identities/managing-users-identities-metadata'
9090
]
9191
},
92+
{
93+
type: 'category',
94+
label: 'Permissions',
95+
items: [
96+
'guides/permissions/overview'
97+
]
98+
},
9299
{
93100
type: 'category',
94101
label: 'Social Sign-in',

0 commit comments

Comments
 (0)