Skip to content

Commit ea2de7e

Browse files
CeEvCeEv
authored
Add authentification topic. (#90)
1 parent 93f3177 commit ea2de7e

File tree

18 files changed

+154
-15
lines changed

18 files changed

+154
-15
lines changed

‎docs/topics/authentification/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Authentification",
3+
"position": 2,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Learn more about the authentification process in the SVS and how to use it."
7+
}
8+
}

‎docs/topics/authentification/concept.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Authentification
2+
3+
## JWT
4+
5+
JSON Web Tokens (JWT) are an open standard (RFC 7519) for securely transmitting information between parties as a JSON object.
6+
7+
### Structure of a JWT
8+
9+
A JWT consists of three parts, separated by dots (`.`):
10+
11+
```
12+
header.payload.signature
13+
```
14+
15+
#### 1. Header
16+
Contains the token type and the signing algorithm used:
17+
```json
18+
{
19+
"alg": "RS256",
20+
"typ": "JWT"
21+
}
22+
```
23+
24+
#### 2. Payload
25+
Contains the claims (statements about the user):
26+
```json
27+
{
28+
"sub": "userId123",
29+
"iat": 1707494400,
30+
"exp": 1707498000,
31+
"roles": ["student"]
32+
}
33+
```
34+
35+
#### 3. Signature
36+
Verifies the integrity of the token:
37+
```
38+
RSASHA256(
39+
base64UrlEncode(header) + "." + base64UrlEncode(payload),
40+
privateKey
41+
)
42+
```
43+
44+
### Public/Private Key Signing
45+
46+
The Schulcloud uses **asymmetric encryption**:
47+
48+
| Key | Usage |
49+
|-----|-------|
50+
| **Private Key** | Signs the JWT (auth server only) |
51+
| **Public Key** | Verifies the JWT (all services) |
52+
53+
### Benefits
54+
55+
- **Stateless**: No server-side session storage required
56+
- **Scalable**: Each service can validate tokens independently
57+
- **Secure**: Signature prevents tampering
58+
59+
### Example Flow
60+
61+
```
62+
1. Login → Server creates JWT with Private Key
63+
2. Client stores JWT
64+
3. Request + JWT → Service validates with Public Key
65+
4. Access granted/denied
66+
```
67+
68+
## Auto Logout
69+
70+
To handle auto logouts and token refresh for user JWTs, we use Valkey as a "JWT-Session-Store".
71+
The user can refresh their JWT until the maximum lifetime of the JWT is reached.
72+
73+
## Related Code
74+
75+
Authentication
76+
- [Authentication Module](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/apps/server/src/modules/authentication) - Main authentication module
77+
- [Authentication Stategies](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/apps/server/src/modules/authentication/strategy) - Authentication stategies
78+
- [Login Controller](https://github.com/hpi-schul-cloud/schulcloud-client/blob/main/controllers/login.js) - Legacy-client-side login controller
79+
80+
For OAuth
81+
- [OAuth Controller](https://github.com/hpi-schul-cloud/schulcloud-server/blob/main/apps/server/src/modules/oauth/api/oauth.controller.ts) - OAuth API controller
82+
- [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
83+
- [Releated OAuth Documentation](/docs/topics/oauth/concept)
84+
85+
For Ldap
86+
tbd.
87+
88+
Validation decorator
89+
- [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
90+
- [Auth Validation Strategies](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/apps/server/src/infra/auth-guard/strategy) - Validate authentication strategies
91+
92+
## Authentification Stategies
93+
94+
We have 3 strategies that can be create a SVS JWT
95+
1. Local - When login credentials are in the SVS.
96+
2. Ldap - We want to login over a external ldap system used in BRB.
97+
3. OAuth - We use a OAuth Flow to login over a external IDM like Moin.Schule (NBC), or TSP.
98+
99+
We have 3 base validation strategies.
100+
1. For the jwt it self over http.
101+
2. For the jwt but used in web sockets.
102+
3. For x-api-key.
103+
104+
The x-api-key stategy is nearly deprecated and will be replaced with system user logins based on the first strategy.
105+
106+
## Decorator Example
107+
108+
[MeController Example](https://github.com/hpi-schul-cloud/schulcloud-server/blob/main/apps/server/src/modules/me/api/me.controller.ts)
109+
110+
```typescript
111+
import { JwtAuthentication } from '@infra/auth-guard';
112+
import { Controller } from '@nestjs/common';
113+
114+
@JwtAuthentication()
115+
@Controller('me')
116+
export class MeController {
117+
// ...
118+
}
119+
```

‎docs/topics/authorization/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Authorization",
3-
"position": 2,
3+
"position": 3,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the authorization service."

‎docs/topics/bbb/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "BigBlueButton",
3-
"position": 3,
3+
"position": 4,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the BigBlueButton service."

‎docs/topics/collabora/_category_.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
{
22
"label": "Collabora",
3-
"position": 4
3+
"position": 5,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Learn about the Collabora service."
7+
}
48
}

‎docs/topics/common-cartridge/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Common Cartridge",
3+
"position": 6,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Learn about the Common Cartridge service."
7+
}
8+
}

‎docs/topics/etherpad/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Etherpad",
3-
"position": 5,
3+
"position": 7,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the etherpad repo."

‎docs/topics/files-storage/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Files Storage",
3-
"position": 6,
3+
"position": 8,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the files-storage repo."

‎docs/topics/h5p/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "H5P",
3-
"position": 7,
3+
"position": 9,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the H5P services & modules."

‎docs/topics/moin-punkt-schule/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Moin.Schule",
3-
"position": 8,
3+
"position": 10,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the moin.schule service."

0 commit comments

Comments
 (0)