---
title: Kerberos and AFS authentication
#tags:
keywords: kerberos, AFS, kinit, klist, keytab, tickets, connecting, client, configuration, slurm
last_updated: 07 September 2022
summary: "This document describes how to use Kerberos."
sidebar: merlin7_sidebar
permalink: /merlin7/kerberos.html
---

Projects and users have their own areas in the central PSI AFS service. In order
to access to these areas, valid Kerberos and AFS tickets must be granted.

These tickets are automatically granted when accessing through SSH with
username and password. Alternatively, one can get a granting ticket with the `kinit` (Kerberos)
and `aklog` (AFS ticket, which needs to be run after `kinit`) commands.

Due to PSI security policies, the maximum lifetime of the ticket is 7 days, and the default
time is 10 hours. It means than one needs to constantly renew (`krenew` command) the existing
granting tickets, and their validity can not be extended longer than 7 days. At this point,
one needs to obtain new granting tickets.

## Obtaining granting tickets with username and password

As already described above, the most common use case is to obtain Kerberos and AFS granting tickets
by introducing username and password:

* When login to Merlin through SSH protocol, if this is done with username + password authentication,
tickets for Kerberos and AFS will be automatically obtained.
* When login to Merlin through NoMachine, no Kerberos and AFS are granted. Therefore, users need to
run `kinit` (to obtain a granting Kerberos ticket) followed by `aklog` (to obtain a granting AFS ticket).
See further details below.

To manually obtain granting tickets, one has to:

1. To obtain a granting Kerberos ticket, one needs to run `kinit $USER` and enter the PSI password.

   ```bash
   kinit $USER@D.PSI.CH
   ```

2. To obtain a granting ticket for AFS, one needs to run `aklog`. No password is necessary, but a valid
Kerberos ticket is mandatory.

   ```bash
   aklog
   ```

3. To list the status of your granted tickets, users can use the `klist` command.

   ```bash
   klist
   ```

4. To extend the validity of existing granting tickets, users can use the `krenew` command.

   ```bash
   krenew
   ```

   * Keep in mind that the maximum lifetime for granting tickets is 7 days, therefore `krenew` can not be used beyond that limit,
     and then `kinit` should be used instead.

## Obtanining granting tickets with keytab

Sometimes, obtaining granting tickets by using password authentication is not possible. An example are user Slurm jobs
requiring access to private areas in AFS. For that, there's the possibility to generate a **keytab** file.

Be aware that the **keytab** file must be **private**, **fully protected** by correct permissions and not shared with any
other users.

### Creating a keytab file

For generating a **keytab**, one has to:

1. Load a newer Kerberos ( `krb5/1.20` or higher) from Pmodules:

   ```bash
   module load krb5/1.20
   ```

2. Create a private directory for storing the Kerberos **keytab** file

   ```bash
   mkdir -p ~/.k5
   ```

3. Run the `ktutil` utility which comes with the loaded `krb5` Pmodule:

   ```bash
   ktutil
   ```

4. In the `ktutil` console, one has to generate a **keytab** file as follows:

   ```bash
   # Replace $USER by your username
   add_entry -password -k 0 -f -p $USER
   wkt /data/user/$USER/.k5/krb5.keytab
   exit
   ```

   Notice that you will need to add your password once. This step is required for generating the **keytab** file.

5. Once back to the main shell, one has to ensure that the file contains the proper permissions:

   ```bash
   chmod 0600 ~/.k5/krb5.keytab
   ```

### Obtaining tickets by using keytab files

Once the keytab is created, one can obtain kerberos tickets without being prompted for a password as follows:

```bash
kinit -kt ~/.k5/krb5.keytab $USER
aklog
```

## Slurm jobs accessing AFS

Some jobs may require to access private areas in AFS. For that, having a valid [**keytab**](/merlin7/kerberos.html#generating-granting-tickets-with-keytab) file is required.
Then, from inside the batch script one can obtain granting tickets for Kerberos and AFS, which can be used for accessing AFS private areas.

The steps should be the following:

* Setup `KRB5CCNAME`, which can be used to specify the location of the Kerberos5 credentials (ticket) cache. In general it should point to a shared area
(`$HOME/.k5` is a good location), and is strongly recommended to generate an independent Kerberos5 credential cache (it is, creating a new credential cache per Slurm job):

  ```bash
  export KRB5CCNAME="$(mktemp "$HOME/.k5/krb5cc_XXXXXX")"
  ```

* To obtain a Kerberos5 granting ticket, run `kinit` by using your keytab:

  ```bash
  kinit -kt "$HOME/.k5/krb5.keytab" $USER@D.PSI.CH
  ```

* To obtain a granting AFS ticket, run `aklog`:

  ```bash
  aklog
  ```

* At the end of the job, you can remove destroy existing Kerberos tickets.

  ```bash
  kdestroy
  ```

### Slurm batch script example: obtaining KRB+AFS granting tickets

#### Example 1: Independent crendetial cache per Slurm job

This is the **recommended** way. At the end of the job, is strongly recommended to remove / destroy the existing kerberos tickets.

```bash
#!/bin/bash
#SBATCH --partition=hourly            # Specify 'general' or 'daily' or 'hourly'
#SBATCH --time=01:00:00               # Strictly recommended when using 'general' partition.
#SBATCH --output=run.out              # Generate custom output file
#SBATCH --error=run.err               # Generate custom error  file
#SBATCH --nodes=1                     # Uncomment and specify #nodes to use
#SBATCH --ntasks=1                    # Uncomment and specify #nodes to use 
#SBATCH --cpus-per-task=1
#SBATCH --constraint=xeon-gold-6152
#SBATCH --hint=nomultithread
#SBATCH --job-name=krb5

export KRB5CCNAME="$(mktemp "$HOME/.k5/krb5cc_XXXXXX")"
kinit -kt "$HOME/.k5/krb5.keytab" $USER@D.PSI.CH
aklog
klist

echo "Here should go my batch script code."

# Destroy Kerberos tickets created for this job only
kdestroy
klist
```

#### Example 2: Shared credential cache

Some users may need/prefer to run with a shared cache file. For doing that, one needs to
setup `KRB5CCNAME` from the **login node** session, before submitting the job.

```bash
export KRB5CCNAME="$(mktemp "$HOME/.k5/krb5cc_XXXXXX")"
```

Then, you can run one or multiple jobs scripts (or parallel job with `srun`). `KRB5CCNAME` will be propagated to the
job script or to the parallel job, therefore a single credential cache will be shared amongst different Slurm runs.

```bash
#!/bin/bash
#SBATCH --partition=hourly            # Specify 'general' or 'daily' or 'hourly'
#SBATCH --time=01:00:00               # Strictly recommended when using 'general' partition.
#SBATCH --output=run.out              # Generate custom output file
#SBATCH --error=run.err               # Generate custom error  file
#SBATCH --nodes=1                     # Uncomment and specify #nodes to use
#SBATCH --ntasks=1                    # Uncomment and specify #nodes to use 
#SBATCH --cpus-per-task=1
#SBATCH --constraint=xeon-gold-6152
#SBATCH --hint=nomultithread
#SBATCH --job-name=krb5

# KRB5CCNAME is inherit from the login node session
kinit -kt "$HOME/.k5/krb5.keytab" $USER@D.PSI.CH
aklog
klist

echo "Here should go my batch script code."

echo "No need to run 'kdestroy', as it may have to survive for running other jobs"
```