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).

What is a SciToken?¶

A SciToken is a special implementation of a JSON Web Token designed for distributed scientific computing. For full details on the SciTokens project and the implementation of the tokens, see

https://scitokens.org/

Key SciTokens concepts¶

Key to the IGWN usage of SciTokens are the following concepts:

Audience¶

The Audience of a token (encoded in the aud claim) is the service that a token is authorised to acccess.

This should typically be the fully-qualified URI of the target service, e.g. https://gracedb.ligo.org.

The Audience can also have the special value ANY, which should allow it to be used with any service. Usage of ANY tokens is discouraged for security reasons.

Scope¶

The Scope of a token (the scope claim) is a space-separated list of capabilities that the token should authorise. For IGWN the valid scopes are service-specific:

Proprietary IGWN data¶

To access proprietary IGWN GWF data (from the igwn.osgstorage.org CVMFS repository), users should use tokens that claim the following scope:

read:/frames

DQSegDB¶

DQSegDB token implementation is not yet complete

Currently DQSegDB does not accept SciTokens for authorisation, see X.509 for details on using X.509 for authorised DQSegDB queries.

You can track the progress of this implementation at

https://git.ligo.org/groups/computing/dqsegdb/-/epics/1

GraceDB¶

GraceDB understands the following token scopes:

Scope	Purpose
`gracedb.read`	Authorise the bearer for GraceDB access

The gracedb.read scope is used as a proxy for an identification token - GraceDB uses its own internal authorisation system to assign capabilities to the subject (owner) of the token.

GWDataFind¶

GWDataFind accepts the following tokens:

Scope	Purpose
`gwdatafind.read`	Retrieve information from a GWDataFind server

Installing the SciTokens tools¶

There are a few different tools to install based on usage:

htgettoken - for generating SciTokens
igwn-auth-utils - for discovering/using SciTokens with HTTP requests

Installing `htgettoken`¶

htgettoken is a tool for generating SciTokens via the IGWN Vault server.

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

CondaDebianRHEL / CentOS / Rocky Linux / Scientific Linux

conda install --channel conda-forge htgettoken

htgettoken is available for Debian in the IGWN Debian repositories:

apt-get install htgettoken

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

yum install htgettoken

Installing `igwn-auth-utils`¶

igwn-auth-utils is a Python library for discovering SciTokens and using them with HTTP requests.

Most IGWN service APIs use igwn-auth-utils automatically

The client API libraries for most IGWN services (including GraceDB and GWDataFind) automatically install and use igwn-auth-utils for handling SciTokens, so you probably don't need to install it manually.

igwn-auth-utils can be installed using your preferred package manager on a number of systems:

CondaDebianPipRHEL / CentOS / Rocky Linux / Scientific Linux

conda install --channel conda-forge igwn-auth-utils

python3-igwn-auth-utils is available for Debian in the IGWN Debian repositories:

apt-get install python3-igwn-auth-utils

python -m pip install igwn-auth-utils

python3-igwn-auth-utils is available for RHEL and derivatives in the IGWN RHEL repositories for Scientific Linux 7 and Rocky Linux 8:

yum install python3-igwn-auth-utils

How to generate a SciToken¶

LIGO.ORG and KAGRA identity holders can generate tokens using htgettoken:

htgettoken -a vault.ligo.org -i igwn

By default this command will generate a token with the following claims

Claim	Value
`aud`	`"ANY"`
`scope`	`read:/frames gracedb.read dqsegdb.read`

Widely-scoped tokens are insecure

The default token is widely scoped, valid with any service with multiple capabilities. This presents a security risk, allowing an intruder to retrieve multiple forms of protected data while in posession of a token.

Generating a secure token¶

To generate a secure token, you should specify the --audience and --scopes as narrowly as possible to generate a token that with a single capability accepted by a single service.

For example, to generate a token that allows the bearer to read data from https://datafind.ligo.org only:

htgettoken -a vault.ligo.org --audience https://datafind.ligo.org --scopes gwdatafind.read