From a1fa3b6c599a163951fa8082cba668b04b546f17 Mon Sep 17 00:00:00 2001
From: Lars Kiesow <lkiesow@uos.de>
Date: Mon, 12 Feb 2024 23:23:33 +0100
Subject: [PATCH] Document user with limited rights

This patch adds documentation on how to add and use a user with limited
access rights for the display.
---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 914d1a8..5db692d 100644
--- a/README.md
+++ b/README.md
@@ -31,3 +31,28 @@ https://github.com/virtUOS/opencast-ca-display/assets/1008395/ead22cd2-9d7a-4d26
 - The display and laptop do not know about each other
 - The laptop is running an Opencast capture agent
 - When the laptop starts capturing video, the display shows an active recording
+
+## Opencast User
+
+To improve security, you can limit the access rights for the Opencast user by
+creating a user which has only read access to the capture agent status API and
+nothing else.
+
+To do this, first create a new security rule in your Opencast's
+`etc/security/mh_default_org.xml` allowing read access for a new role
+`ROLE_CAPTURE_AGENT_CALENDAR`:
+
+```xml
+<!-- Enable capture agent updates and ingest -->
+<sec:intercept-url pattern="/capture-admin/agents/**" method="GET" access="ROLE_ADMIN, ROLE_CAPTURE_AGENT, ROLE_CAPTURE_AGENT_CALENDAR" />
+<sec:intercept-url pattern="/capture-admin/**" access="ROLE_ADMIN, ROLE_CAPTURE_AGENT" />
+```
+
+Next, go to the Opencast  REST Docs → `/user-utils` and fill out the form for
+`POST /` with data like this:
+
+- username: `ca-display`
+- password: `secret-password`
+- roles: `["ROLE_CAPTURE_AGENT_CALENDAR"]`
+
+You should now be able to use this new user.