From 6765537768f5e695b9d0225ccb8f135268106258 Mon Sep 17 00:00:00 2001 From: Brian P Bockelman Date: Tue, 17 Mar 2020 11:35:01 -0500 Subject: [PATCH 1/6] Add audience advice Add in some audience advice based upon the discussions at the WLCG JWT hackathon. --- profile.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/profile.md b/profile.md index 4ab5d05..96569e3 100644 --- a/profile.md +++ b/profile.md @@ -324,7 +324,22 @@ The contents of the claim may either be a string or URL; we do not currently pro +The `aud` claim provides an explicit statement of the intended audience for the token; it is an important mechanism for restricting the scope of the token to one or more relying parties. Note requiring `aud` is atypical: we believe it is better to have the issuer explicitly state the token may be used by any relying party as opposed to assuming its absence indicates no restrictions. +Relying parties are recommended to accept audiences based on the endpoint name most commonly associated with the provided service. +That is, if a client would want to access the resource `https://wlcg.example.com/base/file.root`, then the recommended audience for the relying party at this endpoint would be: + +``` +https://wlcg.example.com +``` + +The audience SHOULD be normalized according to Section 6 of RFC 3986; that is, trailing slashes are discouraged and default ports should not be included. However, the comparison against the value MUST be done as a case sensitive string as specified in Section 4.1.3 RFC 7519. + +Audiences of this form are preferred (as opposed to a human-readable "site name" such as `WLCG_Site_Foo`) because the user can derive the correct audience from a given URL then determine the correct token to request. + +Note that a given relying party may accept several audiences. For example, a storage server may accept an audience based on a load balanced endpoint it participates in (e.g., `https://redirector.example.com`) in addition to its local hostname (`https://server1.example.com`). + +If the relying party provides a non-HTTPS-based service, a URI should be used. For example, a HTCondor-CE running at `condor.example.com` may use an audience of the form `condor:condor.example.com`. ### ID Token Claims From 1a442006824157d4dddeff824a6afbb691fafd3a Mon Sep 17 00:00:00 2001 From: Brian P Bockelman Date: Wed, 18 Mar 2020 08:07:20 -0500 Subject: [PATCH 2/6] Note in the table we have more guidance below --- profile.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/profile.md b/profile.md index 96569e3..a1d90fb 100644 --- a/profile.md +++ b/profile.md @@ -286,8 +286,7 @@ Usage of this claim is OPTIONAL. However, the wlcg.groups RFC7519 & OpenID Connect core - The aud claim represents the audience or audiences the token is intended for. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string. The special string value of “https://wlcg.cern.ch/jwt/v1/any” signifies that the issuer intends the token to be valid for all relying parties; this string value is required in order to force an issuer to explicitly state the intent that the token is targeted to any relying party. -The contents of the claim may either be a string or URL; we do not currently provide specific guidance on selecting audience names. + The aud claim represents the audience or audiences the token is intended for. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string. The special string value of “https://wlcg.cern.ch/jwt/v1/any” signifies that the issuer intends the token to be valid for all relying parties. See the discussion below for further guidance on picking values for the `aud` claim. Required From eec8746f334faa3ab0af815c0c66a27820adef8a Mon Sep 17 00:00:00 2001 From: Brian P Bockelman Date: Wed, 18 Mar 2020 08:13:42 -0500 Subject: [PATCH 3/6] Improve the HTCondor-CE URI example Given condor.example.com is a hostname here, we should make it part of the URI's authority section. --- profile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/profile.md b/profile.md index a1d90fb..27818b4 100644 --- a/profile.md +++ b/profile.md @@ -338,7 +338,7 @@ Audiences of this form are preferred (as opposed to a human-readable "site name" Note that a given relying party may accept several audiences. For example, a storage server may accept an audience based on a load balanced endpoint it participates in (e.g., `https://redirector.example.com`) in addition to its local hostname (`https://server1.example.com`). -If the relying party provides a non-HTTPS-based service, a URI should be used. For example, a HTCondor-CE running at `condor.example.com` may use an audience of the form `condor:condor.example.com`. +If the relying party provides a non-HTTPS-based service, a URI should be used. For example, a HTCondor-CE running at `condor.example.com` may use an audience of the form `condor://condor.example.com`. ### ID Token Claims From 1c9391af5761ebfa198557221d1846bf0877778b Mon Sep 17 00:00:00 2001 From: Brian P Bockelman Date: Wed, 18 Mar 2020 08:26:24 -0500 Subject: [PATCH 4/6] Try to clarify language about audiences Despite the fact there are cases where one cannot derive the audience from the URL for all redirects (CMS's AAA system is a good counter-example), this should work for all storage system implementations I know of. --- profile.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/profile.md b/profile.md index 27818b4..30b9e23 100644 --- a/profile.md +++ b/profile.md @@ -334,9 +334,9 @@ https://wlcg.example.com The audience SHOULD be normalized according to Section 6 of RFC 3986; that is, trailing slashes are discouraged and default ports should not be included. However, the comparison against the value MUST be done as a case sensitive string as specified in Section 4.1.3 RFC 7519. -Audiences of this form are preferred (as opposed to a human-readable "site name" such as `WLCG_Site_Foo`) because the user can derive the correct audience from a given URL then determine the correct token to request. +Note that a given relying party may accept several audiences. For example, a storage server SHOULD accept an audience based on a load balanced endpoint it participates in (e.g., `https://redirector.example.com`) in addition to its local hostname (`https://server1.example.com`). The user SHOULD NOT need to request a new token for each HTTP redirect within the same logical service. -Note that a given relying party may accept several audiences. For example, a storage server may accept an audience based on a load balanced endpoint it participates in (e.g., `https://redirector.example.com`) in addition to its local hostname (`https://server1.example.com`). +Audiences of this form are preferred (as opposed to a human-readable "site name" such as `WLCG_Site_Foo`) because an end-user can often derive the correct audience from a given URL, allowing them to request an appropriate token. Site names are often community-specific and would require the user to maintain a lookup table from endpoint to audience. If the relying party provides a non-HTTPS-based service, a URI should be used. For example, a HTCondor-CE running at `condor.example.com` may use an audience of the form `condor://condor.example.com`. From 97c87f2e5fc66d5fb53399abbaf91dd3e40bce58 Mon Sep 17 00:00:00 2001 From: Brian P Bockelman Date: Thu, 1 Oct 2020 08:49:24 -0500 Subject: [PATCH 5/6] Update language around services Ensure it's clear additional audiences are acceptable. --- profile.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/profile.md b/profile.md index 30b9e23..f9e54dd 100644 --- a/profile.md +++ b/profile.md @@ -334,9 +334,9 @@ https://wlcg.example.com The audience SHOULD be normalized according to Section 6 of RFC 3986; that is, trailing slashes are discouraged and default ports should not be included. However, the comparison against the value MUST be done as a case sensitive string as specified in Section 4.1.3 RFC 7519. -Note that a given relying party may accept several audiences. For example, a storage server SHOULD accept an audience based on a load balanced endpoint it participates in (e.g., `https://redirector.example.com`) in addition to its local hostname (`https://server1.example.com`). The user SHOULD NOT need to request a new token for each HTTP redirect within the same logical service. +Note that a given relying party may accept several audiences. For example, a storage server SHOULD accept an audience based on a load balanced endpoint it participates in (e.g., `https://redirector.example.com`) in addition to its local hostname (`https://server1.example.com`). The user SHOULD NOT need to request a new token for each HTTP redirect within the same logical service. Implementations may accept additional audiences (if, for example, a single storage system has multiple services and endpoints). -Audiences of this form are preferred (as opposed to a human-readable "site name" such as `WLCG_Site_Foo`) because an end-user can often derive the correct audience from a given URL, allowing them to request an appropriate token. Site names are often community-specific and would require the user to maintain a lookup table from endpoint to audience. +Audiences of this form are preferred (as opposed to a human-readable "site name" such as `WLCG_Site_Foo`) to ease the ability of an end-user or tool to derive an audience from a given URL, allowing them to request an appropriate token. Site names, on the other hand, are often community-specific and would require the user to maintain a lookup table from endpoint to audience. If the relying party provides a non-HTTPS-based service, a URI should be used. For example, a HTCondor-CE running at `condor.example.com` may use an audience of the form `condor://condor.example.com`. From e7eb5e78d09bee235f89edfebe68c63ae2768d79 Mon Sep 17 00:00:00 2001 From: Brian P Bockelman Date: Mon, 12 Oct 2020 08:38:48 -0500 Subject: [PATCH 6/6] Clarify we are simply restating RFC text --- profile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/profile.md b/profile.md index f9e54dd..f3053f6 100644 --- a/profile.md +++ b/profile.md @@ -286,7 +286,7 @@ Usage of this claim is OPTIONAL. However, the wlcg.groups RFC7519 & OpenID Connect core - The aud claim represents the audience or audiences the token is intended for. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string. The special string value of “https://wlcg.cern.ch/jwt/v1/any” signifies that the issuer intends the token to be valid for all relying parties. See the discussion below for further guidance on picking values for the `aud` claim. + The aud claim represents the audience or audiences the token is intended for. In the general case, the aud value is an array of case sensitive strings. As specified in [RFC 7519 section 4.1.3](https://tools.ietf.org/html/rfc7519#section-4.1.3), in the common special case when there is one audience, the aud value MAY be a single case sensitive string. The special string value of “https://wlcg.cern.ch/jwt/v1/any” signifies that the issuer intends the token to be valid for all relying parties. See the discussion below for further guidance on picking values for the `aud` claim. Required