Skip to content Skip to site navigation

Automated Authentication

To increase security and reduce risk, Stanford is sunsetting its WebAFS service that is used to upload and download files to AFS.

To optimize AFS and make sure it is serving its intended functions, UIT has also taken these actions:

  • UIT no longer automatically provisions new faculty and staff members with AFS user volumes. New faculty or staff who need a personal user volume must submit a Help request.
    • This change does not impact existing AFS directories or the process for adding permissions for new individuals to those existing directories. Your existing space and everything in it remains intact.
    • This change does not impact the auto-provisioning of new AFS user volumes for students and postdocs.

​Class volumes do not expire and are kept indefinitely. This is an official academic policy, and any change to this policy must be considered by the Faculty Senate.

Introduction

Occasionally it's necessary for automated processes to be able to authenticate to AFS. This mostly comes up in the context of either web servers serving content out of AFS or periodic processing such as cron jobs, although may come up in other cases as well. There is a separate page on serving web content out of AFS; this page describes how to authenticate an automated process to AFS.

In order to access AFS, one has to have an AFS token, obtained from a Kerberos ticket. Users obtain Kerberos tickets with their username and password. Automated processes don't use passwords; instead, they use a file known as a keytab. This is essentially a processed form of a password stored in a special disk format. With a keytab, one can obtain Kerberos tickets and AFS tokens using a program called kstart (or k5start).

Obtaining a keytab

The first step is to get a special Kerberos principal created for the application and then obtain a keytab for that principal. The keytab has to be kept secure and should not be stored in AFS (how would one authenticate to AFS to be able to read the keytab?), so the first step is to identify the server where the process will be run. The keytab should be stored on local disk on that server; traditionally, we put the keytab into /etc/ and name it keytab.service where service is a short name for the service.

The Kerberos principals for such uses are named service.service where service is a short name for the application that is using these AFS credentials. Please note that everyone in the university shares the same namespace here, so please make the service name specific enough that one could determine what group it is associated with. In other words, service.logdump is a bad name unless it's for a campus-wide logdump service; service.sul-logdump is a better name for a logdump service run by Stanford University Libraries.

See An Introduction to Keytabs for more information and how to request a service principal keytab with AFS access.

Setting ACLs

Next, you have to identify what directories the application will need to modify while it's running and make sure that this new Kerberos principal has the appropriate access to those directories.

The first step is to give the application access to those directories where it needs to read or write files. This can be done with the regular file permission commands. The application will be accessing AFS as service.service, that Kerberos principal that was created earlier, and can add that principal to AFS ACLs just like you would add any other user. You can also add it to AFS PTS groups if appropriate.

Also make sure that the application can get to the directories where it needs to do work. This means that it must have at least list (l) access to every parent directory all the way up to /afs/ir. The basic top-level directories of AFS like /afs/ir/dept or /afs/ir/data are all open to the public, so you only need to check up to one of those top-level directories. If anyone (system:anyuser), any Stanford system (system:campushosts), or any authenticated user (system:authuser) has l permissions, that directory is fine. Otherwise, you need to grant at least l permissions to your new Kerberos principal (or to some broader set of users including it, such as the above general groups).

Running the application

Finally, you're ready to run the application.

There are two ways to do this. One is to obtain a Kerberos ticket cache using kstart, either running in daemon mode to maintain the cache all the time or running immediately before the application runs, and then point the application at that ticket cache by setting KRBTKFILE. If using this approach, you need to run aklog before running the application, and you probably want to run the application from a shell script that uses /usr/bin/pagsh as the shell. This keeps the AFS tokens for this run of the application isolated from anything else that's going on at the system at the same time.

The best way to run the application with Kerberos tickets and a token is to use the latest version of k5start, available in source code from the kstart distribution page and available as a Debian package. You can just point k5start at a keytab, make sure you have aklog installed, and it will then obtain tickets, isolate the application from other AFS users, obtain tokens, and then run the application, refreshing the tickets and tokens until the application completes. See the k5start man page for instructions and examples.

Last modified April 12, 2023