Skip to content

Commit

Permalink
Rearrange the readme.md
Browse files Browse the repository at this point in the history 
Signed-off-by: Upekshe (its me) <upekshejay@gmail.com>
  • Loading branch information
@Upekshe
Upekshe committed Jan 1, 2025
1 parent 87ba03f commit 3a528f6
Showing 1 changed file with 103 additions and 25 deletions.
128 changes: 103 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,56 +11,67 @@ Simple LDAP/LDAPS protocol (authentication and search) emulating user-store for
Dockerized Releases: https://hub.docker.com/r/upekshejay/simple-ldap-test-server
```

## Intro
## Introduction

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.
Though LDAP has several authtication mechanisms defined, this project only supports two. Those are
- Anonymous
- Simple (clear-text)
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.

### Why?
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.
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.
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.
While the LDAP protocol supports various authentication mechanisms, this server focuses on two primary methods:
- **Anonymous Authentication**
- **Simple Authentication** (clear-text)

This LDAPJS based server is written to address all these issues. Please note this should be used for TESTING ONLY.
### Purpose

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.

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:
1. Simulate the LDAP protocol.
2. Mimic the organizational unit (OU) structure of the target environment.

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.

### About This Project

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.

> **Note:** This project is strictly intended for **testing purposes** and should never be used in production environments.
## How to use

Start the server,
Simply start the server to proceed, you can choose one of the following methods:

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

Or else for docker users run `docker run -p 389:389 -p 636:636 --name simple-ldap-server upekshejay/simple-ldap-test-server`
1. Navigate to the `simple-ldap-server` folder.
2. Run:
```bash
npm start

### Using docker

run `docker run -p 389:389 -p 636:636 --name simple-ldap-server upekshejay/simple-ldap-test-server`

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

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

```
```shell
[2022-02-19T12:08:12.973] [INFO] default - Added DC=mtr,DC=com
[2022-02-19T12:08:12.984] [INFO] default - Added OU=users,DC=mtr,DC=com
[2022-02-19T12:08:12.990] [INFO] default - Added CN=admin,OU=users,DC=mtr,DC=com
[2022-02-19T12:08:12.992] [INFO] default - Added CN=kamal,OU=users,DC=mtr,DC=com
[2022-02-19T12:08:12.994] [INFO] default - Added CN=nimal,OU=users,DC=mtr,DC=com
[2022-02-19T12:08:12.996] [INFO] default - Added CN=anil,OU=users,DC=mtr,DC=com
[2022-02-19T12:08:12.999] [INFO] default - Added CN=supun,OU=users,DC=mtr,DC=com
[2022-02-19T12:08:13.000] [INFO] default - Added CN=dasun,OU=users,DC=mtr,DC=com
[2022-02-19T12:08:13.002] [INFO] default - Added CN=search_user,OU=users,DC=mtr,DC=com
[2022-02-19T12:08:13.089] [INFO] default - LDAP server up at: ldap://0.0.0.0:389
...
[2022-02-19T12:08:13.090] [INFO] default - LDAP server up at: ldaps://0.0.0.0:636
[2022-02-19T12:08:13.091] [INFO] default - LDAP Service initiation complete
```

Now the ldap server has exposeed its services.

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

```
```shell
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
```
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

```
```shell
# extended LDIF
#
# LDAPv3
Expand Down Expand Up @@ -95,6 +106,73 @@ This indicates that server has responded with the search results including one u

System level configurations are maintained inside the config folder

# JSON Configuration Field Descriptions

## User Store

| Field | Description |
|-------|-------------|
| **user-store** | Defines the configuration for loading users into the LDAP service. |
| **user-store.mode** | Specifies the current running mode for the user store. Example: `user-file-store`. |
| **user-store.modes** | Lists all the supported modes for the user store. |
| **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. |
| **user-store.modes.user-file-store.location** | The file path for the JSON file containing user definitions. |
| **user-store.modes.user-file-store.users-array-name** | The property name in the JSON file that holds the array of user objects. |
| **user-store.modes.user-file-store.common-password** | A default password assigned to all users unless explicitly defined. |
| **user-store.modes.user-file-store.user-group-ou** | The organizational unit (OU) that all users are linked to. Example: `ou=users`. |
| **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`. |
| **user-store.modes.user-file-store.attribute-mapping** | Defines how attributes in LDAP user records map to values in user objects or static values. |
| **user-store.modes.user-file-store.optional** | Contains optional configurations for the user store. |
| **user-store.modes.user-file-store.optional.search-permitted-users** | Lists additional users allowed to perform search operations. |
| **user-store.modes.user-file-store.optional.search-permitted-users.dn** | The full DN of a user with search permissions. |
| **user-store.modes.user-file-store.optional.search-permitted-users.password** | The password for a user with search permissions. |
| **user-store.modes.structure-file-store** | Reserved for future use. This mode is not yet supported. |

### Attribute Mapping

| Field | Description |
|-------|-------------|
| **sAMAccountName** | Maps to the `id` field of the user object. |
| **uid** | Maps to the `id` field of the user object. |
| **userprincipalname** | Maps to the `id` field of the user object. |
| **mailnickname** | Maps to the `id` field of the user object. |
| **groups** | Specifies static group membership. Example: `lime_users|IT`. |
| **cn** | Maps to the `id` field of the user object. |
| **password** | Maps to the `credential` field of the user object. If null, the `common-password` is used. |
| **objectClass** | Specifies a static value for the LDAP object class. Example: `User`. |
| **permissions** | Maps to the `permissions` field of the user object. |

---

## Anonymous Bind

| Field | Description |
|-------|-------------|
| **anonymous-bind** | Configures whether anonymous binding to the LDAP server is enabled. |
| **anonymous-bind.enabled** | A boolean value indicating whether anonymous binding is allowed. |

---

## Protocols

### LDAP Protocol

| Field | Description |
|-------|-------------|
| **protocols.ldap** | Configuration for the LDAP protocol. |
| **protocols.ldap.enabled** | A boolean value indicating whether the LDAP protocol is enabled. |
| **protocols.ldap.port** | The port number used for the LDAP protocol. Default: `389`. |

### LDAPS Protocol

| Field | Description |
|-------|-------------|
| **protocols.ldaps** | Configuration for the LDAPS protocol. |
| **protocols.ldaps.enabled** | A boolean value indicating whether the LDAPS protocol is enabled. |
| **protocols.ldaps.port** | The port number used for the LDAPS protocol. Default: `636`. |
| **protocols.ldaps.key-location** | The file path to the private key used for SSL/TLS. |
| **protocols.ldaps.cert-location** | The file path to the certificate used for SSL/TLS. |


``sample configuration and description``

Expand Down

0 comments on commit 3a528f6

Please sign in to comment.