Skip to content
This repository was archived by the owner on May 23, 2022. It is now read-only.

Commit 9f3d8c6

Browse files
brianhlinbrianhlin
authored
Merge pull request #941 from matyasselmeci/pr/SOFTWARE-5077.moartokens
Token overview (SOFTWARE-5077)
2 parents 51faaab + 3e54e17 commit 9f3d8c6

File tree

1 file changed

+157
-7
lines changed

1 file changed

+157
-7
lines changed

‎docs/security/tokens/overview.md‎

Lines changed: 157 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,139 @@
11
DateReviewed: 2022-03-10
2-
32
Bearer Token Overview
43
=====================
54

5+
Token-based Authentication and Authorization Infrastructure (AAI) is a security method
6+
that is intended as the replacement for X.509 for accessing compute and storage resources.
7+
This document will describe "bearer tokens," which are one of the components of Token AAI;
8+
bearer tokens are the type of token that server software such as HTCondor and XRootD will primarily interact with.
9+
10+
A bearer token (sometimes called an "access token") is a short-lived credential,
11+
performing a similar role as a grid proxy did in X.509.
12+
X.509 proxies established identity (the DN in your subject) and group membership (VOMS FQANs).
13+
Servers made decisions about access based on those properties.
14+
Tokens also have 'scope' which can restrict the actions that can be done with the token.
15+
For example, a token used for storage access can restrict the files that can be read to a particular directory tree.
16+
Instead of using a single proxy, a job may have multiple tokens.
17+
For example the job could have one token granting it the ability to be run;
18+
it could have a token for read access to an input dataset, and a token for write access to a results directory.
19+
20+
21+
Token Components
22+
----------------
23+
24+
Bearer tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format.
25+
A JWT consists of a JSON header, a JSON payload, and a signature that can be verified.
26+
The payload contains a number of fields, called "claims", that describe the token and what it can access.
27+
28+
There are two JWT-based token standards that can be used with OSG software: [SciTokens](https://scitokens.org)
29+
and [WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md).
30+
These standards describe the claims that are used in the payload of the JWT.
31+
32+
SciTokens and WLCG Tokens are similar standards and have some common claims:
33+
34+
**Issuer ("iss")**
35+
36+
The issuer identifies the organization that issued the token.
37+
An issuer looks like an HTTPS URL;
38+
this URL must be valid and publicly accessible as they are used by site services to validate the token.
39+
Token issuers will be [described below](#issuer).
40+
41+
**Subject ("sub")**
42+
43+
The subject identifies an entity (which could be a human or a robot) that owns the token.
44+
Unlike the subject of an X.509 certificate, a token subject does not need to be globally unique,
45+
only unique to the issuer.
46+
Subjects will be [elaborated on below](#subject).
47+
48+
**Issued-at ("iat"), not-before ("nbf"), expiration ("exp")**
49+
50+
These claims are Unix timestamps that specify when the token was issued, and its lifespan.
51+
52+
**Audience ("aud")**
53+
54+
The audience is a server (or a JSON list of servers) that the token may be used on;
55+
it is typically a hostname, host:port, or URI.
56+
For example a token used for submitting a job to a CE would have
57+
`<CE FQDN>:<CE PORT>` in the `aud` claim.
58+
The special values `ANY` (SciTokens) or `https://wlcg.cern.ch/jwt/v1/any` (WLCG Tokens) allow the token to be
59+
used on any server.
60+
61+
**Scope ("scope")**
62+
63+
The scope limits the actions that can be made using the token.
64+
The format of the scope claim differs between SciTokens and WLCG Tokens;
65+
scopes in use by OSG services will be [listed below](#scopes).
66+
WLCG Tokens may have a `wlcg.group` instead of a scope, [as described below](#wlcg-groups).
67+
68+
69+
### Issuer ###
70+
71+
To generate bearer tokens, a collaboration must adminster at least one "token issuer" to issue tokens to their users.
72+
In addition to generating and signing tokens, token issuers provide a public endpoint that can be used to validate an
73+
issued token,
74+
e.g. an OSG Compute Entrypoint (CE) will contact the token issuer to authorize a bearer token used for pilot job
75+
submission.
76+
77+
The issuer is listed in the `iss` claim; this should be an HTTPS URL of a web server.
78+
This server must have the public key that can be used to validate the token in a well-known location,
79+
as described by the [OpenID Connect Discovery standard](https://openid.net/specs/openid-connect-discovery-1_0.html).
80+
If the issuer is down, or the the public key cannot be downloaded, the token cannot be verified
81+
and will be rejected.
82+
Note that most clients will cache the public key.
83+
In order to ease the token transition, the current cache lifetime is 4 days,
84+
but at some point this will be lowered to a few hours.
85+
86+
A collaboration may have more than one token issuer,
87+
but a single token issuer should never serve more than one collaboration.
88+
The issuer claim should be able to uniquely identify the collaboration that identifies the token.
89+
90+
91+
### Subject ###
92+
93+
The subject is listed in the `sub` claim and should be unique, stable identifier that corresponds to a user (human)
94+
or a service (robot or pilot job submission).
95+
A subject does not need to be globally unique but it must be unique to the issuer.
96+
The subject, when combined with the issuer, will give a globally unique identity
97+
that can be used for mapping, banning, accounting, monitoring, auditing, or tracing.
98+
99+
!!! note
100+
Due to privacy concerns, the subject may be a randomly generated string, hash, UUID, etc.,
101+
that does not contain any personally identifying information.
102+
Tracing a token to a user or service may require contacting the issuer.
103+
104+
105+
### Scopes ###
106+
107+
The `scope` claim is a space-separated list of authorizations that should be granted to the bearer.
108+
Scopes utilized by OSG services include the following:
109+
110+
| **Capability** | **SciTokens scope** | **WLCG scope** |
111+
|------------------|---------------------|------------------------------------------------|
112+
| HTCondor `READ` | `condor:/READ` | `compute.read` |
113+
| HTCondor `WRITE` | `condor:/WRITE` | `compute.modify compute.cancel compute.create` |
114+
| XRootD read | `read:<PATH>` | `storage.read:<PATH>` |
115+
| XRootD write | `write:<PATH>` | `storage.modify:<PATH>` |
116+
117+
Replacing `<PATH>` with a path to the storage location that the bearer should be authorized to access.
118+
119+
A SciToken must have a non-empty scope, or it cannot be used to do anything.
120+
121+
122+
### WLCG Groups ###
123+
124+
A WLCG Token may have a `wlcg.groups` claim instead of a scope.
125+
The `wlcg.groups` claim is a comma and space separated list of collaboration groups.
126+
The format of these groups are similar to VOMS FQANs: `/<collaboration>[/<group>][/Role=<role>]`,
127+
replacing `<collaboration>`, `<group>`, and `<role>` with the collaboration, group, and role, respectively, where the
128+
group and role are optional.
129+
For example, the following groups and roles have been used by the ATLAS and CMS collaborations:
130+
131+
```
132+
/atlas/
133+
/atlas/usatlas
134+
/cms/Role=pilot
135+
/cms/local/Role=pilot
136+
```
6137

7138

8139

@@ -11,12 +142,13 @@ Validating Tokens in Pilot Jobs
11142

12143
If an incoming (pre-routed) pilot on a CE has a token, it will have the following classad attributes:
13144

14-
| Attribute | Meaning |
15-
|------------------|-------------------------------------|
16-
| AuthTokenId | A UUID of the token |
17-
| AuthTokenIssuer | The URL of the issuer of the token |
18-
| AuthTokenScopes | Any scope restrictions on the token |
19-
| AuthTokenSubject | The 'sub' field of the token |
145+
| Attribute | Meaning |
146+
|------------------|--------------------------------------|
147+
| AuthTokenId | A UUID of the token |
148+
| AuthTokenIssuer | The URL of the issuer of the token |
149+
| AuthTokenScopes | Any scope restrictions on the token |
150+
| AuthTokenSubject | The `sub` claim of the token |
151+
| AuthTokenGroups | The `wlcg.groups`, if any, claim of the token |
20152

21153
(A pre-routed job is a job without `RoutedJob=True` in its classad.)
22154

@@ -76,3 +208,21 @@ The following collaborations support support file transfer using WebDAV or XRoot
76208
| IceCube | Undergoing testing |
77209
| LIGO | Undergoing testing |
78210
| OSG | N/A |
211+
212+
213+
Help
214+
----
215+
216+
To get assistance, please use the [this page](https://opensciencegrid.org/docs/common/help/).
217+
218+
219+
References and Links
220+
--------------------
221+
222+
- [Troubleshooting Tokens](using-tokens.md#troubleshooting-tokens)
223+
- [OSG Technology - Collaborations and Bearer Tokens](https://opensciencegrid.org/technology/policy/collab-bearer-tokens/)
224+
- [JSON Web Tokens](https://jwt.io) - includes token decoder
225+
- [SciTokens](https://scitokens.org)
226+
- [SciToken Claims and Scopes Language](https://scitokens.org/technical_docs/Claims)
227+
- [SciTokens Demo](https://demo.scitokens.org/) - includes token generator, verifier, and links to libraries
228+
- [WLCG Common JWT Profiles](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md)

0 commit comments

Comments
 (0)