scitokens Package

scitokens Package

Module for creating and using SciTokens.

scitokens Module

SciTokens reference library.

This library provides the primitives necessary for working with SciTokens authorization tokens.

exception scitokens.scitokens.ClaimInvalid[source]

Bases: ValidationFailure

The Validator object attempted validation of a given claim, but one of the callbacks marked the claim as invalid.

exception scitokens.scitokens.EnforcementError[source]

Bases: Exception

A generic error during the enforcement of a SciToken.

class scitokens.scitokens.Enforcer(issuer, audience=None)[source]

Bases: object

Enforce SciTokens-specific validation logic.

Allows one to test if a given token has a particular authorization.

This class is NOT thread safe; a separate object is needed for every thread.

add_validator(claim, validator)[source]

Add a user-defined validator in addition to the default enforcer logic.

generate_acls(token)[source]

Given a SciToken object and the expected issuer, return the valid ACLs.

test(token, authz, path=None)[source]

Test whether a given token has the requested permission within the current enforcer context.

exception scitokens.scitokens.InvalidAuthorizationResource[source]

Bases: EnforcementError

A scope was encountered with an invalid authorization.

Examples include:
  • Authorizations that require paths (read, write) but none were included.

  • Scopes that include relative paths (read:~/foo)

exception scitokens.scitokens.InvalidPathError[source]

Bases: EnforcementError

An invalid test path was provided to the Enforcer object.

Test paths must be absolute paths (start with ‘/’)

exception scitokens.scitokens.MissingClaims[source]

Bases: ValidationFailure

Validation failed because one or more claim marked as critical is missing from the token.

exception scitokens.scitokens.NoRegisteredValidator[source]

Bases: ValidationFailure

The Validator object attempted validation of a token, but encountered a claim with no registered validator.

class scitokens.scitokens.SciToken(key=None, algorithm=None, key_id=None, parent=None, claims=None)[source]

Bases: object

An object representing the contents of a SciToken.

claims()[source]

Return an iterator of (key, value) pairs of claims, starting with the claims from the first token in the chain.

clone_chain()[source]

Return a new, empty SciToken

static deserialize(serialized_token, audience=None, require_key=False, insecure=False, public_key=None)[source]

Given a serialized SciToken, load it into a SciTokens object.

Verifies the claims pass the current set of validation scripts.

Parameters:
  • serialized_token (str) – The serialized token.

  • audience (str) – (Legacy, not checked) The audience URI that this principle is claiming. Default: None. Audience is not checked no matter the value.

  • require_key (bool) – When True, require the key

  • insecure (bool) – When True, allow insecure methods to verify the issuer, including allowing “localhost” issuer (useful in testing). Default=False

  • public_key (str) – A PEM formatted public key string to be used to validate the token

static discover(audience=None, require_key=False, insecure=False, public_key=None)[source]

Create a SciToken by looking for a token with WLCG Bearer Token Discovery protocol

https://github.com/WLCG-AuthZ-WG/bearer-token-discovery/blob/master/specification.md

The serialized token is read in and passed to the deserialize() method to load it into a SciTokens object. Raises IOError is a token cannot be found or the errors of SciTokens.deserialize() if there is an error reading the discovered token.

Parameters:
  • audience (str) – The audience URI that this principle is claiming. Default: None

  • require_key (bool) – When True, require the key

  • insecure (bool) – When True, allow insecure methods to verify the issuer, including allowing “localhost” issuer (useful in testing). Default=False

  • public_key (str) – A PEM formatted public key string to be used to validate the token

get(claim, default=None, verified_only=False)[source]

Return the value associated with a claim, returning the default if the claim is not present. If verified_only is True, then a claim is returned only if it is in the verified claims

serialize(include_key=False, issuer=None, lifetime=600)[source]

Serialize the existing SciToken.

Parameters:
Return bytes:

base64 encoded token

update_claims(claims)[source]

Add new claims to the token.

Parameters:

claims – Dictionary of claims to add to the token

verify()[source]

Verify the claims of the in-memory token.

Automatically called by deserialize.

exception scitokens.scitokens.ValidationFailure[source]

Bases: Exception

Validation of a token was attempted but failed for an unknown reason.

class scitokens.scitokens.Validator[source]

Bases: object

Validate the contents of a SciToken.

Given a SciToken, validate the contents of its claims. Unlike verification, which checks that the token is correctly signed, validation provides an easy-to-use interface that ensures the claims in the token are understood by the user.

add_validator(claim, validate_op)[source]

Add a validation callback for a given claim. When the given claim encountered in a token, validate_op object will be called with the following signature:

>>> validate_op(value)

where value is the value of the token’s claim converted to a python object.

The validator should return True if the value is acceptable and False otherwise.

validate(token, critical_claims=None)[source]

Validate the claims of a token.

This will iterate through all claims in the given SciToken and determine whether all claims a valid, given the current set of validators.

If critical_claims is specified, then validation will fail if one or more claim in this list is not present in the token.

This will throw an exception if the token is invalid and return True if the token is valid.

scitokens.config Module

Module for configuration management

scitokens.utils.config.get(key, default=None)[source]

Get the configuration value for key

Parameters:

key (str) – The key in the configuration to retreive

Returns:

The value in the configuration, or the default

scitokens.utils.config.get_int(key, default=None)[source]

Get an integer from the configuration.

Parameters:

key (str) – The key in the configuration to retreive

Returns:

The value in the configuration, or the default

scitokens.utils.config.set_config(config=None)[source]

Set the configuration of SciTokens library

Parameters:

config – config may be: A full path to a ini configuration file, a ConfigParser instance, or None, which will use all defaults.