Skip to content
This repository was archived by the owner on Dec 18, 2020. It is now read-only.

Commit 5a99d63

Browse files
lrivallainlrivallain
committed
v1.0 - Initial public release
0 parents  commit 5a99d63

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+12845
-0
lines changed

‎.gitignore

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# pyc
2+
**/__pycache__/
3+
# Avoid pushing real configuration
4+
api/config.json
5+
6+
#ui
7+
node_modules
8+
dist
9+
package-lock.json

‎LICENSE

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright 2019 SII Group
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

+329
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,329 @@
1+
# LDAP user management extension for vCloud Director >=9.1
2+
3+
LUMext is a vCD UI & API extension to manage LDAP-based organisation's users and groups through *VMware vCloud Director*.
4+
5+
This extension aims to provide a way to share a single LDAP server for multiple organisations to simplify the user management.
6+
7+
## Features
8+
9+
A this time, the extension supports only **users management** with the following actions available:
10+
11+
* List users
12+
* Create user
13+
* Edit user
14+
* Reset password
15+
* Delete user
16+
17+
LUMExt support both LDAP or LDAPs protocols and, at least, *Active Directory* based LDAP server.
18+
19+
### Todo
20+
21+
In future releases, we plan to provide a support for LDAP **groups** to simplify the role management:
22+
23+
* List groups
24+
* Create group
25+
* Edit group
26+
* Delete group
27+
* 'Attach to'/'Detach from' user
28+
29+
Others stuff to-do:
30+
31+
* Permission management: only enable the LUMExt for some users of an organization.
32+
* Continuous integration
33+
* Autodocumentation
34+
35+
### Screenshots
36+
37+
![Preview of LUMExt for vCloud Director - User listing](./docs/images/preview_userlisting.png)
38+
39+
![Preview of LUMExt for vCloud Director - User creation](./docs/images/preview_usercreation.png)
40+
41+
## How does it works ?
42+
43+
### Components
44+
45+
LUMExt is based on a the [vCloud Director Extension SDK](https://github.com/vmware/vcd-ext-sdk) and relies on the following components:
46+
47+
* An existing vCloud Director instance
48+
* An existing LDAP compatible server (Active Directory is supported)
49+
* A RabbitMQ server. API requests from vCD's extensions are forwarded to RabbitMQ, then consumed by the backend part of the extension.
50+
* A backend server: `LUMExt-api` (A python module that consumes messages from RabbitMQ).
51+
* UI/API Extensions, uploaded to vCD API.
52+
53+
### Architecture
54+
55+
The following architecture is used for LUMExt deployement
56+
57+
![Architecture overview](./docs/images/architecture_overview.png)
58+
59+
### LDAP structure
60+
61+
As the goal of LUMExt for vCloud Director is to provide the ability to manage per-organization's users in a shared LDAP directory, a common structure is required.
62+
63+
We choose to use the following one to map both users and group to organizations:
64+
65+
```
66+
LDAP Directory root/
67+
└── Base OU
68+
├── Org1-OU
69+
│   ├── Groups
70+
│   └── Users
71+
├── Org2-OU
72+
│   ├── Groups
73+
│   └── Users
74+
└── Org3-OU
75+
├── Groups
76+
└── Users
77+
```
78+
79+
Each Organization's OU is named according to the Org-ID (ex: `5eb80c89-06bc-4650-b5e2-25d5d4972e70`) and contains two sub-OU: `Users` & `Groups`. Currently, only `Users` sub-OU is used by the extension.
80+
81+
*Base OU* can be configured in the settings of LUMExt API service to point in a specific point of the LDAP directory based on its LDAP path.
82+
83+
Example of a LDAP structure in an *Active Directory* server:
84+
85+
![LDAP Structure example](./docs/images/ldap_structure_example.png)
86+
87+
## LUMExt-API
88+
89+
*LUMExt-API* is the backend server used to:
90+
91+
1. Catch messages from the RabbitMQ server.
92+
2. Made the appropriate action(s) on LDAP server (search, edition, creation...).
93+
3. Send back answer to the initial request.
94+
95+
### Installation
96+
97+
In the following documentation, we will see how-to deploy the LUMExt-API in a vCloud Director virtual appliance OS (to avoid deploying a new VM to host it)
98+
99+
> This deployement method is not a best-practice one. Consider to deploy a new VM to host this specific application for production purpose. You can use the same process to deploy the LUMExt-API to a non vCD VA VM.
100+
101+
Firstly, connect by SSH to the VM that will host the API (a vCD Cell in our case).
102+
103+
#### Pre-requisites & installation
104+
105+
```bash
106+
# Install git
107+
yum install git
108+
109+
# Create env variable
110+
echo "export LUMEXT_HOME=/opt/sii/lumext" > /etc/profile.d/lumext.sh
111+
echo "export LUMEXT_CONFIGURATION_FILE_PATH=/opt/sii/lumext/etc/config.yaml" >> /etc/profile.d/lumext.sh
112+
chmod 755 /etc/profile.d/lumext.sh
113+
114+
# Create folder structure
115+
mkdir -p $LUMEXT_HOME/etc
116+
cd $LUMEXT_HOME
117+
118+
# Create python virtual env
119+
python3 -m venv lumext-venv
120+
. lumext-venv/bin/activate
121+
122+
# Get LUMExt code
123+
git clone https://github.com/groupe-sii/lumext.git lumext-app
124+
125+
# Install python requirements
126+
cd $LUMEXT_HOME/lumext-app/api
127+
pip install .
128+
```
129+
130+
#### Configuration
131+
132+
Before running LUMExt-API, it is necessary to configure it.
133+
134+
```bash
135+
# Copy configuration sample
136+
cp config.sample.yaml $LUMEXT_CONFIGURATION_FILE_PATH
137+
# Copy log configuration (so you will be able to edit it for your purpose)
138+
cp logging.json $LUMEXT_HOME/etc
139+
```
140+
141+
Then you will need to edit the following line of the `/opt/sii/lumext/etc/config.yaml` file:
142+
143+
```yaml
144+
rabbitmq:
145+
server: rmq.domain # address of rabbitmq server
146+
port: 5672 # tcp port of rabbitmq server
147+
user: svc-user # amqp username
148+
password: "**********" # amqp password
149+
exchange: systemExchange # configured exchange for vCD
150+
queue: sii-lumext
151+
routing_key: sii-lumext
152+
use_ssl: true # true/false depending on your rmq server
153+
154+
ldap:
155+
address: ldaps://---------:636 # ldap address starting with ldap:// or ldaps://
156+
user: user@domain # username for LDAP administration
157+
secret: "***********" # password for LDAP administration
158+
base: dc=domain,dc=tld # LDAP base path to use as a root for OU creation(s)
159+
domain: domain.tld # name of the LDAP domain
160+
search_timeout: 5 # seconds
161+
operation_timeout: 5 # seconds
162+
cacert_file: /etc/ssl/certs/ca-certificates.crt # If LDAPs is used
163+
userAccountControl: 66048 # Default mode for user creation:
164+
# - (66048: no password expiration + user activated)
165+
166+
log:
167+
config_path: /opt/sii/lumext/etc/logging.json
168+
```
169+
170+
> **Note about LDAPs certificates:**
171+
>
172+
> To use LDAPs, a *cacert* file is mandatory to validate the certificate submitted by the server. You can use a custom CA cert chain (*PEM format*) or, if you use a certificate signed by an OS-trusted CA, use the OS declaration of the trusted certificates.
173+
>
174+
> Please refer to [`Python-LDAP` library documentation](https://www.python-ldap.org/en/latest/index.html) for more details.
175+
176+
#### Test
177+
178+
Once configured, you can test in foreground mode that the API is well starting as expected:
179+
180+
```bash
181+
lumext
182+
```
183+
184+
Depending on the chosen log level for console, some informations are available to confirm that the start of API backend in foreground mode:
185+
186+
```
187+
2019-04-12 12:50:20 INFO MainThread lumext_api.__main__ Starting API server
188+
2019-04-12 12:50:20 INFO MainThread VcdExtMessageWorker New listener initialized for exchange/queue: systemExchange/sii-lumext...
189+
2019-04-12 12:50:20 INFO MainThread kombu.mixins Connected to amqp://rmq-svc:**@rbmq:5671//
190+
```
191+
192+
`CTRL+c` to leave.
193+
194+
#### Install LUMExt API as-a-service
195+
196+
For production or regular basis usage, it is necessary to start the LUMExt API as a daemon (in background mode).
197+
198+
On a system using **systemd**:
199+
200+
Create the `/etc/systemd/system/sii_lumextapi.service` file with the following content:
201+
202+
```ini
203+
[Unit]
204+
Description="LUMExt API - Backend for LUMExt for vCD"
205+
After="network-online.target"
206+
207+
[Service]
208+
Environment="LUMEXT_HOME=/opt/sii/lumext"
209+
Environment="LUMEXT_CONFIGURATION_FILE_PATH=/opt/sii/lumext/etc/config.yaml"
210+
WorkingDirectory=/opt/sii/lumext
211+
ExecStart=/opt/sii/lumext/lumext-venv/bin/python -m lumext_api
212+
Restart=on-failure
213+
RestartSec=5
214+
User=root
215+
Group=root
216+
TimeoutStopSec=30
217+
218+
[Install]
219+
WantedBy=multi-user.target
220+
```
221+
222+
Reload `systemd`, enable and start the service:
223+
224+
```bash
225+
# Reload `systemd`
226+
systemctl daemon-reload
227+
# Enable service
228+
systemctl enable sii_lumextapi
229+
# Start it
230+
service sii_lumextapi start
231+
```
232+
233+
## LUMExt-UI and API extension
234+
235+
### Deploy UI extension
236+
237+
LUMExt-UI is a vCloud Director plugin that extends the HTML5 UI. Once deployed, a new item will be available in the main menu of vCloud Director for tenants where the extension is published to.
238+
239+
#### Download plugin
240+
241+
Please download the last version of `plugin.zip` from the releases files of the github project: [lumext/release](https://github.com/groupe-sii/lumext/releases/latest), copy it to the `ui` folder of the project clone.
242+
243+
```bash
244+
cd ui
245+
curl https://github.com/groupe-sii/lumext/releases/download/v1.0/plugin.zip > ./plugin.zip
246+
```
247+
248+
#### from vCD >=9.1 to 9.5
249+
250+
Use the provided script from the `ui` folder to deploy the LUMExt-UI plugin in vCloud Director.
251+
252+
```bash
253+
cd ui # from root ot the github repository clone
254+
python ./ui_ext_api.py --user "administrator" \
255+
--password '******' \
256+
--server "vcd.domain" \
257+
--folder ./ \
258+
deploy
259+
```
260+
261+
#### Since vCD 9.7
262+
263+
Since vCloud Director 9.7, a new plugin name `Customize Portal` enable the plugin management from the HTML5 Provider UI.
264+
265+
Use the `upload` button to upload the `plugin.zip` file. Review the scope of the plugin:
266+
267+
* *Service Provider* to enable the plugin in the *System* organization.
268+
* *Tenants* to enable the plugin for other organizations.
269+
270+
It is also possible to chose to publish the extension for all, or some tenants only.
271+
272+
Then submit the upload process.
273+
274+
### Deploy API extension
275+
276+
LUMExt also relies on the capacity of vCloud Director API to be extended. So, the UI plugin (or any other API tools) will be able to use the `api` path of vCloud Director to access/create/edit LUMExt objects.
277+
278+
In order to deploy this API extension, use the following script from the `ui` folder:
279+
280+
```bash
281+
cd ui # from root ot the github repository clone
282+
python ./deploy_api.py --user "administrator" \
283+
--password '******' \
284+
--server "vcd.domain" \
285+
--extension_file ./extension.xml \
286+
--extension_name "Lumext" \
287+
deploy
288+
```
289+
290+
## Usage
291+
292+
### Pre-requisites
293+
294+
#### RabbitMQ AMQP broker
295+
296+
In order to work, LUMExt requires that the vCloud Director instance is configured with a RabbitMQ server.
297+
298+
Please refer to the [vCloud Director's documentation](https://docs.vmware.com/en/vCloud-Director/9.7/com.vmware.vcloud.install.doc/GUID-8E4DD1BC-E038-499B-B1FD-02A05E1689AF.html) to setup the RabbitMQ AMQP broker.
299+
300+
![vCloud Director setup - AMQP](./docs/images/vclouddirector-setup-amqp.png)
301+
302+
#### LDAP configuration for vCloud Director
303+
304+
To be usable in vCloud Director context, LDAP directory must be addedd as a *system* or *by-organization* source of authentication.
305+
306+
We recommend that:
307+
308+
* You [setup up the LDAP directory at system level](https://docs.vmware.com/en/vCloud-Director/9.7/com.vmware.vcloud.admin.doc/GUID-E751E805-54DB-4A14-8FA0-DB5CCFC069DA.html).
309+
* [Refer to the same configuration at organization level](https://docs.vmware.com/en/vCloud-Director/9.7/com.vmware.vcloud.admin.doc/GUID-65A484BE-67C5-4B72-8FFD-79A9899504D7.html) with a different base path for users lookup.
310+
311+
**For example:**
312+
313+
At *System* level:
314+
315+
![vCloud Director setup - LDAP](./docs/images/vclouddirector-setup-ldap.png)
316+
317+
At organization level:
318+
319+
![vCloud Director setup - LDAP for Org](./docs/images/vclouddirector-setup-ldap-org.png)
320+
321+
#### User import
322+
323+
Once a user is created on LUMExt extension, you can import it at organization's level through the *Access control* section, *Users* subsection and `Import users` button:
324+
325+
![vCloud Director setup - Import user](./docs/images/vclouddirector-setup-import-user.png)
326+
327+
#### User connection
328+
329+
According to the chosen role attributed to the user created through the extension, it is possible to use the account for login process in vCloud Director.

‎api/config.sample.json

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"rabbitmq": {
3+
"server": "",
4+
"port": "",
5+
"user": "",
6+
"password": "",
7+
"exchange": "",
8+
"queue": "sii-lumext",
9+
"routing_key": "sii-lumext",
10+
"use_ssl": true
11+
},
12+
"ldap": {
13+
"address": "ldaps://---------:636",
14+
"user": "",
15+
"secret": "user@domain",
16+
"base": "dc=domain,dc=tld",
17+
"domain": "domain.tld",
18+
"search_timeout": 5,
19+
"operation_timeout": 5,
20+
"cacert_file": "/etc/ssl/certs/ca-certificates.crt",
21+
"userAccountControl": 66048
22+
},
23+
"log": {
24+
"config_path": "/opt/sii/lumext/etc/logging.json"
25+
}
26+
}

0 commit comments

Comments
 (0)