Embedded LDAP server: Improve README.md and examples
Change-Id: Ia62b059960fab78d0150058bb24008273d9df2f9
diff --git a/README.md b/README.md
index 54ad3bd..5882947 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
* <b>Kustvakt full version</b>
- provides user and policy management and extended services, in addition to the basic services. This version requires a database (Sqlite is provided) and an LDAP system for user authentication.
+ provides user and policy management and extended services, in addition to the basic services. This version requires a database (Sqlite is provided) and an LDAP system ([UnboundID InMemoryDirectoryServer](https://github.com/pingidentity/ldapsdk) is provided) for user authentication.
Recent changes on the project are described in the change logs (Changes files).
@@ -76,7 +76,8 @@
If `searchFilter` does not contain any occurrence of `${password}` the user DN found via the filter expression will be authenticated via a regular LDAP bind operation, using the entered password. In this case, depending on the LDAP server, also hashed passwords are supported.
-###### Example ldap config file
+###### Example ldap.conf
+
```properties
host=ldap.example.org
# use LDAP over SSL (LDAPS) if the server supports it
@@ -87,57 +88,44 @@
# add ssl cipher suites if required as csv, e.g. TLS_RSA_WITH_AES_256_GCM_SHA384
additionalCipherSuites=
searchBase=dc=example,dc=org
+# DN of a user with full read access
sLoginDN=cn=admin,dc=example,dc=org
pwd=adminpassword
-searchFilter=(&(&(uid=${login})(userPassword=${password}))(signedeula=TRUE))
+# search for user with uid or email matching login, and signed EULA
+searchFilter=(&(|(uid=${login})(mail=${login}))(signedeula=TRUE))
```
#### Using Kustvakt-full's embedded LDAP server
-For smaller projects, you can also use Kustvakt-full's embedded in-memory LDAP server, that uses [UnboundID LDAP SDK ](http://www.unboundid.com/products/ldap-sdk/) for this purpose. In order to do so, the following additional settings are required in your `ldap.conf`:
+Instead of you own LDAP server, you can also use Kustvakt-full's embedded in-memory LDAP server which uses [UnboundID LDAP SDK](https://github.com/pingidentity/ldapsdk) for this purpose. In order to do so, the following additional settings are required in your `ldap.conf`:
```properties
useEmbeddedServer=true
ldifFile=path-to-users-directory.ldif
-# ldapPort=1234
+# port=1234
```
-Note that currently the embedded server ignores the `ldapHost` and `ldapS` settings, and only listens on the `localhost` interface. The `ldapPort` setting, on the other hand, is used.
+Note that currently the embedded server ignores the `host` and `useSSL` settings, and only listens on the `localhost` interface. The `port` setting, on the other hand, is used.
-The embedded server currently supports the following password encodings:
-
-* clear passwords – prefix `{CLEAR}` or empty
-* hex – prefix `{HEX}`
-* base64 – prefix `{BASE64}`
-* SHA1 – prefix `{SHA}`
-* SHA-256 – prefix `{SHA256}`
+The embedded server currently supports the following password encodings: clear passwords (prefix `{CLEAR}` or empty), `{HEX}`, `{BASE64}`, `{SHA}`, `{SHA256}`.
Note that none of these are safe against brute force attacks.
-###### Example users.ldif
+##### Try out the embedded LDAP server
-```ldif
-dn: dc=example,dc=com
-dc: example
-ou: people
-objectClass: dcObject
-objectClass: organizationalUnit
+You can try Kustvakt-full with embedded LDAP server using the example configuration provided in [embedded-ldap-example.conf](./full/src/main/resources/embedded-ldap-example.conf) and users defined in [example-users.ldif](./full/src/main/resources/example-users.ldif) like this:
-dn: ou=people,dc=example,dc=com
-ou: people
-objectClass: organizationalUnit
+```shell
+$ cp src/main/resources/kustvakt.conf .
+$ java -jar target/Kustvakt-full-*.jar
+```
-dn: uid=user,ou=people,dc=example,dc=com
-cn: user
-uid: user
-mail: user@example.com
-userPassword: cGFzc3dvcmQ=
+The [example-users.ldif](./full/src/main/resources/example-users.ldif) defines the following login:password combinations: user:password, user1:password1, …, user4:password4, with differently encoded passwords.
-dn: uid=user3,ou=people,dc=example,dc=com
-cn: user3
-uid: user3
-mail: user3@example.com
-userPassword: {SHA}ERnP037iRzV+A0oI2ETuol9v0g8=
+To try it out together with KorAP's web user interface [Kalamar](https://github.com/KorAP/Kalamar), add `"Auth"` to the loaded plugins in `kalamar.conf`:
+
+```perl
+plugins => ["Auth"],
```
### Setting BasicAuthentication for Testing
diff --git a/full/src/main/resources/embedded-ldap-example.conf b/full/src/main/resources/embedded-ldap-example.conf
new file mode 100644
index 0000000..0fa5f9f
--- /dev/null
+++ b/full/src/main/resources/embedded-ldap-example.conf
@@ -0,0 +1,10 @@
+# Sample configuration for an automatically starting
+# embedded LDAP server
+host=localhost
+port=3267
+searchBase=dc=example,dc=com
+sLoginDN=cn=admin,dc=example,dc=com
+pwd=admin
+searchFilter=(|(uid=${login})(mail=${login}))
+useEmbeddedServer=true
+ldifFile=src/main/resources/example-users.ldif
diff --git a/full/src/main/resources/korap-users.ldif b/full/src/main/resources/example-users.ldif
similarity index 79%
rename from full/src/main/resources/korap-users.ldif
rename to full/src/main/resources/example-users.ldif
index 8760df9..103582f 100644
--- a/full/src/main/resources/korap-users.ldif
+++ b/full/src/main/resources/example-users.ldif
@@ -9,25 +9,25 @@
objectClass: organizationalUnit
dn: uid=user,ou=people,dc=example,dc=com
-cn: user
+cn: Rainer User
uid: user
mail: user@example.com
userPassword: {BASE64}cGFzc3dvcmQ=
dn: uid=user1,ou=people,dc=example,dc=com
-cn: user1
+cn: User 1
uid: user1
mail: user1@example.com
userPassword: {CLEAR}password1
dn: uid=user2,ou=people,dc=example,dc=com
-cn: user2
+cn: User 2
uid: user2
mail: user2@example.com
userPassword: password2
dn: uid=user3,ou=people,dc=example,dc=com
-cn: user3
+cn: User 3
uid: user3
mail: user3@example.com
userPassword: {SHA}ERnP037iRzV+A0oI2ETuol9v0g8=
@@ -37,10 +37,3 @@
uid: user4
mail: user4@example.com
userPassword: {SHA256}uXhzpA9zq+3Y1oWnzV5fheSpz7g+rCaIZkCggThQEis=
-
-dn: uid=user5,ou=people,dc=example,dc=com
-cn: user5
-uid: user5
-mail: user5@example.com
-userPassword: {PBKDF2-SHA256}26PFrg++/nI8YOiHum5MyAMp0HdqKMNOcLpY5RuO2bY=
-
diff --git a/full/src/main/resources/kustvakt.conf b/full/src/main/resources/kustvakt.conf
index 5d822ae..4ef6aac 100644
--- a/full/src/main/resources/kustvakt.conf
+++ b/full/src/main/resources/kustvakt.conf
@@ -9,7 +9,7 @@
#krill.namedVC = vc
# LDAP
-ldap.config = file-path-to-ldap-config
+ldap.config = src/main/resources/embedded-ldap-example.conf
# Kustvakt
api.welcome.message = Welcome to KorAP API!