|
|
|
EDLdap Library
|
|
|
|
======
|
|
|
|
|
|
|
|
The EDLdap library is a Java based library which can be used to interact with the Enterprise Directory LDAPs.
|
|
|
|
|
|
|
|
| Version | License | API Documentation |
|
|
|
|
| -------- | -------- | -------- |
|
|
|
|
| 3.1.0 | [License](../raw/master/LICENSE) | [Javadocs](javadocs/index.html) |
|
|
|
|
|
|
|
|
### Download
|
|
|
|
|
|
|
|
[Zip Distribution](downloads/3.1.0/edldap-3.1.0-dist.zip)
|
|
|
|
[Signature](downloads/3.1.0/edldap-3.1.0-dist.zip.asc)
|
|
|
|
|
|
|
|
[TGZ Distribution](downloads/3.1.0/edldap-3.1.0-dist.tar.gz)
|
|
|
|
[Signature](downloads/3.1.0/edldap-3.1.0-dist.tar.gz.asc)
|
|
|
|
|
|
|
|
### Maven
|
|
|
|
If you would like to use this project in your maven build, include the following in your pom.xml:
|
|
|
|
|
|
|
|
```xml
|
|
|
|
<dependencies>
|
|
|
|
<dependency>
|
|
|
|
<groupId>edu.vt.middleware</groupId>
|
|
|
|
<artifactId>edldap</artifactId>
|
|
|
|
<version>3.1.0</version>
|
|
|
|
</dependency>
|
|
|
|
</dependencies>
|
|
|
|
|
|
|
|
<repositories>
|
|
|
|
<repository>
|
|
|
|
<id>middleware.vt.edu.repo</id>
|
|
|
|
<url>https://git.it.vt.edu/middleware/maven-repo/raw/master</url>
|
|
|
|
</repository>
|
|
|
|
</repositories>
|
|
|
|
```
|
|
|
|
|
|
|
|
#### What's new?
|
|
|
|
* Support for latest stable Spring 4
|
|
|
|
* Support for latest stable Tomcat 8
|
|
|
|
* Support for latest stable Jetty 9
|
|
|
|
* Requires Java 8 (Performance increase)
|
|
|
|
|
|
|
|
#### Usage
|
|
|
|
|
|
|
|
The following project highlights the features of the EdLdap Library 3.1, along with some general use cases:
|
|
|
|
|
|
|
|
* [Example Project](https://git.it.vt.edu/ememisya/edldap-examples)
|
|
|
|
|
|
|
|
The following page highlights the features of the EdLdap Library 3.1 EdAuth:
|
|
|
|
|
|
|
|
* [Ed-Auth Extended Support (Spring, Jetty, Tomcat & more)](edauth)
|
|
|
|
|
|
|
|
The usage for [ED-Lite](http://middleware.vt.edu/doku.php?id=middleware:ed:edlite) and [ED-Auth](http://middleware.vt.edu/doku.php?id=middleware:ed:edauth) does not require client certificate authentication, however using [ED-ID](http://middleware.vt.edu/doku.php?id=middleware:ed:edid) does.
|
|
|
|
|
|
|
|
To do this you must configure an **edldap.properties** file.
|
|
|
|
|
|
|
|
The edldap.properties file (*[example from sample project](https://git.it.vt.edu/ememisya/edldap-examples/blob/master/src/main/resources/edldap.properties)*) must reside in your classpath (ex: *WEB-INF/classes* for most web applications), alternatively you may specify the location of the edldap.properties file by setting a Java System Property called **"edldap.properties"** with its value as the absolute path to the file (ex: *java -Dedldap.properties="/path/to/edldap.properties"*).
|
|
|
|
|
|
|
|
An edldap.property configuration directive consists of the following format:
|
|
|
|
|
|
|
|
* edldap.**<directory_type>**.ssl.**<property>**=**<value>**
|
|
|
|
|
|
|
|
**<directory_type>** can be one of __**edid**__, __**edlite**__, or __**edauth**__.
|
|
|
|
|
|
|
|
*EDLdap Library supports both JKS, BKS ...*
|
|
|
|
|
|
|
|
```
|
|
|
|
# --[ssl.type = jks]--
|
|
|
|
# Specify the keystore you'd like to use under keystorePath.
|
|
|
|
# If you don't specify a truststorePath, the default ed.truststore
|
|
|
|
# included in the library will be used. Keystore password must be 'changeit'
|
|
|
|
# both BKS and JKS types are supported.
|
|
|
|
# --------------------
|
|
|
|
|
|
|
|
edldap.<directory_type>.ssl.type=jks
|
|
|
|
edldap.<directory_type>.ssl.keystorePath=file:/...
|
|
|
|
edldap.<directory_type>.ssl.truststorePath=file:/...
|
|
|
|
```
|
|
|
|
|
|
|
|
*... and X509 formats for client authentication.*
|
|
|
|
|
|
|
|
```
|
|
|
|
# --[ssl.type = x509]--
|
|
|
|
# Specify the client certificate under authenticationCertificatePath
|
|
|
|
# Specify the certificate key under authenticationCertificateKeyPath
|
|
|
|
# If you don't specify a trustCertificatesPath, the default trustchain.pem
|
|
|
|
# included in the library will be used.
|
|
|
|
# The credential files can be one of all types supported for X.509 version 3
|
|
|
|
# certificate, as specified by ISO/IEC and ANSI X9.
|
|
|
|
# --------------------
|
|
|
|
|
|
|
|
edldap.**<directory_type>**.ssl.type=x509
|
|
|
|
edldap.**<directory_type>**.ssl.authenticationCertificatePath=file:/... (.cer, .der, .pem...)
|
|
|
|
edldap.**<directory_type>**.ssl.authenticationCertificateKeyPath=file:/... (.cer, .der, .pem...)
|
|
|
|
edldap.**<directory_type>**.ssl.trustCertificatesPath=file:/... (.cer, .der, .pem...)
|
|
|
|
```
|
|
|
|
|
|
|
|
To use ED-ID with a PEM certificate and key the following configuration may be used:
|
|
|
|
|
|
|
|
```
|
|
|
|
edldap.edid.ssl.type=x509
|
|
|
|
edldap.edid.ssl.authenticationCertificatePath=file:/path_to_service_certificate.pem
|
|
|
|
edldap.edid.ssl.authenticationCertificateKeyPath=file:/path_to_certificate_key.pem
|
|
|
|
```
|
|
|
|
|
|
|
|
Setting the **.trustCertificatesPath** and **.truststorePath** should be optional as the default certificate chain is included with the library.
|
|
|
|
|
|
|
|
Once configured please take a look at [this project](https://git.it.vt.edu/ememisya/edldap-examples) for a basic implementation.
|
|
|
|
|
|
|
|
Command Line Usage
|
|
|
|
------
|
|
|
|
|
|
|
|
The library also supports command-line interface to perform all of its features which may be used in cron jobs or scripting.
|
|
|
|
|
|
|
|
**eldap commandline usage:**
|
|
|
|
```
|
|
|
|
usage: edldap
|
|
|
|
-authenticate Authenticate user
|
|
|
|
-authorize <arg> Authenticate and authorize user by SpEL expression
|
|
|
|
-credential <arg> Authentication credential
|
|
|
|
-env <arg> DEV|PPRD|PROD
|
|
|
|
-h,--help display this help listing
|
|
|
|
-query <arg> Execute LDAP query
|
|
|
|
-showaffils Authenticate user and show affiliations
|
|
|
|
-showgroups Authenticate user and show group membership
|
|
|
|
-type <arg> EDAUTH|EDID|EDLITE
|
|
|
|
-user <arg> Authentication username
|
|
|
|
```
|
|
|
|
|
|
|
|
The following uses ED-Auth to authenticate and authorize the PID 'ememisya' using the existence of the affiliation VT-FACULTY as its authorization requirement.
|
|
|
|
|
|
|
|
```
|
|
|
|
&{EDLDAP_LIBRARY}/bin/edldap -env DEV -authorize 'hasAttributeValue("eduPersonAffiliation","VT-FACULTY")' -user ememisya
|
|
|
|
```
|
|
|
|
The output is as follows:
|
|
|
|
```
|
|
|
|
Enter password for user ememisya:
|
|
|
|
Performing authorization using EDAUTH
|
|
|
|
User: ememisya
|
|
|
|
SUCCESS. Authenticated and authorized ememisya
|
|
|
|
```
|
|
|
|
All failures will begin with **Exception in thread***
|
|
|
|
```
|
|
|
|
Enter password for user ememisya:
|
|
|
|
Performing authorization using EDAUTH
|
|
|
|
User: ememisya
|
|
|
|
Exception in thread "main" edu.vt.middleware.ldap.ed.EdAuthAuthorizationException: Could not match all attributes requested for authorization.
|
|
|
|
``` |
|
|
\ No newline at end of file |
