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)

Generates a JWT token.

Parameters

  • user_id (Union[str, int]) – Id of the user.

  • 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.

Return type

str

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.

Parameters

  • lab_id (Union[str, int]) – The id of the lab.

  • 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.

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

  • token (str) – The token to decode.

  • secret_key (str) – Key that should be used to decrypt the token.

Return type

Optional[LabInstanceTokenParams]

Returns

The data that is contained in the token or None if decode goes wrong.

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

  • token (str) – The token to decode and verify.

  • vmi_name (str) – The vmi_name the user wants to use.

  • secret_key (str) – Key that is used to decrypt the token.

Return type

Optional[LabInstanceTokenParams]

Returns

The data that is contained in the token or None if the the token or vmi name was invalid or not allowed.

This function checks if the given vmi_name is allowed in the token.