ED-LDAP Java 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.2.0 License Javadocs

Download

Zip Distribution Signature

TGZ Distribution Signature

Maven

If you would like to use this project in your maven build, include the following in your pom.xml:

<dependencies>
  <dependency>
      <groupId>edu.vt.middleware</groupId>
      <artifactId>edldap</artifactId>
      <version>3.2.0</version>
  </dependency>
</dependencies>

<repositories>
  <repository>
    <id>middleware.vt.edu.repo</id>
    <url>https://code.vt.edu/middleware/maven-repo/raw/master</url>
  </repository>
</repositories>

What’s new?

Usage

The following page highlights the features of the EdLdap Library’s EdAuth functionality:

The usage for ED-Lite and ED-Auth does not require client certificate authentication, however using ED-ID does.

To do this you must configure an edldap.properties file.

The edldap.properties file 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:

<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 formatted 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.

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
 -mfa <arg>          Multi-factor source [DUO]
 -mfaval <arg>       Multi-factor value (For DUO: '[factor],[index|value]'
                     Unused sections may be omitted. Examples:
                     'passcode,343342' or 'phone,2' or 'push' or 'auto')
 -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 in EdAuth will throw edu.vt.middleware.ldap.ed.EdAuthAuthorizationException

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.