Login and Authentication in AFS

As explained in Differences in Authentication, AFS authentication is separate from UNIX authentication because the two file systems are separate. The separation has two practical implications:

When a user successfully authenticates, the AFS authentication service passes a token to the user's Cache Manager. The token is a small collection of data that certifies that the user has correctly provided the password associated with a particular AFS identity. The Cache Manager presents the token to AFS server processes along with service requests, as proof that the user is genuine. To learn about the mutual authentication procedure they use to establish identity, see A More Detailed Look at Mutual Authentication.

The Cache Manager stores tokens in the user's credential structure in kernel memory. To distinguish one user's credential structure from another's, the Cache Manager identifies each one either by the user's UNIX UID or by a process authentication group (PAG), which is an identification number guaranteed to be unique in the cell. For further discussion, see Identifying AFS Tokens by PAG.

A user can have only one token per cell in each separately identified credential structure. To obtain a second token for the same cell, the user must either log into a different machine or obtain another credential structure with a different identifier than any existing credential structure, which is most easily accomplished by issuing the pagsh command (see Identifying AFS Tokens by PAG). In a single credential structure, a user can have one token for each of many cells at the same time. As this implies, authentication status on one machine or PAG is independent of authentication status on another machine or PAG, which can be very useful to a user or system administrator.

The AFS distribution includes library files that enable each system type's login utility to authenticate users with AFS and log them into the local file system in one step. If you do not configure an AFS-modified login utility on a client machine, its users must issue the klog command to authenticate with AFS after logging in.


The AFS-modified libraries do not necessarily support all features available in an operating system's proprietary login utility. In some cases, it is not possible to support a utility at all. For more information about the supported utilities in each AFS version, see the OpenAFS Release Notes.

Identifying AFS Tokens by PAG

As noted, the Cache Manager identifies user credential structures either by UNIX UID or by PAG. Using a PAG is preferable because it guaranteed to be unique: the Cache Manager allocates it based on a counter that increments with each use. In contrast, multiple users on a machine can share or assume the same UNIX UID, which creates potential security problems. The following are two common such situations:

  • The local superuser root can always assume any other user's UNIX UID simply by issuing the su command, without providing the user's password. If the credential structure is associated with the user's UNIX UID, then assuming the UID means inheriting the AFS tokens.

  • Two users working on different NFS client machines can have the same UNIX UID in their respective local file systems. If they both access the same NFS/AFS Translator machine, and the Cache Manager there identifies them by their UNIX UID, they become indistinguishable. To eliminate this problem, the Cache Manager on a translator machine automatically generates a PAG for each user and uses it, rather than the UNIX UID, to tell users apart.

Yet another advantage of PAGs over UIDs is that processes spawned by the user inherit the PAG and so share the token; thus they gain access to AFS as the authenticated user. In many environments, for example, printer and other daemons run under identities (such as the local superuser root) that the AFS server processes recognize only as the anonymous user. Unless PAGs are used, such daemons cannot access files for which the system:anyuser group does not have the necessary ACL permissions.

Once a user has a PAG, any new tokens the user obtains are associated with the PAG. The PAG expires two hours after any associated tokens expire or are discarded. If the user issues the klog command before the PAG expires, the new token is associated with the existing PAG (the PAG is said to be recycled in this case).

AFS-modified login utilities automatically generate a PAG, as described in the following section. If you use a standard login utility, your users must issue the pagsh command before the klog command, or include the latter command's -setpag flag. For instructions, see Using Two-Step Login and Authentication.

Users can also use either command at any time to create a new PAG. The difference between the two commands is that the klog command replaces the PAG associated with the current command shell and tokens. The pagsh command initializes a new command shell before creating a new PAG. If the user already had a PAG, any running processes or jobs continue to use the tokens associated with the old PAG whereas any new jobs or processes use the new PAG and its associated tokens. When you exit the new shell (by pressing <Ctrl-d>, for example), you return to the original PAG and shell. By default, the pagsh command initializes a Bourne shell, but you can include the -c argument to initialize a C shell (the /bin/csh program on many system types) or Korn shell (the /bin/ksh program) instead.

Using an AFS-modified login Utility

As previously mentioned, an AFS-modified login utility simultaneously obtains an AFS token and logs the user into the local file system. This section outlines the login and authentication process and its interaction with the value in the password field of the local password file.

An AFS-modified login utility performs a sequence of steps similar to the following; details can vary for different operating systems:

  1. It checks the user's entry in the local password file (the /etc/passwd file or equivalent).

  2. If no entry exists, or if an asterisk (*) appears in the entry's password field, the login attempt fails. If the entry exists, the attempt proceeds to the next step.

  3. The utility obtains a PAG.

  4. The utility converts the password provided by the user into an encryption key and encrypts a packet of data with the key. It sends the packet to the AFS authentication service (the AFS Authentication Server in the conventional configuration).

  5. The authentication service decrypts the packet and, depending on the success of the decryption, judges the password to be correct or incorrect. (For more details, see A More Detailed Look at Mutual Authentication.)

    • If the authentication service judges the password incorrect, the user does not receive an AFS token. The PAG is retained, ready to be associated with any tokens obtained later. The attempt proceeds to Step 6.

    • If the authentication service judges the password correct, it issues a token to the user as proof of AFS authentication. The login utility logs the user into the local UNIX file system. Some login utilities echo the following banner to the screen to alert the user to authentication with AFS. Step 6 is skipped.

           AFS(R) version Login

  6. If no AFS token was granted in Step 4, the login utility attempts to log the user into the local file system, by comparing the password provided to the local password file.

    • If the password is incorrect or any value other than an encrypted 13-character string appears in the password field, the login attempt fails.

    • If the password is correct, the user is logged into the local file system only.

As indicated, when you use an AFS-modified login utility, the password field in the local password file is no longer the primary gate for access to your system. If the user provides the correct AFS password, then the program never consults the local password file. However, you can still use the password field to control access, in the following way:

  • To prevent both local login and AFS authentication, place an asterisk (*) in the field. This is useful mainly in emergencies, when you want to prevent a certain user from logging into the machine.

  • To prevent login to the local file system if the user does not provide the correct AFS password, place a character string of any length other than the standard thirteen characters in the field. This is appropriate if you want to permit only people with local AFS accounts to login on your machines. A single X or other character is the most easily recognizable way to do this.

  • To enable a user to log into the local file system even after providing an incorrect AFS password, record a standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (passwd or equivalent).

Systems that use a Pluggable Authentication Module (PAM) for login and AFS authentication do not necessarily consult the local password file at all, in which case they do not use the password field to control authentication and login attempts. Instead, instructions in the PAM configuration file (on many system types, /etc/pam.conf) fill the same function. See the instructions in the OpenAFS Quick Beginnings for installing AFS-modified login utilities.

Using Two-Step Login and Authentication

In cells that do not use an AFS-modified login utility, users must issue separate commands to login and authenticate, as detailed in the OpenAFS User Guide:

  1. They use the standard login program to login to the local file system, providing the password listed in the local password file (the /etc/passwd file or equivalent).

  2. They must issue the klog command to authenticate with the AFS authentication service, including its -setpag flag to associate the new tokens with a process authentication group (PAG).

As mentioned in Creating Standard Files in New AFS Accounts, you can invoke the klog -setpag command in a user's .login file (or equivalent) so that the user does not have to remember to issue the command after logging in. The user still must type a password twice, once at the prompt generated by the login utility and once at the klog command's prompt. This implies that the two passwords can differ, but it is less confusing if they do not.

Another effect of not using an AFS-modified login utility is that the AFS servers recognize the standard login program as the anonymous user. If the login program needs to access any AFS files (such as the .login file in a user's home directory), then the ACL that protects the file must include an entry granting the l (lookup) and r (read) permissions to the system:anyuser group.

When you do not use an AFS-modified login utility, an actual (scrambled) password must appear in the local password file for each user. Use the /bin/passwd file to insert or change these passwords. It is simpler if the password in the local password file matches the AFS password, but it is not required.

Obtaining, Displaying, and Discarding Tokens

Once logged in, a user can obtain a token at any time with the klog command. If a valid token already exists, the new one overwrites it. If a PAG already exists, the new token is associated with it.

By default, the klog command authenticates the issuer using the identity currently logged in to the local file system. To authenticate as a different identity, use the -principal argument. To obtain a token for a foreign cell, use the -cell argument (it can be combined with the -principal argument). See the OpenAFS User Guide and the entry for the klog command in the OpenAFS Administration Reference.

To discard either all tokens or the token for a particular cell, issue the unlog command. The command affects only the tokens associated with the current command shell. See the OpenAFS User Guideand the entry for the unlog command in the OpenAFS Administration Reference.

To display the tokens associated with the current command shell, issue the tokens command. The following examples illustrate its output in various situations.

If the issuer is not authenticated in any cell:

   % tokens
   Tokens held by the Cache Manager:
          --End of list--

The following shows the output for a user with AFS UID 1000 in the Example Corporation cell:

   % tokens
   Tokens held by the Cache Manager:
   User's (AFS ID 1000) tokens for afs@example.com  [Expires Jun  2 10:00]
       --End of list--

The following shows the output for a user who is authenticated in Example Corporation cell, the Example Organization cell and the Example Network cell. The user has different AFS UIDs in the three cells. Tokens for the last cell are expired:

   % tokens
   Tokens held by the Cache Manager:
   User's (AFS ID 1000) tokens for afs@example.com  [Expires Jun  2 10:00]
   User's (AFS ID 4286) tokens for afs@example.org  [Expires Jun  3 1:34]
   User's (AFS ID 22) tokens for afs@example.net  [>>Expired<<]
       --End of list--

The Kerberos version of the tokens command (the tokens.krb command), also reports information on the ticket-granting ticket, including the ticket's owner, the ticket-granting service, and the expiration date, as in the following example. Also see Support for Kerberos Authentication.

   % tokens.krb
   Tokens held by the Cache Manager:
   User's (AFS ID 1000) tokens for afs@example.com [Expires Jun  2 10:00]
   User smith's tokens for krbtgt.EXAMPLE.COM@example.com [Expires Jun  2 10:00]
     --End of list--

Setting Default Token Lifetimes for Users

The maximum lifetime of a user token is the smallest of the ticket lifetimes recorded in the following three Authentication Database entries. The kas examine command reports the lifetime as Max ticket lifetime. Administrators who have the ADMIN flag on their Authentication Database entry can use the -lifetime argument to the kas setfields command to set an entry's ticket lifetime.

  • The afs entry, which corresponds to the AFS server processes. The default is 100 hours.

  • The krbtgt.cellname entry, which corresponds to the ticket-granting ticket used internally in generating the token. The default is 720 hours (30 days).

  • The entry for the user of the AFS-modified login utility or issuer of the klog command. The default is 25 hours for user entries created using the AFS 3.1 or later version of the Authentication Server, and 100 hours for user entries created using the AFS 3.0 version of the Authentication Server. A user can use the kas examine command to display his or her own Authentication Database entry.


An AFS-modified login utility always grants a token with a lifetime calculated from the previously described three values. When issuing the klog command, a user can request a lifetime shorter than the default by using the -lifetime argument. For further information, see the OpenAFS User Guide and the klog reference page in the OpenAFS Administration Reference.

Changing Passwords

Regular AFS users can change their own passwords by using either the kpasswd or kas setpassword command. The commands prompt for the current password and then twice for the new password, to screen out typing errors.

Administrators who have the ADMIN flag on their Authentication Database entries can change any user's password, either by using the kpasswd command (which requires knowing the current password) or the kas setpassword command.

If your cell does not use an AFS-modified login utility, remember also to change the local password, using the operating system's password-changing command. For more instructions on changing passwords, see Changing AFS Passwords.

Imposing Restrictions on Passwords and Authentication Attempts

You can help to make your cell more secure by imposing restrictions on user passwords and authentication attempts. To impose the restrictions as you create an account, use the A instruction in the uss template file as described in Increasing Account Security with the A Instruction. To set or change the values on an existing account, use the kas setfields command as described in Improving Password and Authentication Security.

By default, AFS passwords never expire. Limiting password lifetime can help improve security by decreasing the time the password is subject to cracking attempts. You can choose an lifetime from 1 to 254 days after the password was last changed. It automatically applies to each new password as it is set. When the user changes passwords, you can also insist that the new password is not similar to any of the 20 passwords previously used.

Unscrupulous users can try to gain access to your AFS cell by guessing an authorized user's password. To protect against this type of attack, you can limit the number of times that a user can consecutively fail to provide the correct password. When the limit is exceeded, the authentication service refuses further authentication attempts for a specified period of time (the lockout time). To reenable authentication attempts before the lockout time expires, an administrator must issue the kas unlock command.

In addition to settings on user's authentication accounts, you can improve security by automatically checking the quality of new user passwords. The kpasswd and kas setpassword commands pass the proposed password to a program or script called kpwvalid, if it exists. The kpwvalid performs quality checks and returns a code to indicate whether the password is acceptable. You can create your own program or modified the sample program included in the AFS distribution. See the kpwvalid reference page in the OpenAFS Administration Reference.

There are several types of quality checks that can improve password quality.

  • The password is a minimum length

  • The password is not a word

  • The password contains both numbers and letters

Support for Kerberos Authentication

If your site is using standard Kerberos authentication rather than the AFS Authentication Server, use the modified versions of the klog, pagsh, and tokens commands that support Kerberos authentication. The binaries for the modified version of these commands have the same name as the standard binaries with the addition of a .krb extension.

Use either the Kerberos version or the standard command throughout the cell; do not mix the two versions. AFS Product Support can provide instructions on installing the Kerberos version of these four commands. For information on the differences between the two versions of these commands, see the OpenAFS Administration Reference.