hpi-schul-cloud · CeEv · Feb 11, 2026 · Feb 9, 2026 · Feb 11, 2026 · Feb 11, 2026
diff --git a/docs/topics/authentification/_category_.json b/docs/topics/authentification/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Authentification",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn more about the authentification process in the SVS and how to use it."
+  }
+}
diff --git a/docs/topics/authentification/concept.md b/docs/topics/authentification/concept.md
@@ -0,0 +1,119 @@
+# Authentification
+
+## JWT
+
+JSON Web Tokens (JWT) are an open standard (RFC 7519) for securely transmitting information between parties as a JSON object.
+
+### Structure of a JWT
+
+A JWT consists of three parts, separated by dots (`.`):
+
+```
+header.payload.signature
+```
+
+#### 1. Header
+Contains the token type and the signing algorithm used:
+```json
+{
+  "alg": "RS256",
+  "typ": "JWT"
+}
+```
+
+#### 2. Payload
+Contains the claims (statements about the user):
+```json
+{
+  "sub": "userId123",
+  "iat": 1707494400,
+  "exp": 1707498000,
+  "roles": ["student"]
+}
+```
+
+#### 3. Signature
+Verifies the integrity of the token:
+```
+RSASHA256(
+  base64UrlEncode(header) + "." + base64UrlEncode(payload),
+  privateKey
+)
+```
+
+### Public/Private Key Signing
+
+The Schulcloud uses **asymmetric encryption**:
+
+| Key | Usage |
+|-----|-------|
+| **Private Key** | Signs the JWT (auth server only) |
+| **Public Key** | Verifies the JWT (all services) |
+
+### Benefits
+
+- **Stateless**: No server-side session storage required
+- **Scalable**: Each service can validate tokens independently
+- **Secure**: Signature prevents tampering
+
+### Example Flow
+
+```
+1. Login → Server creates JWT with Private Key
+2. Client stores JWT
+3. Request + JWT → Service validates with Public Key
+4. Access granted/denied
+```
+
+## Auto Logout
+
+To handle auto logouts and token refresh for user JWTs, we use Valkey as a "JWT-Session-Store". 
+The user can refresh their JWT until the maximum lifetime of the JWT is reached.
+
+## Related Code
+
+Authentication
+- [Authentication Module](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/apps/server/src/modules/authentication) - Main authentication module
+- [Authentication Stategies](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/apps/server/src/modules/authentication/strategy) - Authentication stategies
+- [Login Controller](https://github.com/hpi-schul-cloud/schulcloud-client/blob/main/controllers/login.js) - Legacy-client-side login controller
+
+For OAuth 
+- [OAuth Controller](https://github.com/hpi-schul-cloud/schulcloud-server/blob/main/apps/server/src/modules/oauth/api/oauth.controller.ts) - OAuth API controller
+- [OAuth Provider Controller](https://github.com/hpi-schul-cloud/schulcloud-server/blob/main/apps/server/src/modules/oauth-provider/api/oauth-provider.controller.ts) - OAuth provider API controller
+- [Releated OAuth Documentation](/docs/topics/oauth/concept)
+
+For Ldap
+tbd.
+
+Validation decorator
+- [Auth Guard Decorators](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/apps/server/src/infra/auth-guard) - Infra module for our NestJS decorators
+- [Auth Validation Strategies](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/apps/server/src/infra/auth-guard/strategy) - Validate authentication strategies
+
+## Authentification Stategies
+
+We have 3 strategies that can be create a SVS JWT
+1. Local - When login credentials are in the SVS.
+2. Ldap - We want to login over a external ldap system used in BRB.
+3. OAuth - We use a OAuth Flow to login over a external IDM like Moin.Schule (NBC), or TSP.
+
+We have 3 base validation strategies.
+1. For the jwt it self over http.
+2. For the jwt but used in web sockets.
+3. For x-api-key. 
+
+The x-api-key stategy is nearly deprecated and will be replaced with system user logins based on the first strategy.
+
+## Decorator Example
+
+[MeController Example](https://github.com/hpi-schul-cloud/schulcloud-server/blob/main/apps/server/src/modules/me/api/me.controller.ts)
+
+```typescript
+import { JwtAuthentication } from '@infra/auth-guard';
+import { Controller } from '@nestjs/common';
+
+@JwtAuthentication()
+@Controller('me')
+export class MeController {
+  // ...
+}
+```
diff --git a/docs/topics/authorization/_category_.json b/docs/topics/authorization/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Authorization",
-  "position": 2,
+  "position": 3,
   "link": {
     "type": "generated-index",
     "description": "Learn about the authorization service."

diff --git a/docs/topics/bbb/_category_.json b/docs/topics/bbb/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "BigBlueButton",
-  "position": 3,
+  "position": 4,
   "link": {
     "type": "generated-index",
     "description": "Learn about the BigBlueButton service."

diff --git a/docs/topics/collabora/_category_.json b/docs/topics/collabora/_category_.json
@@ -1,4 +1,8 @@
 {
   "label": "Collabora",
-  "position": 4
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn about the Collabora service."
+  }
 }
diff --git a/docs/topics/common-cartridge/_category_.json b/docs/topics/common-cartridge/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Common Cartridge",
+  "position": 6,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn about the Common Cartridge service."
+  }
+}
diff --git a/docs/topics/etherpad/_category_.json b/docs/topics/etherpad/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Etherpad",
-  "position": 5,
+  "position": 7,
   "link": {
     "type": "generated-index",
     "description": "Learn about the etherpad repo."

diff --git a/docs/topics/files-storage/_category_.json b/docs/topics/files-storage/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Files Storage",
-  "position": 6,
+  "position": 8,
   "link": {
     "type": "generated-index",
     "description": "Learn about the files-storage repo."

diff --git a/docs/topics/h5p/_category_.json b/docs/topics/h5p/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "H5P",
-  "position": 7,
+  "position": 9,
   "link": {
     "type": "generated-index",
     "description": "Learn about the H5P services & modules."

diff --git a/docs/topics/moin-punkt-schule/_category_.json b/docs/topics/moin-punkt-schule/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Moin.Schule",
-  "position": 8,
+  "position": 10,
   "link": {
     "type": "generated-index",
     "description": "Learn about the moin.schule service."

diff --git a/docs/topics/oauth/_category_.json b/docs/topics/oauth/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "OAuth",
-  "position": 10,
+  "position": 11,
   "link": {
     "type": "generated-index",
     "description": "Learn about the OAuth strategy."

diff --git a/docs/topics/provisioning/_category_.json b/docs/topics/provisioning/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Provisioning",
-  "position": 11,
+  "position": 12,
   "link": {
     "type": "generated-index",
     "description": "Learn about the provisioning service."

diff --git a/docs/topics/schulcloud-client/_category_.json b/docs/topics/schulcloud-client/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Schulcloud Client",
-  "position": 12,
+  "position": 13,
   "link": {
     "type": "generated-index",
     "description": "Learn about the schulcloud-client repo."

diff --git a/docs/topics/schulcloud-server/_category_.json b/docs/topics/schulcloud-server/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Schulcloud Server",
-  "position": 13,
+  "position": 14,
   "link": {
     "type": "generated-index",
     "description": "Learn about the schulcloud-server repo."

diff --git a/docs/topics/tldraw-server/_category_.json b/docs/topics/tldraw-server/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Tldraw Server",
-  "position": 14,
+  "position": 15,
   "link": {
     "type": "generated-index",
     "description": "Learn about the tldraw-server repo."

diff --git a/docs/topics/tools/_category_.json b/docs/topics/tools/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Tools",
-  "position": 15,
+  "position": 16,
   "link": {
     "type": "generated-index",
     "description": "Learn about tools."

diff --git a/docs/topics/tsp-sync/_category_.json b/docs/topics/tsp-sync/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "TSP Synchronisation",
-  "position": 16,
+  "position": 17,
   "link": {
     "type": "generated-index",
     "description": "Learn about the Synchronisation of Userdata from the 'Thüringer Schulportal'"

diff --git a/docs/topics/vue-client/_category_.json b/docs/topics/vue-client/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Vue Client",
-  "position": 9,
+  "position": 18,
   "link": {
     "type": "generated-index",
     "description": "Learn about the vue-client repo."