Collaborations and Bearer Tokens¶
Sites in the OSG grant access to their grid services based on client's association with a specific collaboration (i.e. VO) instead of granting access on a per-user basis. In the past, this type of access was provided through X.509 proxies with VOMS attributes to demonstrate assocation with a collaboration:
- Users (both human and robots) would request that their collaboration sign their X.509 proxies (usually through a VOMS server),
- Or in the case of automated services (i.e. pilot job submission) a collaboration could directly create and sign proxies themselves
Now, sites can authenticate and authorize clients presenting bearer tokens, such as SciTokens or WLCG tokens. This document describes how collaborations can issue bearer tokens for the aforementioned use cases in ways that are compatible with OSG sites.
To generate bearer tokens, a collaboration must adminster at least one "token issuer" to issue tokens to their users. In addition to generating and signing tokens, token issuers provide a public endpoint that can be used to validate an issued token, e.g. an OSG Compute Entrypoint (CE) will contact the token issuer to authorize a bearer token used for pilot job submission.
Token issuer uptime
Due to the centralized nature of bearer token validation, token issuers should be treated as critical, highly available services. Otherwise, a token issuer outage will result in OSG sites being unable to authenticate a collaboration's tokens, meaning an interruption in pilot job submission and authenticated data transfers.
Choose one of the token issuer types below, depending on the needs of your collaboration.
If your collaboration centrally administers all services requiring bearer tokens and your users do not need to directly manage bearer tokens, consider running a simple token issuer. A simple token issuer consists of a public/private certificate keypair where the private key is used to issue tokens directly and the public certificate is made available through a web server.
For example, the OSPool (née OSG VO) serves its public certificate through GitHub pages and uses the private key to sign tokens used for pilot job submission as well as automatically generating tokens to accompany user jobs so that they can access their private storage areas.
If your collaboration distributes administrative responsibility or your users need to request and manage their own tokens, you should administer an OAuth2/OpenID Connect (OIDC) service (e.g., INDIGO IAM) or work with an existing OAuth2/OIDC provider (e.g., CILogon).
For example, Fermilab uses CILogon as their OIDC provider combined with an HTVault server used to streamline the OIDC process for users and integrate with their local Kerberos.
Bearer tokens are self-describing credentials that enumerate their capabilities as "claims" and different token "profiles" enumerate common sets of claims. OSG sites support the following bearer token profiles:
Claims are further described below with recommendations to ensure the greatest compatibility with OSG sites.
scope claim is a space-separated list of authorizations that should be granted to the bearer.
Scopes utilized by OSG services include the following:
|Capability||SciTokens scope||WLCG scope|
<PATH> with a path to the storage location that the bearer should be authorized to access.
The issuer URL, or the
iss claim, indicates the endpoint to use for authenticating a given token.
A collaboration may have more than one token issuer but a single token issuer should never serve more than one
In other words, given the token issuer, the site can determine the collaboration that issued the token.
The following collaborations have registered token issuers with the OSG:
The OSG distributes the
osg-scitokens-mapfile RPM package that includes issuer and subject to default user
mappings for use by OSG CEs.
Subjects (i.e., the
sub claim) should be unique, stable identifiers that correspond to a user or service
(e.g. pilot job submission).
In other words, subjects combined with a token issuer can be used for suspending access for a given collaboration user,
user-level accounting, monitoring, auditing, or tracing.
In tandem with a token issuer URL (i.e., the
iss claim), subjects can be used by site HTCondor-CE or XRootD services
to map to a local identity.
Depending on your collaboration's userbase and contributing sites, you may have to take privacy concerns, such as
the GDPR into account when assigning subjects to users.
Thus, it may be preferable to assign users a randomly-generated string as their
To take advantage of the improved security posture of bearer tokens, we recommend that the
aud claim be set to the
For example, tokens used for submission to an HTCondor-CE should set the following:
aud = <CE FQDN>:<CE PORT>
WLCG tokens may have the
wlcg.groups claim consisting of a comma and space separated list of collaboration groups.
The format of these groups are similar to VOMS FQANs:
<role> with the collaboration, group, and role, respectively, where the
group and role are optional.
For example, the following groups and roles have been used by the ATLAS and CMS collaborations:
/atlas/ /atlas/usatlas /cms/Role=pilot /cms/local/Role=pilot
Traditionally, sites have made local accounting and scheduling decisions based on the first VOMS FQAN so collaborations
should set the first group/role in
wlcg.groups to the most specific group or role.
wlcg.groups = /cms/Role=pilot, /cms
wlcg.groups = /cms, /cms/Role=pilot
To get assistance, please use the this page.