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.
- 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.
- 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:
include_key (bool) – When true, include the public key to the serialized token. Default=False
issuer (str) – A string indicating the issuer for the token. It should be an HTTPS address, as specified in https://tools.ietf.org/html/draft-ietf-oauth-discovery-07
lifetime (int) – Number of seconds that the token should be valid
- Return bytes:
base64 encoded token
- 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 andFalse
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