Package: jpl.edrn.ldap.utils
🏃 JPL EDRN LDAP UtilitiesThis package just contains some handy LDAP utilities for theEarly Detection Research NetworkDirectory Service. The EDRN Directory Service is an OpenLDAP-based standalone directory that also happens to handle users and groups for not just EDRN but two other consortia:Consortium for Molecular and Cellular Characterization of Screen-Detected LesionsNational Institute of Standards and Technology💽 InstallationThis software requires Python 3. Python 3.9 or later is recommended, but Python 4 is not. Typically, you'll make a virtual environment and install the software with a litany like:python3 -m venv ldap-utils
cd ldap-utils
bin/pip install --upgrade --quiet setuptools wheel pip
bin/pip install jpl.edrn.ldap.utils==X.Y.ZwhereX.Y.Zis the version you want. To upgrade an existing installation, add--upgrade. Then "activate" the virtual environment (or use full paths to programs likeldap-utils/bin/create-users).👩‍🔧 UsageCurrently the only utility is thecreate-usersscript, which you run as follows:create-users USERSFILEwhere USERSFILE is a CSV file containing the usersand optionally their plain text passwordsto add to the LDAP server. For example, you'd run:create-users --url ldaps://naming.jpl.nasa.gov --replace newusers.csvto add the users innewusers.csvto the LDAP server onnaming.jpl.nasa.gov. If noUSERSFILEis given, the program will read CSV data from the standard input.💁‍♀️ Command-line OptionsYou can fine-tune the behavior ofcreate-userswith the following command-line options:OptionUsageDefault-r,--replaceIf given replace existing users, overwriting all attributresDo not replace-b,--baseBase DN for all usersou=users,o=NIST-o,--objectclassObject classes for new users(see below)-h,--urlURL to LDAP serverldaps://edrn-ds.jpl.nasa.gov-D,--manager-dnDN of the LDAP manager userA reasonable default-w,--passwordPassword of the LDAP manager user(see below)⚠️ Be careful with-ror--replace. If a user has changed their password, email address, or other attributes and their username appears in the CSV file, those changes will be lost.In addition, you can specify either--debugwhich causescreate-usersto print verbose debugging messages during its operation or--quietwhich causes it to only report errors. By default it gives informational messages only. You can also give--helpto get a summary of all the command-line options, including--versionwhich tells you what version you're running.🎓 Object ClassesThe default object classes for users are:inetOrgPersonorganizationalPersonpersontopYou can override this by providing-oor--objectclass; for example:create-users … --objectclass edrnPerson inetOrgPerson person top …🔑 LDAP Manager PasswordThecreate-usersprogram naturally needs the password for the LDAP manager so it can make updates to the user data. You can provide the password on the command line with-wor--password, but beware that other programs and users on the system will be able to see this password.If-wor--passwordis not given, the password will be taken from theMANAGER_DN_PASSWORDenvironment variable. If it is empty or unset, you will be prompted for the password—which is the safest way of providing it.🗂️ CSV File FormatThe single CSV file expected bycreate-usersshould have the following columns:ColumnPurposeMapped LDAP Attribute0Bare user ID (not a distinguished name), such asjoeorjschmoeuid(plus base DN)1Surname, such asSchmoesn2Common name, such asJoe Schmoecn3Email addressmail4Password, but may be blank (see below)userPasswordIf the first row and first column (row 0, column 0) contains the worduid, it's assumed to be a "header row" and is skipped. If there are additional columns beyond these five, they're ignored. Note that column 4 should contain theplain text passwordwith which to create the user. However, if it's blank, then a random password will be generated for the user.👉Note:Randomly generated passwordsare not recoverable. Those users will need to use your "forgotten password" feature (if any) to reset their passwords.Here's an example CSV file (with header row) that describes three users, the middle one of which will get a random password:uid,sn,cn,mail,password
joe,Schmoe,Joe Schmoe,joe@joe.com,h1ghly s3cr3t
waldo,Waldo,Where Is Waldo,waldo@waldo,com
lsimpson,Simpson,Lisa Simpson,lisa@simpsons.tv,bGdfj3z!jf01👨‍👩‍👧‍👦 GroupsThecreate-usersprogram doesnothingwith LDAP groups of users. You'll have to manage those on your own. For example, you might make an LDIF file like thisdn: cn=My Group,ou=groups,o=NIST
objectClass: groupOfUniqueNames
objectClass: top
cn: My Group
uniqueMember: uid=joe,ou=users,o=NIST
uniqueMember: uid=waldo,ou=users,o=NIST
uniqueMember: uid=lsimpson,ou=users,o=NISTand useldapaddto create the group.🔧 DevelopmentTo develop this locally, try the following:git clone https://github.com/EDRN/jpl.edrn.ldap.utils
cd jpl.edrn.ldap.utils
python3 -m venv .venv
.venv/bin/pip install --upgrade --silet setuptools build dist wheel
.venv/bin/pip install --editable .
.venv/bin/create-users …👥 ContributingYou can start by looking at theopen issues, forking the project, and submitting a pull request. You can alsocontact us by emailwith suggestions.🔢 VersioningWe use theSemVerphilosophy for versioning this software. For versions available, see thereleases madeon this project.👩‍🎨 CreatorsThe principal developer is:Sean Kelly📃 LicenseThe project is licensed under theApache version 2license.