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

Commit 5fcc534

Browse files
matyasselmecimatyasselmeci
committed
Finish Token Components section
1 parent a081d58 commit 5fcc534

File tree

1 file changed

+105
-20
lines changed

1 file changed

+105
-20
lines changed

‎docs/security/tokens/overview.md‎

Lines changed: 105 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,6 @@ that is intended as the replacement for X.509 for accessing compute and storage
88
This document will describe "bearer tokens," which are one of the components of Token AAI;
99
bearer tokens are the type of token that server software such as HTCondor and XRootD will primarily interact with.
1010

11-
Bearer tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format.
12-
A JWT consists of a JSON header, a JSON payload, and a signature that can be verified.
13-
The payload contains a number of fields, called "claims", that describe the token and what it can access.
14-
15-
There are two JWT-based token standards that can be used with OSG software: [SciTokens](https://scitokens.org)
16-
and [WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md).
17-
These standards describe the claims that are used in the payload of the JWT.
18-
1911
A bearer token (sometimes called an "access token") is a short-lived credential,
2012
performing a similar role as a grid proxy did in X.509.
2113
X.509 proxies established identity (the DN in your subject) and group membership (VOMS FQANs).
@@ -29,21 +21,114 @@ it could have a token for read access to an input dataset, and a token for write
2921

3022
Token Components
3123
----------------
32-
SciTokens and WLCG Tokens are similar standards and have some common fields (known as "claims"):
3324

34-
- Each token must have an issuer ("iss") claim.
35-
This identifies the organization that issued the token.
36-
An issuer looks like an HTTPS URL;
37-
this URL must be valid and publicly accessible because it is used by services to validate the token.
25+
Bearer tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format.
26+
A JWT consists of a JSON header, a JSON payload, and a signature that can be verified.
27+
The payload contains a number of fields, called "claims", that describe the token and what it can access.
28+
29+
There are two JWT-based token standards that can be used with OSG software: [SciTokens](https://scitokens.org)
30+
and [WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md).
31+
These standards describe the claims that are used in the payload of the JWT.
32+
33+
SciTokens and WLCG Tokens are similar standards and have some common claims:
34+
35+
**Issuer ("iss")**
36+
37+
The issuer identifies the organization that issued the token.
38+
An issuer looks like an HTTPS URL;
39+
this URL must be valid and publicly accessible because it is used by services to validate the token.
40+
Token issuers will be described below.
41+
42+
**Subject ("sub")**
43+
44+
The subject identifies an entity (which could be a human or a robot) that owns the token.
45+
Unlike the subject of an X.509 certificate, a token subject does not need to be globally unique,
46+
only unique to the issuer.
47+
Subjects will be elaborated on below.
48+
49+
**Issued-at ("iat"), not-before ("nbf"), expiration ("exp")**
50+
51+
These claims are Unix timestamps that specify when the token was issued, and its lifespan.
52+
53+
**Audience ("aud")**
54+
55+
The audience is a server (or a JSON list of servers) that the token may be used on;
56+
it is typically a hostname, host:port, or URI.
57+
For example a token used for submitting a job to a CE would have
58+
`<CE FQDN>:<CE PORT>` in the `aud` claim.
59+
The special values `ANY` (SciTokens) or `https://wlcg.cern.ch/jwt/v1/any` (WLCG Tokens) allow the token to be
60+
used on any server.
61+
62+
**Scope ("scope")**
63+
64+
The scope limits the actions that can be made using the token.
65+
The format of the scope claim differs between SciTokens and WLCG Tokens;
66+
scopes in use by OSG services will be listed below.
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+
83+
A collaboration may have more than one token issuer,
84+
but a single token issuer should never serve more than one collaboration.
85+
The issuer claim should be able to uniquely identify the collaboration that identifies the token.
86+
87+
88+
### Subject ###
89+
90+
The subject is listed in the `sub` claim and should be unique, stable identifier that corresponds to a user (human)
91+
or a service (robot or pilot job submission).
92+
A subject does not need to be globally unique but it must be unique to the issuer.
93+
The subject, when combined with the issuer, will give a globally unique identity
94+
that can be used for mapping, banning, accounting, monitoring, auditing, or tracing.
95+
96+
!!! note
97+
Due to privacy concerns, the subject may be a randomly generated string, hash, UUID, etc.,
98+
that does not contain any personally identifying information.
99+
Tracing a token to a user or service may require contacting the issuer.
100+
101+
102+
### Scopes and WLCG Groups ###
103+
104+
The `scope` claim is a space-separated list of authorizations that should be granted to the bearer.
105+
Scopes utilized by OSG services include the following:
106+
107+
| **Capability** | **SciTokens scope** | **WLCG scope** |
108+
|------------------|---------------------|------------------------------------------------|
109+
| HTCondor `READ` | `condor:/READ` | `compute.read` |
110+
| HTCondor `WRITE` | `condor:/WRITE` | `compute.modify compute.cancel compute.create` |
111+
| XRootD read | `read:<PATH>` | `storage.read:<PATH>` |
112+
| XRootD write | `write:<PATH>` | `storage.modify:<PATH>` |
113+
114+
Replacing `<PATH>` with a path to the storage location that the bearer should be authorized to access.
115+
116+
A SciToken must have a non-empty scope, or it cannot be used to do anything.
117+
118+
A WLCG Token may have a `wlcg.groups` claim instead of a scope.
119+
This is a comma and space separated list of collaboration groups.
120+
The format of these groups are similar to VOMS FQANs: `/<collaboration>[/<group>][/Role=<role>]`,
121+
replacing `<collaboration>`, `<group>`, and `<role>` with the collaboration, group, and role, respectively, where the
122+
group and role are optional.
123+
For example, the following groups and roles have been used by the ATLAS and CMS collaborations:
38124

39-
- Tokens should have a limited lifespan.
40-
This is described by the issued-at ("iat"), not-before ("nbf"), and expiration ("exp") claims,
41-
all of which are Unix timestamps.
125+
```
126+
/atlas/
127+
/atlas/usatlas
128+
/cms/Role=pilot
129+
/cms/local/Role=pilot
130+
```
42131

43-
- Tokens must have a subject ("sub") claim.
44-
The subject identifies an entity (which could be a human or a robot) that owns the token.
45-
Unlike the subject of an X.509 certificate, a token subject does not need to be globally unique,
46-
only unique to the issuer.
47132

48133
Validating Tokens in Pilot Jobs
49134
-------------------------------

0 commit comments

Comments
 (0)