Add Kerberos authentication

_data/sidebars/merlin6_sidebar.yml

@@ -39,6 +39,8 @@ entries:
       url: /merlin6/nomachine.html
     - title: Configuring SSH Keys
       url: /merlin6/ssh-keys.html
+    - title: Kerberos and AFS authentication
+      url: /merlin6/kerberos.html
     - title: Software repository - PModules
       url: /merlin6/using-modules.html
   - title: Slurm General Documentation

pages/merlin6/02-How-To-Use-Merlin/kerberos.md

@@ -0,0 +1,155 @@
+---
+title: Configuring SSH Keys in Merlin
+
+#tags:
+keywords: Linux, connecting, client, configuration, Kerberos, AFS, keytab
+last_updated: 15 Jul 2020
+summary: "This document describes how to use Kerberos."
+sidebar: merlin6_sidebar
+permalink: /merlin6/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` and introduce the PSI password.
+```bash
+kinit
+```
+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 /psi/home/$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 0400 ~/.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**](/merlin6/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 a shared Kerberos5 cache (in example, in that way one can always refresh 
+granting tickets for long jobs from anywhere):
+
+```bash
+# Example one: Shared Kerberos5 cache
+#              Same cache file for all jobs
+#              Generally, always the recommended option
+export KRB5CCNAME="$(mktemp "$HOME/.k5/krb5cc_XXXXXX")"
+
+# Example two: Independent Kerberos5 cache
+#              ${SLURM_JOBID} will make the cache independent per job
+#              Use it only if necessary
+export KRB5CCNAME="$(mktemp "$HOME/.k5/krb5cc_${SLURM_JOBID}")"
+```
+* 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
+```
+
+### Slurm batch script example: obtaining KRB+AFS granting 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."
+```