Skip to content

Using your identity

Your collaboration identity is used to authenticate you and authorise access to collaboration services, both via your web browser, and from software applications. Typically in your browser, you will need to use the username and password associated with your identity to gain access to services.

Outside of the browser a number of different technologies are used to authenticate and authorise access based on your identity.

What types of credentials are there?

IGWN Computing services that allow non-browser access should support one or more of the following credential types.

Kerberos

Kerberos is a network authentication protocol supported by a number of IGWN Computing services. Users can generate a ticket-granting ticket tied to their identity that can be used to authenticate against services.

Installing the Kerberos tools

The Kerberos command-line tools can be installed using your preferred package manager:

choco install mitkerberos
conda install --channel conda-forge krb5
apt-get install krb5-user
yum install krb5-workstation

SciTokens

SciTokens is a capability-based authorisation system whereby tokens are issued that grant access to perform specific actions on specific services (for example to query for segment information from the Segment Database).

Installing the htgettoken SciToken generation tool

The htgettoken tool can be installed using your preferred package manager on a number of systems:

conda install --channel conda-forge htgettoken

htgettoken is available for RHEL in the Open Science Grid yum repositories:

yum install htgettoken

X.509

The IGWN collaborations rely heavily on a technology standard called X.509 to authenticate users and authorise access to data and services.

In a typical workflow, users authenticate using their institutional or collaboration identity to create an X.509 credential that is valid for a short amount of time (normally a few days). This credential can then be leveraged to gain access to various computing centres and services.

Installing the ciecplib X.509 credential generation tool
conda install --channel conda-forge ciecplib

Debian packages are available from the IGWN Debian Repositories:

apt-get install ciecplib
python -m pip install ciecplib

RPM packages are available from the IGWN Yum Repositories (SL7, RL8):

yum install ciecplib

How to generate a credential

KAGRA

X.509 for KAGRA

KAGRA identity holders can create X.509 credentials when they are required using ecp-get-cert from the ciecplib Python package:

ecp-get-cert --identity-provider KAGRA --username albert.einstein --verbose

Notes:

  • you can also set the ECP_IDP environment variable to your default --identity-provider so that you don't have to enter it every time.

    export ECP_IDP="KAGRA"
    
    setenv ECP_IDP KAGRA
    
    $Env:ECP_IDP = "KAGRA"
    
  • the --reuse option can be passed to avoid unnecessarily generating a new credential if an existing one can be used, and is valid for more than the given number of hours.

LIGO (LIGO.ORG)

Kerberos for LIGO.ORG

LIGO.ORG identity holders can generate Kerberos credentials using the kinit command-line tool from the MIT Kerberos (krb5) distribution:

kinit albert.einstein@LIGO.ORG

Password-less authentication using a Kerberos keytab

Credentials can be stored in a keytab file to enable (re-)generation of Kerberos tickets without having to re-enter a password each time.

To generate a keytab file:

$ ktutil
ktutil:  addent -password -p albert.einstein@LIGO.ORG -k 1 -e des3-cbc-sha1
Password for albert.einstein@LIGO.ORG:
ktutil:  wkt ligo.org.keytab
ktutil:  quit

This will generate the ligo.org.keytab file in the current directory, feel free then to move it wherever you want.

It is common then to store the path of that file in the KRB5_KTNAME environment variable, e.g.:

export KRB5_KTNAME=${HOME}/.kerberos/ligo.org.keytab

Check permissions on Kerberos keytab

A Kerberos keytab can be used by anybody to impersonate the user who created it. It is extremely important that you verify that the permissions on your keytab file (ligo.org.keytab in the above example) are restricted to only allow read/write for you, the user:

chmod 600 ligo.org.keytab

ktutil not available on Windows

The ktutil utility required to generate keytabs is not available from MIT Kerberos on Windows.

SciTokens for LIGO.ORG

LIGO.ORG identity holders can generate tokens using the htgettoken command-line tool:

htgettoken -a vault.ligo.org -i ligo

X.509 for LIGO.ORG

LIGO.ORG identity holders can create X.509 credentials when they are required using ecp-get-cert from the ciecplib Python package:

ecp-get-cert --identity-provider LIGO --username albert.einstein --verbose

Notes:

  • you can also set the ECP_IDP environment variable to your default --identity-provider so that you don't have to enter it every time.

    export ECP_IDP="LIGO"
    
    setenv ECP_IDP LIGO
    
    $Env:ECP_IDP = "LIGO"
    
  • the --reuse option can be passed to avoid unnecessarily generating a new credential if an existing one can be used, and is valid for more than the given number of hours.

  • the --kerberos option can be used to use an existing kerberos ticket for authentication when generating a new X.509 credential.

Virgo

X.509 for Virgo

Getting a GRID certificate

Please get in touch with your Home Institution in order to obtain a GRID-enabled X.509 certificate. Once the certificate is obtained, install it on the machine(s) you intend to use to connect to the IGWN resources, following the instructions provided by your home institution.

The certificate may come in many different formats. In the end it should be converted to an X.509 certificate and then split, extracting the private key and your own public certificate. These two files should be placed in ~/.globus and are userkey.pem and usercert.pem. To get certificate-format-specific instructions to extract these two certificate components please refer to your Home Institution instructions.

The same ~/.globus folder with the two contained files should be present on any machine from which you expect to be able to create new proxy certificates (e.g. your laptop, a workstation, and your home directory on any remote submission machine of IGWN).

Virgo VOMS

Once you have a valid certificate, you are allowed to complete the procedure for the registration of your certificate in the Virgo VOMS (Virtual Organization Membership Service) by connecting to this page.

When opening this page a web browser prompt should ask you to provide a certificate to connect to the website. Select your X.509 certificate from the suggestions or manually select it if needed.

Once connected to the page you can apply for VOMS memberships using the provided button. Apply for /virgo and /virgo/virgo memberships selecting them from the dropdown menu.

You'll be notified by email upon membership approval.

Install the VOMS client package

VOMS users will need to install the VOMS client software package in order to use their Virgo identity, just search for voms* in your system's software package manager.

LIGO identities for Virgo members

Virgo members get LIGO.ORG identities

In order to workaround differences in collaboration identity management, all Virgo Collaboration members are also given a LIGO.ORG identity, which should be used to gain access to LIGO- or IGWN-operated computing centres, including the IGWN HTCondor submission points.

Please follow the LIGO (LIGO.ORG) instructions to use this identity.