Skip to content

Commit 6fe58d7

Browse files
MetaurielMetauriel
authored
LDAP Documentation (#91)
* document local setup for ldap * concept for ldap * add ldap to topics
1 parent ea2de7e commit 6fe58d7

File tree

6 files changed

+195
-35
lines changed

6 files changed

+195
-35
lines changed

‎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": 9,
3+
"position": 8,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the H5P services & modules."

‎docs/topics/ldap/_category_.json‎

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

‎docs/topics/ldap/concept.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# LDAP Sync
2+
3+
The LDAP Sync is a highly configurable and scalable tool to import Users, Classes, and Schools from an LDAP System into the Bildungscloud.
4+
5+
## Strukture
6+
7+
Each external LDAP Server that should be synced has to be configured with a `system` object in the database.
8+
9+
Through the `system` object, many details for the structure of the external LDAP can be configured, so they can be automatically mapped to our datastructure.
10+
11+
There is a UI under /administration/school-settings where a school admin is able to configure an LDAP system for his own school himself. However bear in mind that this is a fairly complicated and errorprone matter, that should be done by people with technikal knowledge and be closely monitored by Support.
12+
13+
Its also possible to set up an LDAP System with multiple schools.
14+
15+
The actual Synchronisation is triggered regularly via a Cronjob, and is implemented with a producer/consumer pattern via RabbitMQ.
16+
17+
## Requirements
18+
19+
The external LDAP System has to be accessible for our Server.
20+
If necessary, the corresponding IP adresses should be whitelisted in the firewall of the LDAP Provider. (This means we need to ensure the IP Adress used by the server does not randomly change)
21+
22+
Each user in the LDAP must have the following attributes, though their naming may vary:
23+
24+
- uid (used as login name, must be unique)
25+
- uuid (must be immutable and unique)
26+
- mail (must be unique)
27+
- givenName (firstname)
28+
- sn (surname)
29+
- objectClass (must include the value `person`)
30+
31+
The role of the user can either be an attribute, or an ldap group (`memberOf`). There must be the following roles, though their naming may vary:
32+
33+
- ROLE_STUDENT
34+
- ROLE_TEACHER
35+
- ROLE_ADMIN
36+
37+
You can also give the role `ROLE_NO_SC` to users that should not be synced.
38+
39+
## Components
40+
41+
The Code can be found in the legacy Server under [src/services/sync/strategies](https://github.com/hpi-schul-cloud/schulcloud-server/tree/main/src/services/sync/strategies).
42+
43+
The three main components are the `LDAPSyncer`, `LDAPSyncerConsumer`, and `LDAPSystemSyncer`.
44+
45+
the `LDAPSyncer` will process a single LDAP System, fetch and parse its data to identify its schools, classes, and users, and push each of those as a rabbitMQ event.
46+
47+
the `LDAPSyncerConsumer` will consume these events, and create or update the corresponding objects in the Bildungscloud.
48+
49+
the `LDAPSystemSyncer` provides an API to run all configured LDAP Systems with a single command.
50+
51+
## Scaling
52+
53+
The LDAP Sync is, as of writing this, not yet implemented as a microservice, but part of the legacy Server.
54+
55+
However when multiple Servers are deployed and connected via RabbitMQ, they will share and balance the work among themselves.
56+
57+
Do ensure each of the Servers that should partake in the LDAP Sync has `FEATURE_SYNCER_CONSUMER_ENABLE` set.

‎docs/topics/ldap/local-setup.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Setting up LDAP server on local & dev environments
2+
3+
## Introduction
4+
5+
This guide describes how to test the LDAP adapter in a local or dev environment. For this we use the following Docker image: [ghcr.io/hpi-schul-cloud/sc-openldap-single:main](http://ghcr.io/hpi-schul-cloud/sc-openldap-single:main) It provides a multitude of users for testing, in a compatible format.
6+
7+
---
8+
9+
## Setting up the LDAP server for local development & testing purposes
10+
11+
### Starting the LDAP Container
12+
13+
The first step is to start a Docker container with the **sc-openldap-single** image and exposed 389 port for the ldap protocol connections.
14+
15+
Note that there have been issues running the ldaps protocol.
16+
17+
```bash
18+
docker run -d -p 389:389 --name openldap ghcr.io/hpi-schul-cloud/sc-openldap-single:main
19+
```
20+
21+
You can verify the deployment using [Apache Directory Studio™](https://directory.apache.org/studio/) or a simlar software to connect:
22+
23+
- **Hostname:** `localhost` or `127.0.0.1`
24+
- **Port:** `389`
25+
- **Bind DN or user:** `cn=admin,dc=example,dc=org`
26+
- **Bind password:** `admin`
27+
28+
### Connecting to the LDAP Container
29+
30+
Since we are not using the ldaps protocoll for the local deployment, we have to configure the server to accept insecure ldap connections. Add the following to your environment variables:
31+
32+
```bash
33+
FEATURE_ALLOW_INSECURE_LDAP_URL_ENABLED: true
34+
```
35+
36+
To configure a school in the Bildungscloud to use your new LDAP deployment, there are two ways: Either you add the necessary data directly in the database, or you add the system in the UI.
37+
38+
To make the changes directly, add the following Object in the `systems` collection
39+
40+
```json
41+
{
42+
"type": "ldap",
43+
"alias": "testldap-schoolOne0",
44+
"ldapConfig": {
45+
"active": true,
46+
"federalState": {
47+
"$oid": "0000b186816abba584714c53"
48+
},
49+
"url": "ldap://127.0.0.1:389",
50+
"rootPath": "o=schoolOne0,dc=de,dc=example,dc=org",
51+
"searchUser": "cn=admin,dc=example,dc=org",
52+
"searchUserPassword": "<encryt this with your Base64 Key>",
53+
"provider": "general",
54+
"providerOptions": {
55+
"schoolName": "Paul-Gerhardt-Gymnasium",
56+
"userPathAdditions": "ou=users",
57+
"classPathAdditions": "ou=groups",
58+
"roleType": "group",
59+
"userAttributeNameMapping": {
60+
"givenName": " givenName",
61+
"sn": "sn",
62+
"dn": "dn",
63+
"uuid": "uuid",
64+
"uid": "uid",
65+
"mail": "mail",
66+
"role": "memberOf"
67+
},
68+
"roleAttributeNameMapping": {
69+
"roleStudent": "cn=ROLE_STUDENT,ou=roles,o=schoolOne0,dc=de,dc=example,dc=org",
70+
"roleTeacher": "cn=ROLE_TEACHER,ou=roles,o=schoolOne0,dc=de,dc=example,dc=org",
71+
"roleAdmin": "cn=ROLE_ADMIN,ou=roles,o=schoolOne0,dc=de,dc=example,dc=org",
72+
"roleNoSc": "cn=ROLE_NBC_EXCLUDE,ou=roles,o=schoolOne0,dc=de,dc=example,dc=org"
73+
},
74+
"classAttributeNameMapping": {
75+
"description": "description",
76+
"dn": "dn",
77+
"uniqueMember": "member"
78+
}
79+
}
80+
},
81+
}
82+
```
83+
84+
Then add the following properties to a school object of your choice.
85+
86+
```json
87+
{
88+
[...]
89+
"systems": [
90+
{
91+
"$oid": "<id of the system you just created>"
92+
}
93+
],
94+
"ldapSchoolIdentifier": "o=schoolOne0,dc=de,dc=example,dc=org"
95+
}
96+
```
97+
98+
Alternatively, in the UI you can login as a school admin and navigate to /administration/school-settings, and under "Authentication" click on "Add LDAP System".
99+
100+
Refer to the example above for the values. (note that the password only has to be encrypted if you add it to the database manually)
101+
102+
> **Note:** you can not use `localhost` as the hostname, since that will be rejected by the validator. use the ip adress `127.0.0.1` instead.
103+
104+
Once you have filled all the fields you can verify the config.
105+
106+
---
107+
108+
## Triggering the LDAP sync
109+
110+
Before triggering the LDAP sync ensure you have a working RabbitMQ setup, and add the following environment variables
111+
112+
```bash
113+
FEATURE_SYNCER_CONSUMER_ENABLE: 'true'
114+
SYNC_API_KEY: 'a-key-of-your-choice'
115+
```
116+
117+
Then trigger the sync with the following request:
118+
119+
```bash
120+
curl -X POST -H "X-API-Key: $SYNC_API_KEY" "$API_HOST/v1/sync?target=ldap"
121+
```
122+
123+
You should get a response similar to:
124+
125+
```json
126+
[{"success":true,"errors":[],"systems":{"Paul-Gerhardt-Gymnasium":{"success":true,"errors":[],"schools":1,"users":1226,"classes":17}}}]
127+
```

‎docs/topics/vue-client/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Vue Client",
3-
"position": 18,
3+
"position": 20,
44
"link": {
55
"type": "generated-index",
66
"description": "Learn about the vue-client repo."

0 commit comments

Comments
 (0)