From f676921a0a5fa05836186472e384f68663557a37 Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Wed, 9 Mar 2022 17:27:42 -0600 Subject: [PATCH 01/11] First chunk of token overview; changed title to Token AAI Overview (since it covers both authn and authz) --- docs/security/tokens/overview.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index c7691e0fc..c441e30bd 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -1,4 +1,16 @@ DateReviewed: 2022-03-10 +======= +Token Authentication/Authorization Infrastructure (AAI) Overview +================================================================ + +Token Authentication/Authorization Infrastructure (AAI) is a security method used +for accessing compute and storage resources. +It was introduced in the OSG 3.5 series as the replacement for X.509 security. + +Token AAI is built on the [JSON Web Token](https://jwt.io) standard; +supported implementations are [SciTokens](https://scitokens.org) +[WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md). + Bearer Token Overview ===================== From babf4eaa8f1b6c61ce3ec7caa93a887a1587a2c3 Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Thu, 10 Mar 2022 23:18:28 -0600 Subject: [PATCH 02/11] Wrote some words. Also Brian picked the title "Bearer Token Overview" so let's go with that --- docs/security/tokens/overview.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index c441e30bd..fc9d97b65 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -1,19 +1,24 @@ DateReviewed: 2022-03-10 ======= -Token Authentication/Authorization Infrastructure (AAI) Overview -================================================================ +Bearer Token Overview +===================== -Token Authentication/Authorization Infrastructure (AAI) is a security method used -for accessing compute and storage resources. -It was introduced in the OSG 3.5 series as the replacement for X.509 security. +Bearer Tokens are a security method used for accessing compute and storage resources, +introduced as a replacement for X.509. -Token AAI is built on the [JSON Web Token](https://jwt.io) standard; -supported implementations are [SciTokens](https://scitokens.org) -[WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md). +Bearer Tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format; +a JWT is a small piece of JSON data with a signature that can be verified. +There are two JWT-based token standards that can be used with OSG software: [SciTokens](https://scitokens.org) +and [WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md). +X.509 proxies established identity (the DN in your subject) and group membership (VOMS FQANs). +Servers made decisions about access based on those properties. +Tokens also have 'scope' which can restrict the actions that can be done with the token. +For example, a token used for storage access can restrict the files that can be read to a particular directory tree. +Instead of using a single proxy, a job may have multiple tokens. +For example the job could have one token granting it the ability to be run; +it could have a token for read access to an input dataset, and a token for write access to a results directory. -Bearer Token Overview -===================== From bd6a717808ed376a9ce9d6be345cff853852caf9 Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Sun, 13 Mar 2022 20:44:15 -0500 Subject: [PATCH 03/11] Continuing with overview. --- docs/security/tokens/overview.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index fc9d97b65..5325a71ec 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -3,14 +3,21 @@ DateReviewed: 2022-03-10 Bearer Token Overview ===================== -Bearer Tokens are a security method used for accessing compute and storage resources, -introduced as a replacement for X.509. +Token-based Authentication and Authorization Infrastructure (AAI) is a security method +that is intended as the replacement for X.509 for accessing compute and storage resources. +This document will describe "bearer tokens," which are one of the components of Token AAI; +bearer tokens are the type of token that server software such as HTCondor and XRootD will primarily interact with. + +Bearer tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format. +A JWT consists of a JSON header, a JSON payload, and a signature that can be verified. +The payload contains a number of fields, called "claims", that describe the token and what it can access. -Bearer Tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format; -a JWT is a small piece of JSON data with a signature that can be verified. There are two JWT-based token standards that can be used with OSG software: [SciTokens](https://scitokens.org) and [WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md). +These standards describe the claims that are used in the payload of the JWT. +A bearer token (sometimes called an "access token") is a short-lived credential, +performing a similar role as a grid proxy did in X.509. X.509 proxies established identity (the DN in your subject) and group membership (VOMS FQANs). Servers made decisions about access based on those properties. Tokens also have 'scope' which can restrict the actions that can be done with the token. @@ -20,8 +27,23 @@ For example the job could have one token granting it the ability to be run; it could have a token for read access to an input dataset, and a token for write access to a results directory. +Token Components +---------------- +SciTokens and WLCG Tokens are similar standards and have some common fields (known as "claims"): + +- Each token must have an issuer ("iss") claim. + This identifies the organization that issued the token. + An issuer looks like an HTTPS URL; + this URL must be valid and publicly accessible because it is used by services to validate the token. +- Tokens should have a limited lifespan. + This is described by the issued-at ("iat"), not-before ("nbf"), and expiration ("exp") claims, + all of which are Unix timestamps. +- Tokens must have a subject ("sub") claim. + The subject identifies an entity (which could be a human or a robot) that owns the token. + Unlike the subject of an X.509 certificate, a token subject does not need to be globally unique, + only unique to the issuer. Validating Tokens in Pilot Jobs ------------------------------- From 774775eda2813f54a01d16b6d6d800228a252d55 Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Mon, 14 Mar 2022 00:12:04 -0500 Subject: [PATCH 04/11] Finish Token Components section --- docs/security/tokens/overview.md | 125 ++++++++++++++++++++++++++----- 1 file changed, 105 insertions(+), 20 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index 5325a71ec..bf4da97bc 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -8,14 +8,6 @@ that is intended as the replacement for X.509 for accessing compute and storage This document will describe "bearer tokens," which are one of the components of Token AAI; bearer tokens are the type of token that server software such as HTCondor and XRootD will primarily interact with. -Bearer tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format. -A JWT consists of a JSON header, a JSON payload, and a signature that can be verified. -The payload contains a number of fields, called "claims", that describe the token and what it can access. - -There are two JWT-based token standards that can be used with OSG software: [SciTokens](https://scitokens.org) -and [WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md). -These standards describe the claims that are used in the payload of the JWT. - A bearer token (sometimes called an "access token") is a short-lived credential, performing a similar role as a grid proxy did in X.509. 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 Token Components ---------------- -SciTokens and WLCG Tokens are similar standards and have some common fields (known as "claims"): -- Each token must have an issuer ("iss") claim. - This identifies the organization that issued the token. - An issuer looks like an HTTPS URL; - this URL must be valid and publicly accessible because it is used by services to validate the token. +Bearer tokens are credential strings in the [JSON Web Token (JWT)](https://jwt.io) format. +A JWT consists of a JSON header, a JSON payload, and a signature that can be verified. +The payload contains a number of fields, called "claims", that describe the token and what it can access. + +There are two JWT-based token standards that can be used with OSG software: [SciTokens](https://scitokens.org) +and [WLCG Tokens](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md). +These standards describe the claims that are used in the payload of the JWT. + +SciTokens and WLCG Tokens are similar standards and have some common claims: + +**Issuer ("iss")** + +The issuer identifies the organization that issued the token. +An issuer looks like an HTTPS URL; +this URL must be valid and publicly accessible because it is used by services to validate the token. +Token issuers will be described below. + +**Subject ("sub")** + +The subject identifies an entity (which could be a human or a robot) that owns the token. +Unlike the subject of an X.509 certificate, a token subject does not need to be globally unique, +only unique to the issuer. +Subjects will be elaborated on below. + +**Issued-at ("iat"), not-before ("nbf"), expiration ("exp")** + +These claims are Unix timestamps that specify when the token was issued, and its lifespan. + +**Audience ("aud")** + +The audience is a server (or a JSON list of servers) that the token may be used on; +it is typically a hostname, host:port, or URI. +For example a token used for submitting a job to a CE would have +`:` in the `aud` claim. +The special values `ANY` (SciTokens) or `https://wlcg.cern.ch/jwt/v1/any` (WLCG Tokens) allow the token to be +used on any server. + +**Scope ("scope")** + +The scope limits the actions that can be made using the token. +The format of the scope claim differs between SciTokens and WLCG Tokens; +scopes in use by OSG services will be listed below. + + +### Issuer ### + +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. + +The issuer is listed in the `iss` claim; this should be an HTTPS URL of a web server. +This server must have the public key that can be used to validate the token in a well-known location, +as described by the [OpenID Connect Discovery standard](https://openid.net/specs/openid-connect-discovery-1_0.html). +If the issuer is down, or the the public key cannot be downloaded, the token cannot be verified +and will be rejected. + +A collaboration may have more than one token issuer, +but a single token issuer should never serve more than one collaboration. +The issuer claim should be able to uniquely identify the collaboration that identifies the token. + + +### Subject ### + +The subject is listed in the `sub` claim and should be unique, stable identifier that corresponds to a user (human) +or a service (robot or pilot job submission). +A subject does not need to be globally unique but it must be unique to the issuer. +The subject, when combined with the issuer, will give a globally unique identity +that can be used for mapping, banning, accounting, monitoring, auditing, or tracing. + +!!! note + Due to privacy concerns, the subject may be a randomly generated string, hash, UUID, etc., + that does not contain any personally identifying information. + Tracing a token to a user or service may require contacting the issuer. + + +### Scopes and WLCG Groups ### + +The `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** | +|------------------|---------------------|------------------------------------------------| +| HTCondor `READ` | `condor:/READ` | `compute.read` | +| HTCondor `WRITE` | `condor:/WRITE` | `compute.modify compute.cancel compute.create` | +| XRootD read | `read:` | `storage.read:` | +| XRootD write | `write:` | `storage.modify:` | + +Replacing `` with a path to the storage location that the bearer should be authorized to access. + +A SciToken must have a non-empty scope, or it cannot be used to do anything. + +A WLCG Token may have a `wlcg.groups` claim instead of a scope. +This is a comma and space separated list of collaboration groups. +The format of these groups are similar to VOMS FQANs: `/[/][/Role=]`, +replacing ``, ``, and `` 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: -- Tokens should have a limited lifespan. - This is described by the issued-at ("iat"), not-before ("nbf"), and expiration ("exp") claims, - all of which are Unix timestamps. +``` +/atlas/ +/atlas/usatlas +/cms/Role=pilot +/cms/local/Role=pilot +``` -- Tokens must have a subject ("sub") claim. - The subject identifies an entity (which could be a human or a robot) that owns the token. - Unlike the subject of an X.509 certificate, a token subject does not need to be globally unique, - only unique to the issuer. Validating Tokens in Pilot Jobs ------------------------------- From 1eb146744d3880e15c765e488c632c4c86c3998e Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Mon, 14 Mar 2022 00:12:24 -0500 Subject: [PATCH 05/11] Add info on AuthTokenGroups attribute --- docs/security/tokens/overview.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index bf4da97bc..adafd3ab9 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -135,12 +135,13 @@ Validating Tokens in Pilot Jobs If an incoming (pre-routed) pilot on a CE has a token, it will have the following classad attributes: -| Attribute | Meaning | -|------------------|-------------------------------------| -| AuthTokenId | A UUID of the token | -| AuthTokenIssuer | The URL of the issuer of the token | -| AuthTokenScopes | Any scope restrictions on the token | -| AuthTokenSubject | The 'sub' field of the token | +| Attribute | Meaning | +|------------------|--------------------------------------| +| AuthTokenId | A UUID of the token | +| AuthTokenIssuer | The URL of the issuer of the token | +| AuthTokenScopes | Any scope restrictions on the token | +| AuthTokenSubject | The `sub` claim of the token | +| AuthTokenGroups | The `wlcg.groups` claim of the token | (A pre-routed job is a job without `RoutedJob=True` in its classad.) From 21b64c29371d8020f22c070a20e1ca0526e5f6d7 Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Mon, 14 Mar 2022 00:13:47 -0500 Subject: [PATCH 06/11] Help link, references, and a short debugging section --- docs/security/tokens/overview.md | 45 ++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index adafd3ab9..c69623419 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -201,3 +201,48 @@ The following collaborations support support file transfer using WebDAV or XRoot | IceCube | Undergoing testing | | LIGO | Undergoing testing | | OSG | N/A | + + +Debugging Tokens +---------------- + +Validating a token: + +A token must be a _one-line_ string consisting of 3 base64-encoded parts separated by periods (`.`). +You can use the tools in the `scitokens-cpp` RPM to validate a SciToken or WLCG token. + +- Run `scitokens-verify ` (where `` is the text of the token) to validate the token using the issuer. + +- Run `scitokens-list-access ` (where `` is the text of the token, + `` is the issuer to verify the token with, + and `` is the server you are using the token to access). + +Examining a token: + +- Online: paste the token into . + +- Offline: + 1. Write the token to a file named `tok`. + 2. Run `IFS=. read header payload signature < tok`. + 3. Run `echo $header | base64 -d` to examine the header. + Run `echo $payload | base64 -d` to examine the payload. + Note: the header or payload may be missing the final padding characters (up to 2 `=` characters); + adding them (e.g. `echo $payload== | base64 -d`) should make base64 stop complaining about "invalid input" or "truncated input". + + + +Help +---- + +To get assistance, please use the [this page](https://opensciencegrid.org/docs/common/help/). + + +References and Links +-------------------- + +- [OSG Technology - Collaborations and Bearer Tokens](https://opensciencegrid.org/technology/policy/collab-bearer-tokens/) +- [JSON Web Tokens](https://jwt.io) - includes token decoder +- [SciTokens](https://scitokens.org) + - [SciToken Claims and Scopes Language](https://scitokens.org/technical_docs/Claims) + - [SciTokens Demo](https://demo.scitokens.org/) - includes token generator, verifier, and links to libraries +- [WLCG Common JWT Profiles](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md) From 4479a2692c2bd9db231299bafd8a8a00fee3d3cd Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Mon, 14 Mar 2022 00:46:45 -0500 Subject: [PATCH 07/11] Add some information about using tokens with a CE or with XRootD --- docs/security/tokens/overview.md | 39 ++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index c69623419..8287f9db3 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -130,6 +130,45 @@ For example, the following groups and roles have been used by the ATLAS and CMS ``` +Using Bearer Tokens with HTCondor-CE +------------------------------------ + +In order to support Token AAI, your CE must be based on OSG 3.6 or OSG 3.5-upcoming. +You will need HTCondor 9.0.0 or newer, and `SCITOKENS` must be enabled as an auth method (this is the default). + +You must have a mapfile which provides mappings from bearer tokens to Unix usernames, +based on the token's issuer and, optionally, subject. +The OSG distributes the `osg-scitokens-mapfile` RPM package that includes default mappings for use by OSG CEs. + +Token mapfile lines look like: +``` +SCITOKENS /^https\:\/\/scitokens\.org\/ligo,/ ligo +SCITOKENS /^https\:\/\/cilogon\.org\/gm2,gm2pilot\@fnal\.gov$/ gm2pilot +``` +These are regular expressions; the first matches a token with the issuer `https://scitokens.org/ligo` +and any subject, and maps it to the `ligo` user. +Note the trailing `,` in the regular expression: this separates the issuer from the subject. + +The second example matches the issuer `https://cilogon.org/gm2` _and_ the subject `gm2pilot@fnal.gov`, +and maps it to the `gm2pilot` user. + +A `SCITOKENS` mapfile line supports WLCG tokens as well. +Note that mapping can only be done on issuer and subject, _not_ `wlcg.groups`. + +See the [configuring authentication documentation for HTCondor-CE] +(https://opensciencegrid.org/docs/compute-element/install-htcondor-ce/#configuring-authentication) +for further information. + + +Using Bearer Tokens with XRootD +------------------------------- + +In order to support Token AAI, your XRootD installation must be based on OSG 3.6 or OSG 3.5-upcoming. +You will need XRootD 5.0.2 or newer, with the `xrootd-scitokens` plugin. +Follow the [configuring XRootD authorization documentation](https://opensciencegrid.org/docs/data/xrootd/xrootd-authorization) +for information on how to configure XRootD to accept bearer tokens. + + Validating Tokens in Pilot Jobs ------------------------------- From 3d0c836d7270adc3e561a8eb902ff3f1ae67f8e5 Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Mon, 14 Mar 2022 09:58:39 -0500 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: Brian Lin --- docs/security/tokens/overview.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index 8287f9db3..6432534c2 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -1,5 +1,4 @@ DateReviewed: 2022-03-10 -======= Bearer Token Overview ===================== @@ -36,7 +35,7 @@ SciTokens and WLCG Tokens are similar standards and have some common claims: The issuer identifies the organization that issued the token. An issuer looks like an HTTPS URL; -this URL must be valid and publicly accessible because it is used by services to validate the token. +this URL must be valid and publicly accessible as they are used by site services to validate the token. Token issuers will be described below. **Subject ("sub")** @@ -180,7 +179,7 @@ If an incoming (pre-routed) pilot on a CE has a token, it will have the followin | AuthTokenIssuer | The URL of the issuer of the token | | AuthTokenScopes | Any scope restrictions on the token | | AuthTokenSubject | The `sub` claim of the token | -| AuthTokenGroups | The `wlcg.groups` claim of the token | +| AuthTokenGroups | The `wlcg.groups`, if any, claim of the token | (A pre-routed job is a job without `RoutedJob=True` in its classad.) From 6a8c3828aa82b4855767227f43034fa61d14401a Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Tue, 15 Mar 2022 17:32:10 -0500 Subject: [PATCH 09/11] Remove "Debugging Tokens" section and add a link to the "Troubleshooting Tokens" section of the client doc --- docs/security/tokens/overview.md | 29 +---------------------------- 1 file changed, 1 insertion(+), 28 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index 6432534c2..6d223aade 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -241,34 +241,6 @@ The following collaborations support support file transfer using WebDAV or XRoot | OSG | N/A | -Debugging Tokens ----------------- - -Validating a token: - -A token must be a _one-line_ string consisting of 3 base64-encoded parts separated by periods (`.`). -You can use the tools in the `scitokens-cpp` RPM to validate a SciToken or WLCG token. - -- Run `scitokens-verify ` (where `` is the text of the token) to validate the token using the issuer. - -- Run `scitokens-list-access ` (where `` is the text of the token, - `` is the issuer to verify the token with, - and `` is the server you are using the token to access). - -Examining a token: - -- Online: paste the token into . - -- Offline: - 1. Write the token to a file named `tok`. - 2. Run `IFS=. read header payload signature < tok`. - 3. Run `echo $header | base64 -d` to examine the header. - Run `echo $payload | base64 -d` to examine the payload. - Note: the header or payload may be missing the final padding characters (up to 2 `=` characters); - adding them (e.g. `echo $payload== | base64 -d`) should make base64 stop complaining about "invalid input" or "truncated input". - - - Help ---- @@ -278,6 +250,7 @@ To get assistance, please use the [this page](https://opensciencegrid.org/docs/c References and Links -------------------- +- [Troubleshooting Tokens](using-tokens.md#troubleshooting-tokens) - [OSG Technology - Collaborations and Bearer Tokens](https://opensciencegrid.org/technology/policy/collab-bearer-tokens/) - [JSON Web Tokens](https://jwt.io) - includes token decoder - [SciTokens](https://scitokens.org) From 469a94b082b960ac678ad8f61704cc3887bb180e Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Tue, 15 Mar 2022 17:33:13 -0500 Subject: [PATCH 10/11] Add links, split "Scopes and WLCG Groups" into two, mention caching --- docs/security/tokens/overview.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index 6d223aade..2010973f7 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -36,14 +36,14 @@ SciTokens and WLCG Tokens are similar standards and have some common claims: The issuer identifies the organization that issued the token. An issuer looks like an HTTPS URL; this URL must be valid and publicly accessible as they are used by site services to validate the token. -Token issuers will be described below. +Token issuers will be [described below](#issuer). **Subject ("sub")** The subject identifies an entity (which could be a human or a robot) that owns the token. Unlike the subject of an X.509 certificate, a token subject does not need to be globally unique, only unique to the issuer. -Subjects will be elaborated on below. +Subjects will be [elaborated on below](#subject). **Issued-at ("iat"), not-before ("nbf"), expiration ("exp")** @@ -62,8 +62,9 @@ used on any server. The scope limits the actions that can be made using the token. The format of the scope claim differs between SciTokens and WLCG Tokens; -scopes in use by OSG services will be listed below. - +scopes in use by OSG services will be [listed below](#scopes). +WLCG Tokens may have a `wlcg.group` instead of a scope, [as described below](#wlcg-groups). + ### Issuer ### @@ -78,6 +79,9 @@ This server must have the public key that can be used to validate the token in a as described by the [OpenID Connect Discovery standard](https://openid.net/specs/openid-connect-discovery-1_0.html). If the issuer is down, or the the public key cannot be downloaded, the token cannot be verified and will be rejected. +Note that most clients will cache the public key. +In order to ease the token transition, the current cache lifetime is 4 days, +but at some point this will be lowered to a few hours. A collaboration may have more than one token issuer, but a single token issuer should never serve more than one collaboration. @@ -98,7 +102,7 @@ that can be used for mapping, banning, accounting, monitoring, auditing, or trac Tracing a token to a user or service may require contacting the issuer. -### Scopes and WLCG Groups ### +### Scopes ### The `scope` claim is a space-separated list of authorizations that should be granted to the bearer. Scopes utilized by OSG services include the following: @@ -114,8 +118,11 @@ Replacing `` with a path to the storage location that the bearer should be A SciToken must have a non-empty scope, or it cannot be used to do anything. + +### WLCG Groups ### + A WLCG Token may have a `wlcg.groups` claim instead of a scope. -This is a comma and space separated list of collaboration groups. +The `wlcg.groups` claim is a comma and space separated list of collaboration groups. The format of these groups are similar to VOMS FQANs: `/[/][/Role=]`, replacing ``, ``, and `` with the collaboration, group, and role, respectively, where the group and role are optional. From 3e54e172ae36c9ce165b0128fb8b7db7c5b30609 Mon Sep 17 00:00:00 2001 From: Matyas Selmeci Date: Tue, 15 Mar 2022 17:36:34 -0500 Subject: [PATCH 11/11] Delete "Using Bearer Tokens with {HTCondor-CE,XRootD}" sections for now --- docs/security/tokens/overview.md | 38 -------------------------------- 1 file changed, 38 deletions(-) diff --git a/docs/security/tokens/overview.md b/docs/security/tokens/overview.md index 2010973f7..8cd03323f 100644 --- a/docs/security/tokens/overview.md +++ b/docs/security/tokens/overview.md @@ -136,44 +136,6 @@ For example, the following groups and roles have been used by the ATLAS and CMS ``` -Using Bearer Tokens with HTCondor-CE ------------------------------------- - -In order to support Token AAI, your CE must be based on OSG 3.6 or OSG 3.5-upcoming. -You will need HTCondor 9.0.0 or newer, and `SCITOKENS` must be enabled as an auth method (this is the default). - -You must have a mapfile which provides mappings from bearer tokens to Unix usernames, -based on the token's issuer and, optionally, subject. -The OSG distributes the `osg-scitokens-mapfile` RPM package that includes default mappings for use by OSG CEs. - -Token mapfile lines look like: -``` -SCITOKENS /^https\:\/\/scitokens\.org\/ligo,/ ligo -SCITOKENS /^https\:\/\/cilogon\.org\/gm2,gm2pilot\@fnal\.gov$/ gm2pilot -``` -These are regular expressions; the first matches a token with the issuer `https://scitokens.org/ligo` -and any subject, and maps it to the `ligo` user. -Note the trailing `,` in the regular expression: this separates the issuer from the subject. - -The second example matches the issuer `https://cilogon.org/gm2` _and_ the subject `gm2pilot@fnal.gov`, -and maps it to the `gm2pilot` user. - -A `SCITOKENS` mapfile line supports WLCG tokens as well. -Note that mapping can only be done on issuer and subject, _not_ `wlcg.groups`. - -See the [configuring authentication documentation for HTCondor-CE] -(https://opensciencegrid.org/docs/compute-element/install-htcondor-ce/#configuring-authentication) -for further information. - - -Using Bearer Tokens with XRootD -------------------------------- - -In order to support Token AAI, your XRootD installation must be based on OSG 3.6 or OSG 3.5-upcoming. -You will need XRootD 5.0.2 or newer, with the `xrootd-scitokens` plugin. -Follow the [configuring XRootD authorization documentation](https://opensciencegrid.org/docs/data/xrootd/xrootd-authorization) -for information on how to configure XRootD to accept bearer tokens. - Validating Tokens in Pilot Jobs -------------------------------