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=600, expires_at=None)
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.
- 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)
Data that is inserted into the JWT token.
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.
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'
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)
Decodes a JWT token.
- Parameters
- Return type
- Returns
The data that is contained in the token or None if decode goes wrong.
- Raise
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)
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
- Raise
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.