Usage
Installation
To use LabOrchestratorLib-Auth, first install it using pip:
(.venv) $ pip3 install lab-orchestrator-lib-auth
Creating Tokens
To create a JWT token you can use the lab_orchestrator_lib_auth.auth.generate_auth_token(...) function:
- lab_orchestrator_lib_auth.auth.generate_auth_token(user_id, lab_instance_token_params, secret_key, expires_in=3600, expires_at=None, algorithm='HS256')
Generates a JWT token.
- Parameters
lab_instance_token_params (
LabInstanceTokenParams) – The data that is included in the token.secret_key (
str) – The secret key that is used to decrypt the token.expires_in (
int) – Amount of seconds the token is valid.expires_at (
Optional[int]) – Optional UNIX time at which this token expires. Overwrites expires_in.algorithm (
str) – Algorithm that should be used for creating the token. Available algorithms: https://pyjwt.readthedocs.io/en/latest/algorithms.html
- Return type
- Returns
A JWT token.
The user_id parameter should be either of type str or int and contain the id of the user. As decryption HS256 is used, which is a symmetric algorithm. The secret_key parameter contains the symmetric key that is used to encrypt and decrypt the token. The lab_instance_token_params parameter contains the information that are written into the token:
- class lab_orchestrator_lib_auth.auth.LabInstanceTokenParams(lab_id, lab_instance_id, namespace_name, allowed_vmi_names, additional_data=None)
Data that is inserted into the JWT token.
- Parameters
lab_instance_id (
Union[str,int]) – The id of the lab instance.namespace_name (
str) – Name of the namespace the VMs are running into.allowed_vmi_names (
List[str]) – List of VM-names that the user is allowed to access.additional_data (
Optional[Dict[str,Any]]) – Additional data that should be added to the key. The data in this parameter needs to be json serializable.
The allowed_vmi_names parameter is a list of the VM-names the user is allowed to access. So you can use one token for accessing multiple VMs in a lab. The additional_data parameter can be a dictionary of json serialisable data or None. This parameter is used to add more data without always changing the auth library.
For example:
>>> import lab_orchestrator_lib_auth.auth
>>> param = lab_orchestrator_lib_auth.auth.LabInstanceTokenParams(1, 9, "pentest-ubuntu-3-9", ["ubuntu"])
>>> lab_orchestrator_lib_auth.auth.generate_auth_token(5, param, "secret")
'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6NSwiZXhwIjoxNjMyMTM3OTExLjc5NTg1NjcsImxhYl9pbnN0YW5jZSI6eyJsYWJfaWQiOjEsImxhYl9pbnN0YW5jZV9pZCI6OSwibmFtZXNwYWNlX25hbWUiOiJwZW50ZXN0LXVidW50dS0zLTkiLCJhbGxvd2VkX3ZtaV9uYW1lcyI6WyJ1YnVudHUiXX19.ag6f2OsBP5FFyDN9kEw_ivesT8Pa0jGMp2eKjRM9iCs'
To create tokens with asymmetric keys install pyjwt[crypto] and take a look at these two links:
Decoding Tokens
To decode a JWT token you can use the lab_orchestrator_lib_auth.auth.decode_auth_token(...) function:
- lab_orchestrator_lib_auth.auth.decode_auth_token(token, secret_key, algorithms=None)
Decodes a JWT token.
- Parameters
- Return type
- Returns
The data that is contained in the token or None if decode goes wrong.
- Raises
jwt.exceptions.DecodeError – Raised when a token cannot be decoded because it failed validation.
jwt.exceptions.InvalidSignatureError – Raised when a token’s signature doesn’t match the one provided as part of the token.
jwt.exceptions.ExpiredSignatureError – Raised when a token’s exp claim indicates that it has expired.
jwt.exceptions.InvalidAudienceError – Raised when a token’s aud claim does not match one of the expected audience values.
jwt.exceptions.InvalidIssuerError – Raised when a token’s iss claim does not match the expected issuer.
jwt.exceptions.InvalidIssuedAtError – Raised when a token’s iat claim is in the future.
jwt.exceptions.ImmatureSignatureError – Raised when a token’s nbf claim represents a time in the future.
jwt.exceptions.InvalidKeyError – Raised when the specified key is not in the proper format.
jwt.exceptions.InvalidAlgorithmError – Raised when the specified algorithm is not recognized by PyJWT.
jwt.exceptions.MissingRequiredClaimError – Raised when a claim that is required to be present is not contained in the claimset.
This function also uses HS256 as decryption algorithm so you need to have the same secret key as during the creation of a token. This method then returns the data that was inserted into the token.
Verifying Tokens
To verfiy a JWT token you can use the lab_orchestrator_lib_auth.auth.verify_auth_token(...) function:
- lab_orchestrator_lib_auth.auth.verify_auth_token(token, vmi_name, secret_key, algorithms=None)
Decodes a token and verifies if it’s valid.
Checks if the vmi_name is allowed in the token.
- Parameters
- Return type
- Returns
The result of the verification as a boolean and the data contained in the token.
- Raises
jwt.exceptions.DecodeError – Raised when a token cannot be decoded because it failed validation.
jwt.exceptions.InvalidSignatureError – Raised when a token’s signature doesn’t match the one provided as part of the token.
jwt.exceptions.ExpiredSignatureError – Raised when a token’s exp claim indicates that it has expired.
jwt.exceptions.InvalidAudienceError – Raised when a token’s aud claim does not match one of the expected audience values.
jwt.exceptions.InvalidIssuerError – Raised when a token’s iss claim does not match the expected issuer.
jwt.exceptions.InvalidIssuedAtError – Raised when a token’s iat claim is in the future.
jwt.exceptions.ImmatureSignatureError – Raised when a token’s nbf claim represents a time in the future.
jwt.exceptions.InvalidKeyError – Raised when the specified key is not in the proper format.
jwt.exceptions.InvalidAlgorithmError – Raised when the specified algorithm is not recognized by PyJWT.
jwt.exceptions.MissingRequiredClaimError – Raised when a claim that is required to be present is not contained in the claimset.
This function checks if the given vmi_name is allowed in the token.
Exceptions
- exception jwt.exceptions.InvalidTokenError
Bases:
jwt.exceptions.PyJWTError
- exception jwt.exceptions.DecodeError
- exception jwt.exceptions.InvalidSignatureError
Bases:
jwt.exceptions.DecodeError
- exception jwt.exceptions.ExpiredSignatureError
- exception jwt.exceptions.InvalidAudienceError
- exception jwt.exceptions.InvalidIssuerError
- exception jwt.exceptions.InvalidIssuedAtError
- exception jwt.exceptions.ImmatureSignatureError
- exception jwt.exceptions.InvalidKeyError
Bases:
jwt.exceptions.PyJWTError
- exception jwt.exceptions.InvalidAlgorithmError
- exception jwt.exceptions.MissingRequiredClaimError(claim)
- exception jwt.exceptions.PyJWKError
Bases:
jwt.exceptions.PyJWTError
- exception jwt.exceptions.PyJWKSetError
Bases:
jwt.exceptions.PyJWTError
- exception jwt.exceptions.PyJWKClientError
Bases:
jwt.exceptions.PyJWTError