api_jwt source docs

class api_jwt.APIJwt(public_keys=None, private_key=None, ttl=None, **kwargs)

Bases: object

Main class to represent a JWT used for API purposes. The internal structure of the JWT is set when the class is instantiated. This structure will be used for encode/decode operations. If no parameters are supplied, the defaults are used. If no certificate or key is supplied, a dummy test pair is used, causing a log warning.

For the extras parameter (kwargs): An extras key that is set to None will be pruned from the JWT. With no extras set, these default extras will be included. Default extras:

extras = {
    'level': 0.0,  # Authentication level, allowed['levels'] specifies the valid levels
    'factor': '',  # Authentication factor used, e.g. password, otp, etc
    'target': '',  # Target id for scopes
    'dnt': 0,      # Do Not Track
    'scopes': [],  # Scopes this token gives access to
}

For the allowed parameter (kwargs): The allowed dict defines the valid values for each of the extras. If a new extra is to be used, a new key with valid paramters should also be included. The ‘keys’ and ‘scopes’ keys are special:

allowed = {
    'keys': {
        'user': 'auth_user',
        'admin': 'auth_admin'
    },
    'level': [
        0.0,  # Level 0, no authentication
        1.0,  # Externally authenticated
        2.0,  # Password/single-factor
        3.0,  # Multi-factor
        4.0   # Certificate-level
    ],
    'dnt': [
        0,  # or not set - normal user
        1,  # reservation - don't track this user
        2,  # not anonymous - don't track and don't store data anonymously
        3   # Test user - this is a test user, don't skew metrics
    ],
    'scopes': {
        'PER_KEY': {  # Use single key with 'PER_KEY' to set allowed values based on key
            'user': ['user:all'],
            'admin': ['admin:all']
        }
    }
}

Parameters:

• public_keys – Single string or list of strings with public pem keys for signing verification
• private_key – Single string with pem key for
• ttl – Default time to live in seconds for the encoded JWT (can be overridden in encode())
• extras – A dict with non-mandatory JWT parameters that will be included in the encoded JWT.
• allowed – A dict with allowed values for keys and scopes and for the extras

add_public_keys(keys=None)

Add more public keys to the list of keys used to validate JWT signature

Parameters:keys – Single or list of keys (no json allowed)

decode(token=None)

Decode a token, properties is_valid, is_bad, an is_expired will be set. All tokens are verified against the list of public keys

Parameters:token – JWT token to decode Returns:Either None if doken was not successfully decoded or a dict with the payload

encode(subject=None, key='user', exp=None, **kwargs)

Encode the token with subject as the identity this token concerns (sub), using key to identify the key type (used by some gateways like kong in the iss parameter) and with exp (or default) expiry in seconds. Additional key/value pairs will be validated against extras and the values of each against allowed. If an extra does not have a key in allowed, any value except None will be included in the token payload.

Use kwargs, extras={} or allowed={}, as short-cuts to calling set_allowed() and set_extras() before encode(), i.e. do everything at once in the encode() call.

Parameters:

• subject – id of the subject of this token
• key – a valid key from _allowed[‘keys’], typically used in iss to match key on external system
• exp – expiry time in seconds
• kwargs – key/value pairs to include in the payload.

Returns:

None if not successfully encoded JWT token

expiry

Expiry date of the token

Returns:Expiry timestamp for token Return type:datetime

is_bad

Set if decoded a token and token contained errors

Returns:Bad token or not Return type:bool

is_expired

Set if decoded a token and token was expired :return: Expired token or not :rtype: bool

is_valid

Set if decoded a token and contains True if token is valid

Returns:whether token is valid or not Return type:bool

jwt

Contains the jwt token

Returns:JWT token Return type:string

override_keys(public_keys=None, private_key=None)

Override the public and private keys ‘on the fly’. Preferred method is at instantiation

Parameters:

• public_keys – list or json list of keys, or single public key for decoding
• private_key – private key for encoding

reset_keys()

Reset back the keys to the dummy keys (both public and private)

set_allowed(key, values)

Set allowed values for the extras in the payload

Parameters:

• key – Payload name
• values – Dict for keys and scopes, list for other extras

set_extras(key, default)

Set extra allowed payload parameters for encoded tokens

Parameters:

• key – Payload key name
• default – Default value, None if it should be pruned from jwt if not set

user

Contains the entire payload of a decoded token

Returns:payload Return type:dict