Skip to content

Commit 3a528f6

Browse files
UpeksheUpekshe
committed
Rearrange the readme.md
Signed-off-by: Upekshe (its me) <upekshejay@gmail.com>
1 parent 87ba03f commit 3a528f6

File tree

1 file changed

+103
-25
lines changed

1 file changed

+103
-25
lines changed

‎README.md

Lines changed: 103 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -11,56 +11,67 @@ Simple LDAP/LDAPS protocol (authentication and search) emulating user-store for
1111
Dockerized Releases: https://hub.docker.com/r/upekshejay/simple-ldap-test-server
1212
```
1313

14-
## Intro
14+
## Introduction
1515

16-
This is an easily configurable `TEST ENV ONLY` LDAP/LDAPS authentication and search action supported user store. The intention of this project is to support development and testing of applications which require LDAP(or LDAPS) for authentication.
17-
Though LDAP has several authtication mechanisms defined, this project only supports two. Those are
18-
- Anonymous
19-
- Simple (clear-text)
16+
This project provides an easily configurable **`TEST ENV ONLY`** LDAP/LDAPS server designed to **mock an existing setup** for authentication and user store testing. It enables developers to simulate LDAP (or LDAPS) authentication mechanisms and directory structures during application development and testing.
2017

21-
### Why?
22-
When Software solution providers are asked to develop new systems to companies they require the support to plug the new systems to the existing Authentication michanism, Usually these Companies have Active Directory or OpenLDAP setup for authentication. So the easiest and the standard way of pluging in is by using the LDAP/LDAPS protocols.
23-
When developed these authentication mechanism should be tested against a LDAP service. So either you have to configure a Active Directory or OpenLDAP server to test since on a testing (initial testing or UAT) stage inductry would not let you to link directly to their LDAP service.
24-
So if you have a user store which can emulate both LDAP protocol and the companies OU structure, It makes everyone life easier since on the day of production you just have to change the LDAP service address from the test Service to the Actual service.
18+
While the LDAP protocol supports various authentication mechanisms, this server focuses on two primary methods:
19+
- **Anonymous Authentication**
20+
- **Simple Authentication** (clear-text)
2521

26-
This LDAPJS based server is written to address all these issues. Please note this should be used for TESTING ONLY.
22+
### Purpose
23+
24+
When developing new systems, software solutions often need to integrate with an organization’s existing authentication infrastructure. Many organizations rely on Active Directory or OpenLDAP for authentication, and the standard integration approach involves the LDAP/LDAPS protocols.
25+
26+
During development and testing stages—such as initial testing or User Acceptance Testing (UAT)—organizations typically prohibit direct access to their production LDAP services. To address this, a testing LDAP server is needed to:
27+
1. Simulate the LDAP protocol.
28+
2. Mimic the organizational unit (OU) structure of the target environment.
29+
30+
By using this mock LDAP server, developers can replicate the behavior of an organization’s directory service, making it easier to test authentication mechanisms in isolation. On production deployment, the only required change is updating the LDAP server address to the actual service endpoint.
31+
32+
### About This Project
33+
34+
This server, built using **LDAPJS**, is specifically designed to mock existing LDAP setups for development and testing purposes. It provides a lightweight and configurable solution for simulating directory services, ensuring seamless integration and robust testing.
35+
36+
> **Note:** This project is strictly intended for **testing purposes** and should never be used in production environments.
2737
2838
## How to use
2939

30-
Start the server,
40+
Simply start the server to proceed, you can choose one of the following methods:
3141

32-
Go to the simple-ldap-server folder and run `npm start`.
42+
### Using Node.js
3343

34-
Or else for docker users run `docker run -p 389:389 -p 636:636 --name simple-ldap-server upekshejay/simple-ldap-test-server`
44+
1. Navigate to the `simple-ldap-server` folder.
45+
2. Run:
46+
```bash
47+
npm start
48+
49+
### Using docker
50+
51+
run `docker run -p 389:389 -p 636:636 --name simple-ldap-server upekshejay/simple-ldap-test-server`
3552

36-
On both scenarios the server should start with a prompt similar to below
3753

54+
Once started the server should prompt something similar. (This output is based on the default values included with the `/etc/store.json`)
3855

39-
```
56+
```shell
4057
[2022-02-19T12:08:12.973] [INFO] default - Added DC=mtr,DC=com
4158
[2022-02-19T12:08:12.984] [INFO] default - Added OU=users,DC=mtr,DC=com
4259
[2022-02-19T12:08:12.990] [INFO] default - Added CN=admin,OU=users,DC=mtr,DC=com
43-
[2022-02-19T12:08:12.992] [INFO] default - Added CN=kamal,OU=users,DC=mtr,DC=com
44-
[2022-02-19T12:08:12.994] [INFO] default - Added CN=nimal,OU=users,DC=mtr,DC=com
45-
[2022-02-19T12:08:12.996] [INFO] default - Added CN=anil,OU=users,DC=mtr,DC=com
46-
[2022-02-19T12:08:12.999] [INFO] default - Added CN=supun,OU=users,DC=mtr,DC=com
47-
[2022-02-19T12:08:13.000] [INFO] default - Added CN=dasun,OU=users,DC=mtr,DC=com
48-
[2022-02-19T12:08:13.002] [INFO] default - Added CN=search_user,OU=users,DC=mtr,DC=com
49-
[2022-02-19T12:08:13.089] [INFO] default - LDAP server up at: ldap://0.0.0.0:389
60+
...
5061
[2022-02-19T12:08:13.090] [INFO] default - LDAP server up at: ldaps://0.0.0.0:636
5162
[2022-02-19T12:08:13.091] [INFO] default - LDAP Service initiation complete
5263
```
5364

5465
Now the ldap server has exposeed its services.
5566

56-
To check everything works as intended, lets use the tool ldapserach, execute following command in a shell
67+
Then check everything works as intended, lets use the tool `ldapserach`, execute following command in a shell
5768

58-
```
69+
```shell
5970
ldapsearch -x -H ldap://127.0.0.1:389 -b "CN=nimal,OU=users,DC=mtr,DC=com" -D "CN=admin,OU=users,DC=mtr,DC=com" -W
6071
```
6172
The above command search the ldap server for the user 'nimal' with the credentials of the 'admin' user. When this is executed it will ask for the password of admin user, enter the password "itachi". Now ldapsearch should print a prompt similar to below
6273

63-
```
74+
```shell
6475
# extended LDIF
6576
#
6677
# LDAPv3
@@ -95,6 +106,73 @@ This indicates that server has responded with the search results including one u
95106

96107
System level configurations are maintained inside the config folder
97108

109+
# JSON Configuration Field Descriptions
110+
111+
## User Store
112+
113+
| Field | Description |
114+
|-------|-------------|
115+
| **user-store** | Defines the configuration for loading users into the LDAP service. |
116+
| **user-store.mode** | Specifies the current running mode for the user store. Example: `user-file-store`. |
117+
| **user-store.modes** | Lists all the supported modes for the user store. |
118+
| **user-store.modes.user-file-store** | Defines the configuration for the `user-file-store` mode. This mode supports loading users from a JSON file to a single user group. |
119+
| **user-store.modes.user-file-store.location** | The file path for the JSON file containing user definitions. |
120+
| **user-store.modes.user-file-store.users-array-name** | The property name in the JSON file that holds the array of user objects. |
121+
| **user-store.modes.user-file-store.common-password** | A default password assigned to all users unless explicitly defined. |
122+
| **user-store.modes.user-file-store.user-group-ou** | The organizational unit (OU) that all users are linked to. Example: `ou=users`. |
123+
| **user-store.modes.user-file-store.root-entry** | The root entry for the directory structure, represented in Distinguished Name (DN) format. Example: `dc=mtr,dc=com`. |
124+
| **user-store.modes.user-file-store.attribute-mapping** | Defines how attributes in LDAP user records map to values in user objects or static values. |
125+
| **user-store.modes.user-file-store.optional** | Contains optional configurations for the user store. |
126+
| **user-store.modes.user-file-store.optional.search-permitted-users** | Lists additional users allowed to perform search operations. |
127+
| **user-store.modes.user-file-store.optional.search-permitted-users.dn** | The full DN of a user with search permissions. |
128+
| **user-store.modes.user-file-store.optional.search-permitted-users.password** | The password for a user with search permissions. |
129+
| **user-store.modes.structure-file-store** | Reserved for future use. This mode is not yet supported. |
130+
131+
### Attribute Mapping
132+
133+
| Field | Description |
134+
|-------|-------------|
135+
| **sAMAccountName** | Maps to the `id` field of the user object. |
136+
| **uid** | Maps to the `id` field of the user object. |
137+
| **userprincipalname** | Maps to the `id` field of the user object. |
138+
| **mailnickname** | Maps to the `id` field of the user object. |
139+
| **groups** | Specifies static group membership. Example: `lime_users|IT`. |
140+
| **cn** | Maps to the `id` field of the user object. |
141+
| **password** | Maps to the `credential` field of the user object. If null, the `common-password` is used. |
142+
| **objectClass** | Specifies a static value for the LDAP object class. Example: `User`. |
143+
| **permissions** | Maps to the `permissions` field of the user object. |
144+
145+
---
146+
147+
## Anonymous Bind
148+
149+
| Field | Description |
150+
|-------|-------------|
151+
| **anonymous-bind** | Configures whether anonymous binding to the LDAP server is enabled. |
152+
| **anonymous-bind.enabled** | A boolean value indicating whether anonymous binding is allowed. |
153+
154+
---
155+
156+
## Protocols
157+
158+
### LDAP Protocol
159+
160+
| Field | Description |
161+
|-------|-------------|
162+
| **protocols.ldap** | Configuration for the LDAP protocol. |
163+
| **protocols.ldap.enabled** | A boolean value indicating whether the LDAP protocol is enabled. |
164+
| **protocols.ldap.port** | The port number used for the LDAP protocol. Default: `389`. |
165+
166+
### LDAPS Protocol
167+
168+
| Field | Description |
169+
|-------|-------------|
170+
| **protocols.ldaps** | Configuration for the LDAPS protocol. |
171+
| **protocols.ldaps.enabled** | A boolean value indicating whether the LDAPS protocol is enabled. |
172+
| **protocols.ldaps.port** | The port number used for the LDAPS protocol. Default: `636`. |
173+
| **protocols.ldaps.key-location** | The file path to the private key used for SSL/TLS. |
174+
| **protocols.ldaps.cert-location** | The file path to the certificate used for SSL/TLS. |
175+
98176

99177
``sample configuration and description``
100178

0 commit comments

Comments
 (0)