Skip to content

Commit e38f1ac

Browse files
AndrewThienAndrewThien
authored
Add Sub layer entities management (#19)
* initial add co-ordinate setup pages * improve the index page * add prettier ignore * improve TRE deployment steps * improve Sub deployment steps * add page to add realm user * change name route * add path to ignore * add creating realm user step * improve config of tre * update config of sub * move the cofig * move out of journey * fix spelling * under construction * fix data * fix tag * structure the pages * add Prerequisites * resolve merge conflict * done add user * add link and callout * add more details * done register new TRE * add what next * done proejct * done assign * improve * done adding KC user * add things in * more details * change type * modify wording * update workflow
1 parent 6020626 commit e38f1ac

23 files changed

Lines changed: 361 additions & 15 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ jobs:
4040
- name: Setup Node
4141
uses: actions/setup-node@v5
4242
with:
43-
node-version: "22"
43+
node-version: "24"
4444
cache: npm
4545

4646
- name: Setup Pages

‎.prettierignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
app/connect/setup-tre/deployment-steps/page.mdx
22
app/co-ordinate/setup-sub-layer/deployment-steps/page.mdx
3-
app/co-ordinate/entity-management/add-realm-admin/page.mdx
3+
app/co-ordinate/entity-management/add-realm-admin/page.mdx
4+
app/co-ordinate/entity-management/assign-tre-user-to-project/page.mdx
5+
app/connect/controlling-tre-data-access/page.mdx
6+
app/connect/components/page.mdx
7+
app/co-ordinate/entity-management/add-keycloak-user/page.mdx

‎app/co-ordinate/entity-management/_meta.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
11
export default {
22
"add-realm-admin": "Add a Realm admin",
3+
"add-keycloak-user": "Add a Keycloak user", // Hidden from navigation for now because it not belongs to any card
4+
"add-new-researcher": "Add a new Researcher",
5+
"register-a-tre": "Register a new TRE",
6+
"setup-new-project": "Setup a new Project",
7+
"assign-tre-user-to-project": "Assign TRE and Researcher to a Project",
38
};

‎app/co-ordinate/entity-management/add-keycloak-user/page.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Add a Keycloak user
3+
readingTime: PT15M
4+
audiences: [federation-operator, tre-operator, contributor]
5+
docType: guide
6+
display: hidden # Hide from navigation for now because it not belongs to any card
7+
---
8+
9+
import { Steps, Callout } from "nextra/components";
10+
import { DocMetadata } from "@/components/doc-metadata/DocMetadata";
11+
12+
<DocMetadata />
13+
14+
# Adding a Keycloak User
15+
16+
This guide describes how to add a new user to the Keycloak instance, especially for the Submission Layer and TRE Layer in 5S-TES.
17+
18+
## Prerequisites
19+
20+
- Access to Keycloak Admin Console as Administrator user
21+
- Information about the user to be added:
22+
- Username
23+
- First Name
24+
- Last Name
25+
- Email
26+
- Role
27+
28+
## Steps
29+
30+
<Steps>
31+
### Login to Keycloak and navigate to the intended Realm
32+
33+
- Login as an admin user (of the master realm) to Keycloak server of the service you are adding the user to (e.g., Submission Layer, TRE Layer, etc.).
34+
- Use `Manage realms` to navigate to the realm you are adding the user to, i.e., `Dare-Control` for Submission Layer, `Dare-TRE` for TRE Layer and `Data-Egress` for Egress Layer.
35+
36+
### Navigate to the Users page.
37+
38+
Navigate to the `Users` page.
39+
40+
### Open Create User dialog.
41+
42+
Click on the blue 'Add user' button to open the 'Create user' dialog.
43+
44+
![Add user dialog](/images/manage-entities/keycloak-CreateUser.png)
45+
46+
### Enter User Details, and Assign to Required Groups.
47+
48+
1. Select the required user actions on first log-in
49+
(this is optional, and recommended to be left blank)
50+
2. Select if email is verified
51+
3. Set Username (mandatory)
52+
4. Set Email, First and Last names (optional, recommended to be filled in)
53+
5. Open the 'Select groups to join' dialog by clicking the 'Join Groups' button.
54+
Select the required groups (as noted in the prerequisites).
55+
6. Finally, click the blue 'Create' button at the bottom of the screen.
56+
57+
<Callout >
58+
- In a Submission Layer, to be able to add/remove people to/from a project,
59+
users need to have `dare-control-admin` role (Role Mapping tab) and joined
60+
`dare-control-admin` group (Groups tab) on KeyCloak.
61+
- To access the TRE Layer's storage, users need to have `dare-tre-admin` role
62+
(Role Mapping tab) and joined `dare-tre-admin` group (Groups tab) on KeyCloak.
63+
</Callout>
64+
65+
### Apply any Required Extra Configurations
66+
67+
Once the user account has been created then
68+
the 'User details' page for the new user will be displayed.
69+
At this point you can set any required extra configurations (e.g., password, role, group) for the new account.
70+
71+
![Change user details](/images/manage-entities/KeyCloak_ChangeUserDetails.png)
72+
73+
<Callout type="info">
74+
- You can use the `Credentials` tab to set a temporary or permanent password for the user.
75+
- You can use the `Details` tab to set any required extra configurations for the new account.
76+
- You can use the `Role Mapping` tab to set the role for the user. For example, Submission Layer admin needs to have `dare-control-admin` role.
77+
- You can use the `Groups` tab to set the groups for the user. For example, Submission Layer admin needs to be joined `dare-control-admin` group.
78+
</Callout>
79+
80+
81+
</Steps>

‎app/co-ordinate/entity-management/add-new-researcher/page.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Add a new Researcher
3+
readingTime: PT5M
4+
audiences: federation-operator
5+
docType: guide
6+
---
7+
8+
import { Steps, Callout } from "nextra/components";
9+
import { DocMetadata } from "@/components/doc-metadata/DocMetadata";
10+
11+
<DocMetadata />
12+
13+
# Adding a New Researcher
14+
15+
This guide describes how to add a new Researcher to the Keycloak instance.
16+
17+
## Prerequisites
18+
19+
- A Submission Layer Administrator user - Submission Layer's Keycloak Admin has to create a Submission Layer Admin user with `dare-control-admin` role using this [guide](/co-ordinate/entity-management/add-keycloak-user)
20+
- A Submission Layer Researcher user - Submission Layer's Keycloak Admin has to create a new user in Keycloak with the `default-roles-dare-control` role using this [guide](/co-ordinate/entity-management/add-keycloak-user)
21+
- Access to the Submission Layer as a Submission Layer administrator user
22+
23+
## Steps
24+
25+
<Steps>
26+
### Login to the Submission Layer
27+
28+
Login to the Submission Layer as Submission Layer Administrator.
29+
30+
### Open the `Create New User` page
31+
32+
Select the `People` tab at the top of the home page. This will display the list of existing users.
33+
34+
Click the blue `+ Create New User` button at the top-right of the `People` page. This will open the `Create User` page.
35+
36+
![Create New User](/images/manage-entities/create-new-user.png)
37+
38+
### Fill in the Researcher details
39+
40+
Enter the user details:
41+
42+
- Full Name (mandatory)
43+
- Username (mandatory)
44+
- Email (mandatory)
45+
46+
<Callout>
47+
The username must match the username entered into Keycloak for the same
48+
Researcher user.
49+
</Callout>
50+
51+
![Create Researcher from](/images/manage-entities/create-new-user-form.png)
52+
53+
### Submit the form
54+
55+
Once all details have been added click the blue `Submit` button. This will return you to the `People` page, where the new user will be displayed.
56+
57+
</Steps>
58+
59+
## What's next?
60+
61+
- [Register a new TRE](/co-ordinate/entity-management/register-a-tre)
62+
- [Assign TRE and Researcher to a Project](/co-ordinate/entity-management/assign-tre-user-to-project)

‎app/co-ordinate/entity-management/assign-tre-user-to-project/page.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Assign TRE and Researcher to a Project
3+
readingTime: PT15M
4+
audiences: federation-operator
5+
docType: guide
6+
---
7+
8+
import { Steps, Callout } from "nextra/components";
9+
import { DocMetadata } from "@/components/doc-metadata/DocMetadata";
10+
11+
<DocMetadata />
12+
13+
# Assigning a TRE and Researcher to a Project
14+
15+
This guide describes how to assign a TRE and Researcher to a Project.
16+
17+
## Prerequisites
18+
19+
- List of Researchers and TREs of the target Project
20+
- A Submission Layer Administrator user - Keycloak Admin has to create a Submission Layer Admin user with `dare-control-admin` role and `dare-control-admin` group using this [guide](/co-ordinate/entity-management/add-keycloak-user)
21+
- Access to the Submission Layer as a Submission Layer administrator user
22+
23+
<Steps>
24+
### Login to the Submission Layer
25+
26+
Login to the Submission Layer as Submission Layer Administrator.
27+
28+
### Open the `Project` page
29+
30+
Select the `Projects` tab at the top of the home page. This will display the list of existing Projects.
31+
32+
Click on the project name to open the project details page.
33+
34+
### Assign TRE and Researcher to the Project
35+
36+
**To assign Researchers:**
37+
38+
- click on the `People` tab. This will display the list of Researchers assigned to the project.
39+
- click on the `+ Add User` button to add a new Researcher to the project.
40+
- select the Researcher you wish to assign to the project from the list of available Researchers.
41+
- click on the `Add` button to save the changes.
42+
43+
![Assign Researcher to Project](/images/manage-entities/assign-researcher.png)
44+
45+
**To assign TREs:**
46+
47+
- click on the `TREs` tab. This will display the list of TREs assigned to the project.
48+
- click on the `+ Add TRE` button to add a new TRE to the project.
49+
- select the TRE you wish to assign to the project from the list of available TREs.
50+
- click on the `Add` button to save the changes.
51+
52+
![Assign TRE to Project](/images/manage-entities/assign-tre.png)
53+
54+
<Callout>
55+
- Click on the TRE or Researcher name to open the TRE or Researcher details page.
56+
- TRE and Researcher can be assigned to multiple projects.
57+
- To remove a TRE or Researcher from a project, click on the bin icon button on the TRE or Researcher row.
58+
</Callout>
59+
60+
</Steps>
61+
62+
{/* ## What's next? TODO: add What's next section */}

‎app/co-ordinate/entity-management/register-a-tre/page.mdx‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Register a new TRE
3+
readingTime: PT15M
4+
audiences: federation-operator
5+
docType: guide
6+
---
7+
8+
import { Steps, Callout } from "nextra/components";
9+
import { DocMetadata } from "@/components/doc-metadata/DocMetadata";
10+
11+
<DocMetadata />
12+
13+
# Registering a TRE
14+
15+
This guide describes how to register a TRE to the Submission Layer.
16+
17+
## Prerequisites
18+
19+
- A Submission Layer Administrator user - Submission Layer's Keycloak Admin has to create a Submission Layer Admin user with `dare-control-admin` role using this [guide](/co-ordinate/entity-management/add-keycloak-user)
20+
- A TRE admin user - Submission Layer's Keycloak Admin has to create a new user in Keycloak with the `dare-tre-admin` role using this [guide](/co-ordinate/entity-management/add-keycloak-user). The credentials of this user will be used by TRE Operator to connect their TRE to the Submission Layer.
21+
- Name of the TRE - This is the name of the TRE that will be registered to the Submission Layer, and should be given by the TRE administrator.
22+
- Access to the Submission Layer as a Submission Layer administrator user
23+
24+
## Steps
25+
26+
<Steps>
27+
### Login to the Submission Layer
28+
29+
Login to the Submission Layer as Submission Layer Administrator.
30+
31+
### Open the `Create New TRE` page
32+
33+
Select the `TREs` tab at the top of the home page. This will display the list of existing TREs.
34+
35+
Click the blue `+ Create New TRE` button at the top-right of the `TREs` page. This will open the `Create TRE` page.
36+
37+
![Create New TRE ](/images/manage-entities/create-new-tre.png)
38+
39+
### Fill in the TRE details
40+
41+
- Name of the TRE (mandatory)
42+
- Username of the TRE administrator created in Keycloak with the `dare-tre-admin` role for the TRE with the name above (mandatory)
43+
44+
![Create TRE](/images/manage-entities/create-tre-form.png)
45+
46+
### Submit the form
47+
48+
Once all details have been added click the blue `Submit` button. This will return you to the `TREs` page, where the new TRE will be displayed.
49+
50+
<Callout>
51+
During creation, the Submission Layer automatically:
52+
- Creates a dedicated Keycloak client for the TRE.
53+
- Enables a service account for the client.
54+
- Assigns the `dare-tre-admin` role to the service account.
55+
- Stores the generated credentials securely in Vault.
56+
57+
</Callout>
58+
59+
</Steps>
60+
61+
## What's next?
62+
63+
- [Setup a new Project](/co-ordinate/entity-management/setup-new-project)
64+
- [Assign TRE to a Project](/co-ordinate/entity-management/assign-tre-user-to-project)

‎app/co-ordinate/entity-management/setup-new-project/page.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: Setup a new Project
3+
readingTime: PT15M
4+
audiences: federation-operator
5+
docType: guide
6+
---
7+
8+
import { Steps, Callout } from "nextra/components";
9+
import { DocMetadata } from "@/components/doc-metadata/DocMetadata";
10+
11+
<DocMetadata />
12+
13+
# Setting up a New Project
14+
15+
This guide describes how to setup a new Project.
16+
17+
## Prerequisites
18+
19+
- Project Name, Start and End Date
20+
- A Submission Layer Administrator user - Keycloak Admin has to create a Submission Layer Admin user with `dare-control-admin` role using this [guide](/co-ordinate/entity-management/add-keycloak-user)
21+
- Access to the Submission Layer as a Submission Layer administrator user
22+
23+
<Steps>
24+
### Login to the Submission Layer
25+
26+
Login to the Submission Layer as Submission Layer Administrator.
27+
28+
### Open the `Create Project` page
29+
30+
Select the `Projects` tab at the top of the home page. This will display the list of existing Projects.
31+
32+
Click the blue `+ Create Project` button at the top-right of the `Projects` page. This will open the `Create Project` page.
33+
34+
![Create New Project ](/images/manage-entities/create-new-project.png)
35+
36+
### Fill in the Project details
37+
38+
The project information should be entered. This includes:
39+
40+
- Project Name (mandatory)
41+
- Start and End dates (mandatory)
42+
- Project Owner (optional)
43+
- Project Contact (email) (optional)
44+
- Mark if project is embargoed
45+
- Project Description (optional)
46+
- Display on UI (not currently modifiable)
47+
48+
![Create Project](/images/manage-entities/create-new-project-form.png)
49+
50+
### Submit the form
51+
52+
Once all details have been added click the blue `Submit` button. This will return you to the `Projects` page, where the new Project will be displayed.
53+
54+
</Steps>
55+
56+
## What's next?
57+
58+
- [Add a new Researcher](/co-ordinate/entity-management/add-new-researcher)
59+
- [Register a new TRE](/co-ordinate/entity-management/register-a-tre)
60+
- [Assign TRE and Researcher to a Project](/co-ordinate/entity-management/assign-tre-user-to-project)

‎app/co-ordinate/setup-sub-layer/configuration/page.mdx‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ audiences: federation-operator
44
docType: reference
55
---
66

7-
import { Table } from "nextra/components";
7+
import { Table, Callout } from "nextra/components";
88
import { DocMetadata } from "@/components/doc-metadata/DocMetadata";
99

1010
<DocMetadata />
@@ -163,6 +163,13 @@ This section contains the environment variables that are used to configure the S
163163
</tbody>
164164
</Table>
165165

166+
<Callout>
167+
Even though `SubmissionS3ApiUrl` is not used by Submission Layer, it is
168+
required by TRE Agent to connect to the Submission Layer S3 server. This is
169+
the URL of the S3 API, one of Submission Layer's [User accessible
170+
components](/co-ordinate/components#user-accessible-components).
171+
</Callout>
172+
166173
### OpenID and redirect URLs Configuration
167174

168175
This section contains the environment variables that are used to configure the OpenID configuration.

0 commit comments

Comments
 (0)