Token and Authorization docs #2773
Conversation
I did this while I was working on docs for the tool. Adding the SilenceUsage option to cobra prevents the command from dumping all the options/flags/usage info in the event of an error. I prefer this because most errors the command produces don't warrant spamming people with all this info.
This documentation is meant to live at the level of "how can I as a user get protected data", not how an extensive explanation of how the Pelican token ecosystem works or how Origin admins can set up their services with OAuth2 providers. I plan to write a more extensive "how tokens in Pelican" work page in the "Advanced" section, and this commit is a checkpoint while I work toward that. As such, I already link to that page (which I have sketched out locally).
|
For the reviewers, please think carefully about the content of what I'm saying, especially in the "advanced" section -- while I used some AI to help with formatting and clarity, 99% of the content first traveled through my fingers. I likely made mistakes! In particular, it'd be useful for others to think about the descriptions/diagrams in the section about establishing trust, which turned out to be pretty tricky and I'm not totally sure I got it right. I also highly recommend you actually build these docs to see formatting, double check my links, etc. I tried to double check everything before requesting a review, but there's a lot of content and I'm becoming blind to it because of how long I've been staring at it... |
|
I should also note that these docs still aren't a complete "everything auth in Pelican" -- I'm punting on things like "how to set up the built-in issuer". I think some of those topics can/should be added in a followup PR. |
aowen-uwmad
left a comment
aowen-uwmad
left a comment
There was a problem hiding this comment.
Some writing feedback. Did not investigate the technical details; someone else should confirm those before approving.
| 3. **Signature:** The cryptographic proof that ensures the token was created by the right issuer and hasn't been altered. Signatures do not decode to JSON | ||
|
|
||
| <Callout type="example"> | ||
| Below are JSON objects that represent an example JWT header and payload: |
There was a problem hiding this comment.
| Below are JSON objects that represent an example JWT header and payload: | |
| Below are JSON objects that represent an example JWT **header** and **payload**: |
| <Callout type="default"> | ||
| You can safely share the first two sections (everything **up to but not after** the second period) of your tokens because they don't contain secrets. | ||
| However, you should be ***extremely careful*** about sharing token signatures and you should treat this like sharing a password. | ||
| </Callout> |
There was a problem hiding this comment.
| <Callout type="default"> | |
| You can safely share the first two sections (everything **up to but not after** the second period) of your tokens because they don't contain secrets. | |
| However, you should be ***extremely careful*** about sharing token signatures and you should treat this like sharing a password. | |
| </Callout> | |
| <Callout type="danger"> | |
| You should be ***extremely careful*** about sharing token signatures and you should treat this like sharing a password!! | |
| You can safely share the first two sections (everything **up to but not after** the second period) of your tokens because they don't contain secrets. | |
| </Callout> |
The callout should be something like "danger" (I don't know what the available options are; something stronger than "warning").
|
|
||
| While discussing what tokens are and how they work, it's been unavoidable to briefly discuss the concept of *issuers*, but up until now we haven't rigorously explained what issuers are and why it's difficult to precisely describe them. | ||
|
|
||
| At its simplest, an **Issuer** is the authority that creates/mints, signs, and provides means to validate tokens. |
There was a problem hiding this comment.
| At its simplest, an **Issuer** is the authority that creates/mints, signs, and provides means to validate tokens. | |
| At its simplest, an **Issuer** is the authority that creates (or "mints"), signs, and provides means to validate tokens. |
|
|
||
| This is the private, secure side of the issuer. | ||
| Before a user can get a token, they must prove who they are to an identity provider. | ||
| Once that provider validates the user's identity, it passes *identifiers* to the "Mint Issuer" like which groups the user belongs to. |
There was a problem hiding this comment.
| Once that provider validates the user's identity, it passes *identifiers* to the "Mint Issuer" like which groups the user belongs to. | |
| Once that provider validates the user's identity, it passes *identifiers* to the "Mint Issuer", such as which groups the user belongs to. |
| The actual token that is _does_ create is the intersection of what the issuer is willing to create and what the user is asking for. | ||
| </Callout> | ||
|
|
||
| In Pelican, the "Mint Issuer" is often a service called [OA4MP (OAuth for Many People)](https://oa4mp.org/) built into the Origin. |
There was a problem hiding this comment.
| In Pelican, the "Mint Issuer" is often a service called [OA4MP (OAuth for Many People)](https://oa4mp.org/) built into the Origin. | |
| In Pelican, the "Mint Issuer" is often a service called [OA4MP (OAuth for Many People)](https://oa4mp.org/), which is built into the Origin. |
| Additionally, these generated configuration files may be merged with admin-supplied files by specifying the [`Xrootd.Authfile`](../parameters#Xrootd-Authfile) and [`Xrootd.ScitokensConfig`](../parameters#Xrootd-ScitokensConfig) config parameters. | ||
|
|
||
| <Callout type="warning"> | ||
| Any extra information provided in custom authfile or SciTokens configuration ***does not*** propagate through the rest of the federation. | ||
| Moreover, improper configuration can result in ***unintentional data exposure***. | ||
| Use these at your own risk! | ||
|
|
||
| If you're setting up an Origin to serve protected data and you can use tokens to download directly via the Origin but not via Caches, double check that you're not relying on admin-supplied authfile/SciTokens configuration! | ||
| </Callout> |
There was a problem hiding this comment.
Given the warning, I think we should move the the config options text into the callout itself.
Perhaps a nested callout? (This text in the outer info level callout, and the existing callout inside). I don't know if that is even possible..
| ```text | ||
| u * /my-prefix lr /my-prefix-auth -lr | ||
| ``` | ||
| </Callout> |
There was a problem hiding this comment.
I don't know if this is a practical suggestion.
| </Callout> | |
| One way to ensure that expanded privileges are not granted by accident is to make sure that the more restrictive policies are placed earlier in the configuration than the more open policies. | |
| </Callout> |
|
|
||
| <Callout type="warning"> | ||
| The content in this page is outdated and describes use of a deprecated command line tool. | ||
| For modern guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". |
There was a problem hiding this comment.
| For modern guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". | |
| For updated guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". |
| ## Pelican CLI | ||
| <Callout type="warning"> | ||
| The content in this section is outdated and describes use of a deprecated command line tool. | ||
| For modern guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". |
There was a problem hiding this comment.
| For modern guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". | |
| For updated guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". |
| ### Additional Command Line Arguments | ||
| <Callout type="warning"> | ||
| The content in this section is outdated and describes use of a deprecated command line tool. | ||
| For modern guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". |
There was a problem hiding this comment.
| For modern guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". | |
| For updated guidelines describing token generation, see "[Getting Data with Pelcian/Working with Protected Data](../../getting-data-with-pelican/auth)". |
|
This probably deserves a conversation in the proverbial hallway (rather than me trying to type an essay into GitHub), but the reason our story for "issuers" is a mess is because it invents terminology where it doesn't need to.
After looking at some RFCs, in the context of Pelican, I think this is what I'd start with: An "issuer" is an identifier for an authorization server, in the sense of OAuth2, that supports metadata discovery. Pelican expects this metadata to include a URL to the signing key(s) for validating tokens issued by the authorization server. Depending on the authorization server's configuration, as conveyed in its metadata, Pelican may be able to use standard OAuth2 flows to obtain access tokens from the authorization server. An "issuer" doesn't do anything, because identifiers don't do anything. They just are. The active thing is an "authorization server." It is the thing that creates and signs tokens. To do this, sometimes, it hands a key over to a third party it trusts and has the third party create JWTs in its name. Sometimes, it publishes a collection of endpoints for an OAuth2 flow. |
4 participants
A few notes about this: