Skip to content

Commit 31ca110

Browse files
joakimnordlinglietu
joakimnordling
and
lietu
authored
Update creating/managing groups guide + separate party configuration (#35)
* Update creating/managing groups guide + separate party configuration This updates cleans up and updates the guide for creating and managing groups and separates the party configuration details to a new guide. * Update src/routes/guides/managing-groups/+page.svelte Co-authored-by: Janne Enberg <janne.enberg@lietu.net> * Apply suggestions from code review Co-authored-by: Janne Enberg <janne.enberg@lietu.net> * Add details based on feedback * Update image with one with email addresses * Optimize images --------- Co-authored-by: Janne Enberg <janne.enberg@lietu.net>
1 parent a43c38f commit 31ca110

12 files changed

Lines changed: 177 additions & 65 deletions

File tree

‎src/routes/guides/images.json‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -140,15 +140,28 @@
140140
}
141141
},
142142
"MANAGE_GROUP": {
143-
"EDITING_A_GROUP": {
144-
"src": "/guides/managing-groups/editing_a_group.png",
145-
"alt": "Editing a group page in Developer Portal"
143+
"MY_GROUPS_BUTTON": {
144+
"src": "/guides/managing-groups/my_groups_button.png",
145+
"alt": "My groups page with the Add a group button"
146146
},
147-
"PAGE_FOR_CREATING_GROUPS": {
148-
"src": "/guides/managing-groups/page_for_creating_groups.png",
149-
"alt": "Create a group page in Developer Portal"
147+
"MY_GROUPS_DISCLAIMER": {
148+
"src": "/guides/managing-groups/my_groups_disclaimer.png",
149+
"alt": "My groups page with disclaimer"
150+
},
151+
"CREATE_GROUP_PAGE": {
152+
"src": "/guides/managing-groups/create_group_page.png",
153+
"alt": "Create a group page"
154+
},
155+
"GROUP_LISTING": {
156+
"src": "/guides/managing-groups/group_listing.png",
157+
"alt": "List items on the My groups page"
158+
},
159+
"EDIT_GROUP": {
160+
"src": "/guides/managing-groups/edit_group.png",
161+
"alt": "Edit group page"
150162
}
151163
},
164+
"PARTY_CONFIGURATION": {},
152165
"USING_DATA": {
153166
"MENU_DATA_SOURCES": {
154167
"src": "/guides/using-data-from-data-sources/menu_data_sources.png",

‎src/routes/guides/managing-groups/+page.svelte‎

Lines changed: 58 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
<script lang="ts">
22
import SectionTitle from "$lib/components/SectionTitle.svelte"
3-
import Code from "$lib/components/Code.svelte"
4-
import json from "svelte-highlight/languages/json"
53
import A from "$lib/components/A.svelte"
64
import Breadcrumbs from "$lib/components/Breadcrumbs.svelte"
75
import Title from "$lib/components/Title.svelte"
86
import TableOfContents from "$lib/components/TableOfContents.svelte"
97
import GuideImage from "$lib/components/GuideImage.svelte"
108
import type { PageData } from "./$types"
9+
import { GUIDES } from "../urls"
1110
1211
export let data: PageData
1312
@@ -21,73 +20,73 @@
2120

2221
<SectionTitle title="Introduction" />
2322
<p>
24-
A group is needed both for data sources and for applications. You create a group in the
25-
developer portal. You have to input a unique name for the group and then input the party
26-
configuration domain where you hosted a party configuration you set up. In case you have an
27-
existing group without a party configuration you can find the group in your list of groups, edit
28-
it, add the party configuration domain and click the update button.
23+
A group is needed both to create data sources and to be able to request data from data sources
24+
that use access control.
25+
</p>
26+
27+
<SectionTitle title="Creating a group" />
28+
29+
<p>
30+
You can create a group in the <em>My groups</em> section using the <em>Add a group</em> button.
31+
</p>
32+
<GuideImage img={images.MY_GROUPS_BUTTON} />
33+
<p>
34+
<strong>Note:</strong> In some IOXIO data sharing services, such as
35+
<A href="https://ioxio.io/">IOXIO.io</A> the group creation is restricted and the group is instead
36+
created by the support upon separate requests and verification. In that case the
37+
<em>My groups</em> page has a disclaimer with instructions to follow. Please also after it has
38+
been created follow the steps in<A href="#editing-a-group">Editing a group</A> section of this guide
39+
to fill in a GDPR and technical contact for the group.
40+
</p>
41+
<GuideImage img={images.MY_GROUPS_DISCLAIMER} />
42+
<GuideImage img={images.CREATE_GROUP_PAGE} />
43+
<p>
44+
When creating the group, note that the name of the group needs to be unique for the data sharing
45+
service, can consist of lower case letters a-z, underscores and numbers, and be at most 64
46+
characters long.
2947
</p>
3048
<p>
31-
Note that some dataspaces require groups to be created by staff, so if the page has a notice
32-
saying so, please follow the instructions written on it.
49+
The group should also have a GDPR contact, as well as a technical contact that can be contacted
50+
in case of technical problems, such as problems with requesting data from data sources or
51+
requests to data sources made by the group. It's recommended that these addresses are generic
52+
gdpr@ or support@ -style addresses where applicable so you don't have to worry about updating
53+
them as your team changes.
3354
</p>
34-
<GuideImage img={images.PAGE_FOR_CREATING_GROUPS} />
35-
<GuideImage img={images.EDITING_A_GROUP} />
36-
<SectionTitle title="Creating and hosting party configuration" />
3755
<p>
38-
<strong>1.</strong>
39-
Select a domain (it can also be a subdomain) on which you want to host your party configuration.
40-
<br />
41-
<strong>Note:</strong> You will need to be able to create a file at
42-
<em>/.well-known/dataspace/party-configuration.json</em>
43-
on that domain and it needs to be accessible over <em>https://</em> with a valid certificate.
56+
The group can also optionally have a party configuration domain; a domain on which a party (the
57+
group) publishes standardized configuration files. In most cases this should be left empty. It
58+
is only needed if the group is going to use HTTP Message Signatures or intends to use the
59+
consent protocol prototype (only available on a limited set of IOXIO data sharing services). To
60+
set it up, see the
61+
<A href={GUIDES.PARTY_CONFIGURATION.href}>{GUIDES.PARTY_CONFIGURATION.title}</A> guide for details
62+
before entering the domain here.
4463
</p>
4564
<p>
46-
<strong>2.</strong>
47-
Create the <em>party-configuration.json</em> and host it on the desired domain. See
48-
<A href="/schemas/party-configuration/">party configuration schema</A>
49-
for more details.
65+
Once you have filled in all the required fields, press the <em>Create</em> button.
5066
</p>
67+
68+
<SectionTitle title="Editing a group" />
69+
5170
<p>
52-
<strong>3.</strong>
53-
Ensure the <em>jwks_uri</em> points to some <em>https://</em> based domain and a location you
54-
can control. A suggestion is to point it to the <em>/.well-known/jwks.json</em> on the same
55-
domain as the party configuration.<br />Example from
56-
<A href="/schemas/party-configuration">https://docs.ioxio.dev/schemas/party-configuration</A>:
71+
You can also open any of your groups for editing from the <em>My groups</em> page by pressing
72+
the <em>View</em> button next to it.
5773
</p>
58-
<Code lang={json}>
59-
{`
60-
{
61-
"jwks_uri": "https://ioxio.com/.well-known/jwks.json"
62-
}
63-
`}
64-
</Code>
74+
<GuideImage img={images.GROUP_LISTING} />
75+
76+
<GuideImage img={images.EDIT_GROUP} />
77+
6578
<p>
66-
<strong>4.</strong>
67-
Create the content for the <em>jwks_uri</em> and host it in the location you specified in the
68-
party configuration. For this, you will need to generate an RSA public/private keypair. Ensure
69-
there is at least one key and that it has a <em>kid</em>, the <em>kty</em> is <em>RSA</em>, the
70-
<em>use</em>
71-
is set to <em>sig</em>, the <em>alg</em>
72-
is <em>RS256</em> and it has the <em>n</em> and <em>e</em> parameters. Here is an example of
73-
what it should look like from
74-
<A href="https://ioxio.com/.well-known/jwks.json">https://ioxio.com/.well-known/jwks.json</A>:
79+
If your group was created by support, please ensure you fill in a GDPR contact and a technical
80+
contact.
7581
</p>
7682

77-
<Code lang={json}>
78-
{`
79-
{
80-
"keys": [
81-
{
82-
"kid": "302feac8851574f3ef74ec1c62a7489f",
83-
"kty": "RSA",
84-
"use": "sig",
85-
"alg": "RS256",
86-
"n": "wO_R-_1EUodohCn9mIf3lxH70IFDLIsSbSLg3rNbKJIexFlxE8X72_gFGwMoZJqbeNfEDcPI9UiSXM6H9z_bpfVF7jxtvvyCqSmy-R5miadGoiiYUZpRvK-nxyjOiXlobsaPOgXiC3tCwxZ4EfXznzu5WZm2ekSeIf9nj-NKuPNuUpfCLH6Jbfq7PzWq5BMnmjEwz_VXqqk58mkqgFwr_0BRh2I2i5ufHTixyUGV7u7NK1WkkeIF4VbQILpO0t5-yxO6by2r3A_pubjSUmy8F5FSqqWkxNOfv5svFLnbCTvFuXVonjMqs6MD4BFVjRRhSI9NDWfjTisy-EKNpmWtbM0WAqk2hwey-dE8Fd0B7FmR9GmWt8oR5-LN3QgoRa8_z-h0dYhSWi6vV7dBJxHtyFFVJSTHw3xwCpg6PdeuB8OxqlSuLxry5tMVGNv9humih_92tPbAOq3luAuUuVKmxEgZ-_bk3y9Gxo2YutFfTI8QcaBEyqiao040NIJiNJ0z0OiBodalGny-sHL51Y7iB_z8TYIs8aie_WDfpXRg5IP5UbZ3Onl84IIrH3RbsM2p889-qEpMRXJJY5pQVjur3LIlx2TQ3ir7nBqGYC_5JAeq0sDFonvFGGTfWA_e_QDLKth9Dz2-HPVCUqBsdyF2Es7Ot1ijBV9rVKiaGUtx67M",
87-
"e": "AQAB"
88-
}
89-
]
90-
}
91-
`}
92-
</Code>
83+
<SectionTitle title="Next steps" />
84+
85+
<p>When you have a group, you might want to check out the following guides:</p>
86+
87+
<ul>
88+
<li><A href={GUIDES.MANAGE_GROUP_MEMBERS.href}>{GUIDES.MANAGE_GROUP_MEMBERS.title}</A></li>
89+
<li><A href={GUIDES.BUILD_DATA_SOURCE.href}>{GUIDES.BUILD_DATA_SOURCE.title}</A></li>
90+
<li><A href={GUIDES.USING_DATA.href}>{GUIDES.USING_DATA.title}</A></li>
91+
</ul>
9392
</TableOfContents>

‎src/routes/guides/party-configuration/+page.server.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
import IMAGES from "../images.json"
2+
import { GUIDES } from "../urls"
3+
4+
export async function load({ url, route }) {
5+
return {
6+
path: url.pathname,
7+
route: route.id,
8+
guide: GUIDES.PARTY_CONFIGURATION,
9+
images: IMAGES.PARTY_CONFIGURATION,
10+
}
11+
}

‎src/routes/guides/party-configuration/+page.svelte‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<script lang="ts">
2+
import SectionTitle from "$lib/components/SectionTitle.svelte"
3+
import Code from "$lib/components/Code.svelte"
4+
import json from "svelte-highlight/languages/json"
5+
import Breadcrumbs from "$lib/components/Breadcrumbs.svelte"
6+
import Title from "$lib/components/Title.svelte"
7+
import TableOfContents from "$lib/components/TableOfContents.svelte"
8+
9+
import type { PageData } from "./$types"
10+
import A from "$lib/components/A.svelte"
11+
12+
export let data: PageData
13+
</script>
14+
15+
<TableOfContents>
16+
<Title title={data.guide.title} />
17+
18+
<Breadcrumbs path={data.path} />
19+
20+
<SectionTitle title="Introduction" />
21+
22+
<p>
23+
On the IOXIO data sharing services groups can optionally have a party configuration domain; a
24+
domain on which a party (the group) publishes standardized configuration files. They are used
25+
with HTTP Message Signatures or with the consent protocol prototype, which is available only on
26+
some data sharing services.
27+
</p>
28+
29+
<p>This guide explains how to set up the necessary configuration files.</p>
30+
31+
<SectionTitle title="Creating and hosting party configuration" />
32+
<p>
33+
<strong>1.</strong>
34+
Select a domain (it can also be a subdomain) on which you want to host your party configuration.
35+
<br />
36+
<strong>Note:</strong> You will need to be able to create a file at
37+
<em>/.well-known/dataspace/party-configuration.json</em> on that domain and it needs to be
38+
accessible over <em>https://</em> with a valid certificate.
39+
</p>
40+
<p>
41+
<strong>2.</strong>
42+
Create the <em>party-configuration.json</em> and host it on the desired domain. See
43+
<A href="/schemas/party-configuration/">party configuration schema</A> for more details.
44+
</p>
45+
<p>
46+
<strong>3.</strong>
47+
Ensure the <em>jwks_uri</em> points to some <em>https://</em> based domain and a location you
48+
can control. A suggestion is to point it to the <em>/.well-known/jwks.json</em> on the same
49+
domain as the party configuration.<br />Example from
50+
<A href="/schemas/party-configuration">https://docs.ioxio.dev/schemas/party-configuration</A>:
51+
</p>
52+
<Code lang={json}>
53+
{`
54+
{
55+
"jwks_uri": "https://ioxio.com/.well-known/jwks.json"
56+
}
57+
`}
58+
</Code>
59+
<p>
60+
<strong>4.</strong>
61+
Create the content for the <em>jwks_uri</em> and host it in the location you specified in the
62+
party configuration. For this, you will need to generate an RSA public/private keypair. Ensure
63+
there is at least one key and that it has a <em>kid</em>, the <em>kty</em> is <em>RSA</em>, the
64+
<em>use</em> is set to <em>sig</em>, the <em>alg</em> is <em>RS256</em> and it has the
65+
<em>n</em> and <em>e</em> parameters. Here is an example of what it should look like from
66+
<A href="https://ioxio.com/.well-known/jwks.json">https://ioxio.com/.well-known/jwks.json</A>:
67+
</p>
68+
69+
<Code lang={json}>
70+
{`
71+
{
72+
"keys": [
73+
{
74+
"kid": "302feac8851574f3ef74ec1c62a7489f",
75+
"kty": "RSA",
76+
"use": "sig",
77+
"alg": "RS256",
78+
"n": "wO_R-_1...tx67M",
79+
"e": "AQAB"
80+
}
81+
]
82+
}
83+
`}
84+
</Code>
85+
</TableOfContents>

‎src/routes/guides/urls.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ export const GUIDES = {
2323
title: "Using data from data sources",
2424
href: "/guides/using-data-from-data-sources",
2525
},
26+
PARTY_CONFIGURATION: {
27+
title: "Setting up a party configuration domain",
28+
href: "/guides/party-configuration",
29+
},
2630
BUILD_APP: {
2731
title: "Legacy: Building an application",
2832
href: "/guides/building-an-application",

‎static/guides/managing-groups/create_group_page.png‎

139 KB
Loading

‎static/guides/managing-groups/edit_group.png‎

163 KB
Loading

‎static/guides/managing-groups/editing_a_group.png‎

-157 KB
Binary file not shown.

‎static/guides/managing-groups/group_listing.png‎

14.1 KB
Loading

‎static/guides/managing-groups/my_groups_button.png‎

99.6 KB
Loading

0 commit comments

Comments
 (0)