Generating Tokens for Accessing Protected Objects

To access a protected object via a Pelican data federation, the client must present a token signed by the Origin where the object is hosted on. The token then is used by Pelican servers to verify the object access permissions granted to the user, along with other security checks to ensure the token is valid and not tampered by malicious attackers. Pelican takes advantage of JSON Web Token (JWT) to embed permission, user and server identity to the token.

To allow user access the protected objects, the token must be generated by the Pelican Origin using its private key. Pelican Origin can be configured to use a third-party OIDC token issuer, in which case the client will be prompted to get a token from the issuer. By default, however, the Pelican Origin needs to generate the token by its built-in issuer and pass it to the client. This page documents different ways to generate the token to access the protected objects.

Pelican CLI

The Pelican binary comes with a command pelican origin token create to generate the token. To generate a valid token, this command MUST be run on the same server where the Pelican Origin hosting the target object runs. On the Origin server, run:

pelican origin token create \
    --scope "storage.read:/" \
    --issuer https://localhost:8443 \
    --claim "wlcg.ver=1.0" \
    --subject origin \
    --audience https://wlcg.cern.ch/jwt/v1/any

where:

• --scope defines the access permission of the token. It follows WLCG claim semantics (opens in a new tab). There are three scopes that are most frequently used:

  • storage.read: Read data.
  • storage.create: Upload data. This capability includes the creation of directories and subdirectories at the specified path, and the creation of any non-existent directories required to create the path itself. This authorization does not permit overwriting or deletion of stored data.
  • storage.modify: Change the data, including creating new files and writing data. This permission includes overwriting or replacing stored data in addition to deleting or truncating data. This is a strict superset of storage.create.

  One can control the fine-grained permission based on object prefixes by appending the allowed path to the scope. For example, a storage.read:/foo/bar scope only has read access to the /foo/bar path and the child paths.

  In this example, the token has read permission to the / prefix, meaning it can be used to read any objects on this Origin.

  For other scope options, refer to WLCG GitHub website (opens in a new tab).

• --issuer tells Pelican the issuer URL it should embed in the token, which will be used by other Pelican servers to verify the integrity of the token. The issuer should be the publicly accessible URL of the Origin server. The port number should also be included if the issuer URL contains a port number other than 443.

• --claim encodes an additional JWT claim, wlcg.ver with value 1.0 to the token. wlcg.ver is a special claim to indicate the version of the token profile. Pelican Origin accepts both SciToken token profile and WLCG token profile. Here we set the token profile to WLCG. See details here (opens in a new tab).

• --subject encodes the entity that issues the token.

• --audience encodes the entities who requested the token. In most of cases, Pelican uses the special any audience.

Additional Command Line Arguments

• --private-key encodes the path to the private key used to sign the token. By default it uses the private key defined by the Origin server that the command runs on.
• --lifetime encodes the duration in seconds where the token is valid. By default it's 1200 seconds, or 20 minutes.