Skip to content

Account management operations

Jump to bottom
Charles Hedrick edited this page Feb 22, 2019 · 7 revisions

There are three major components to account management, all on services.cs.rutgers.edu. Source code is in this repository.

  • a web application for activating your account
  • administrator command line version of activation, activate
  • command-line tools for cron jobs to expire accounts and conduct account reviews
    • Config file**: /etc/activator.config. That file is for all tools. It has policies, file locations, URL's, passwords.

Table of Contents

Web process

Java code, running in **Tomcat**, behind Apache.

  • Tomcat is in /var/www/tomcat, with logging in .../logs/catalina.out and application in .../webapps/accounts. The application is deployed as .../webapps/accounts.war. Tomcat notices when this changes and unzips it into accounts, redeploying the application.
  • Tomcat is installed from the apache.org distribution site. There are instructions in /var/www for upgrading.
  • Tomcat is run from systemd, using /etc/systemd/system/tomcat.service. Note that it runs under k5start. K5start is responsible for maintaining a credential cache for http/services.cs.rutgers.edu, using the keytab /etc/krb5.keytab.services. The application uses those credentials for many of its operations.
  • .../bin/setenv.sh sets the enviornment parameters and arguments for Java. Note that it sets Java to Java 11. That means that this system is not using the OS's default Java. It explicitly asks for Java 11, because we use Java features newer than Java 8.
  • All changes to users are done using IPA commands. Those commands are logged to /var/log/messages or /var/log/secure
If there are issues, check, /var/www/tomcat/logs/catalina.out. Make sure k5start is running, and try klist /tmp/krb5ccservi ces to make sure the credentials are being maintained.

Apache is installed using yum. Configuration is in /etc/httpd/conf.d/virtualhost.conf. Most of this file has to do with other services on the system. The key item is 

<Location "/accounts">
   ProxyPass "ajp://localhost:8009/accounts"
</location>
This causes /accounts to be passed to Tomcat via a special protocol between Apache and Tomcat. The protocol is call ajp.

Apache logs to /var/log/httpd. However the logs won't show much about this application, since it's just passed to tomcat.

Data is kept in IPA's LDAP, except state information for notification and review, which is kept as files in /var/lib/activator/. In addition

  • The University's LDAP is used when activating an account and cleaning up. It tells us what classes the user is in, and a few other pieces of information.
  • An LCSR Oracle database is also used when activating and cleaning up. It has the role for each user. These are roles like faculty, TA, etc. However we keep more detailed roles than the University does, so typically accounts are based on role information from Oracle and class information from University LDAP.
If we suddenly start warning lots of people about account closures, make sure something isn't broken with our connection to University LDAP or Oracle. The connection information is in /etc/activator.config. /usr/local/bin/testdbs will check all the connections for you.

In general information is read from LDAP using Java's LDAP API, JNDI. Changes are made by using "ipa" commands in a subprocess. IPA does various things to maintain consistency. It seemed safest to let IPA to updates than to try and update LDAP myself.

IPA is authenticated by setting the environment variable KRB5CCNAME to either the privileged credential for http/services.cs.rutgers.edu or the user's own credential cache. When the user logs in, the login process puts credentials for him in /tmp/krb5cc_NETID.

LDAP queries are authenticated using GSSAPI (which the Java LDAP API's support). Credentials may be http/services or the user's credentials.

Account expiraton

A cron job runs nightly, /usr/local/libexec/syncall. It does two things:

  • /usr/local/bin/activate -c. This is the cleanup of users who have no more reason to be on the system
  • /usr/local/bin/cleanup. This asks faculty to review groups annually, and disables them if they aren't renewed.
Both of these use the same code as the web app. If you look at the scripts, you'll see that they set the Java classpath to classes and lib in /var/www/tomcat/webapps/accounts. So when you deploy the webapp, you're also updating these jobs.

"activate -c" uses the same main method as the web app, with different arguments. "cleanup" uses a separate method.

Both applications send email notifications and do final cleanup later. /var/lib/activator/notifications/ keeps track of when notifications were sent for account cleanup. /var/lib/activator/review is the same for faculty review of groups.

Outgoing mail is relayed through mx.farside.rutgers.edu.

As with the webapp, all changes are logged to /var/log/messages or /var/log/secure. Because the cron jobs don't use /var/www/tomcat/logs/catalina.out, errors will probably show up in /var/log.

Actions with LDAP and IPA are authenticated with http/services.cs.rutgers.edu. I believe the code reads the credential cache that's maintained by k5start, so if k5start isn't working, the command line tools probably won't.

Activate command line tool

/usr/local/bin/activate lets you do things manually that users normally do through the web app. It works the same way as the command line tools for cleanup, so see the previous section.

Testing the system

If you're getting odd results from activation or cleanup, a reasonable test of overall functionality is 

; as root
/usr/local/bin/activate -v yourNetid
This should show your roles and the systems you're authorized for.

If it looks like there's an issue getting to the data 

; as non-root user who can sudo
/usr/local/bin/testdbs
This will try to get information about you from all the data sources used by the system.

Programming info

Source code is kept in git, https://github.com/clhedrick/kerberos/. It's in the account directory. At the top level there are build and deploy scripts.

The code uses Spring Boot. The web app is a very straightforward Spring Boot application. The main complexities are:

  • The actual account activation logic is in User.java. This file is not simple, because we provide quite a flexible set of policies. It's heavily commented. To make sense of it, you should look at /etc/activator.config. That is well commented, and will show you what the code is supposed to be doing with the various options. The code will make no sense without understanding how the config file works.
  • The code uses a layer of LDAP code. I find the Java JNDI API cumbersome. I supply a layer that reads the attributes and constructs a map modeled after how PHP handles LDAP. The main call passes a query, optionally a base DN for search, and the attributes to return. You then pull the map that is retuned out of the object. It is slightly complicated by authentication, but it should be clear from the usage in User.java what is going on.
  • The code uses two LDAP servers. The one from IPA is used to look at groups, and the user's current state. The University LDAP server is used to update the user's name, and also to find the list of classes they are in. An LCSR Oracle database is used to find user roles. E.g. faculty, adjunct, TA. We keep more specific roles than the University does. The rules let us user either, but most groups are built from LCSR's roles.
The code uses Java logging. The newest logging has quite flexible configuration. Depending upon how the code is called, I configure logging to go to syslog or the tty. The tty is used for "activate", since it's interactive. The various logging configuration files are in /var/www/tomcat/webapps/accounts/log4j*. There are more than you might expect, because I need interactive and background operation, and there's a verbose option that turns up the log level.

Note that the code currently requires Java 10 or later.

Clone this wiki locally