16.2.1.6. Container Functions¶

This module contains all top level container functions.

This is the layer between the API and the database

privacyidea.lib.container.add_container_info(serial: str, ikey: str, ivalue) → bool[source]¶

Add the given info to the container with the given serial. If the key already exists, the value is updated. However, if the entry is of type PI_INTERNAL, the value can not be modified.

Parameters:

serial – The serial of the container
ikey – The info key
ivalue – The info value

Returns:

True on success

privacyidea.lib.container.add_container_realms(serial: str, realms: list[str], allowed_realms: list[str] | None) → dict[str, bool][source]¶

Add the realms to the container realms.

Parameters:

serial – serial of the container
realms – new realms as list of str
allowed_realms – A list of realms the admin is allowed to set, optional

Returns:

Dictionary in the format {realm: success}, the entry ‘deleted’ indicates whether existing realms were deleted.

privacyidea.lib.container.add_container_states(serial: str, states: list[str]) → dict[str, bool][source]¶

Add the states to a container.

Parameters:

serial – serial of the container
states – additional states as list of str

Returns:

Dictionary in the format {state: success}

privacyidea.lib.container.add_multiple_tokens_to_container(container_serial: str, token_serials: list) → dict[str, bool][source]¶

Add the given tokens to the container with the given serial. Raises a ResourceNotFoundError if the container does not exist. If a token is already in a container it is removed from the old container.

Parameters:

container_serial – The serial of the container
token_serials – A list of token serials to add

Returns:

A dictionary in the format {<token_serial>: <success>}

privacyidea.lib.container.add_not_authorized_tokens_result(result: dict, not_authorized_serials: list) → dict[str, bool][source]¶

Add the result False for all tokens the user is not authorized to manage.

Parameters:

result – The result dictionary in the format {token_serial: success}
not_authorized_serials – A list of token serials the user is not authorized to manage

Returns:

The result dictionary with the not authorized tokens added like {<token_serial>: False}

privacyidea.lib.container.add_token_to_container(container_serial: str, token_serial: str) → bool[source]¶

Add a single token to a container. If a token is already in a container it is removed from the old container. Raises a ResourceNotFoundError if either the container or token does not exist.

Parameters:

container_serial – The serial of the container
token_serial – The serial of the token

Returns:

True on success

privacyidea.lib.container.assign_user(serial: str, user: User) → bool[source]¶

Assign a user to a container.

Parameters:

serial – container serial
user – user to assign to the container

Returns:

True on success, False otherwise

privacyidea.lib.container.check_container_challenge(transaction_id: str) → dict[source]¶

Check if the challenge for the given transaction_id belongs to a container. If this is the case it checks if the challenge is valid and was already answered. Then it deletes the challenge and returns a successful authentication response. This function is used as last step during enroll via multi challenge.

Parameters:

transaction_id – The transaction ID of the challenge

Returns:

A dictionary with the success state and details of the authentication in the format

{
"success": True,
"details": {"serial": "CONT0001", "message": "Found matching challenge"}
}

privacyidea.lib.container.compare_template_dicts(template_a: dict, template_b: dict) → bool[source]¶

Compares two template dictionaries for equal tokens.

Parameters:

template_a – The first template dictionary
template_b – The second template dictionary

Returns:

True if the templates contain the same tokens, False otherwise.

privacyidea.lib.container.compare_template_with_container(template: ContainerTemplateBase, container: TokenContainerClass) → dict[source]¶

Compares the template with the container. It is only evaluated if the token types are equal.

Parameters:

template – The template object
container – The container object

Returns:

A dictionary with the differences between the template and the container

Example of a returned dictionary:

{
    "tokens": {
                "missing": ["hotp"],
                "additional": ["totp"]
                }
}

privacyidea.lib.container.create_container_dict(container_list: list[TokenContainerClass], no_token: bool = False, user: User = None, logged_in_user_role: str = 'user', allowed_token_realms: list[str] | None = [], hide_token_info: list[str] = None, hide_container_info: list[str] = None) → list[dict][source]¶

Create a dictionary for each container in the list. It contains the container properties, owners, realms, tokens and info. The information is only provided if the user is allowed to see it.

Parameters:

container_list – List of container objects
no_token – If True, the token information is not included
user – The user object requesting the containers
logged_in_user_role – The role of the logged-in user (‘admin’ or ‘user’)
allowed_token_realms – A list of realms the admin is allowed to see tokens from
hide_token_info – List of token info keys to hide in the response, optional
hide_container_info – List of container info keys to hide in the response, optional

Returns:

List of container dictionaries

Example of a returned list:

[
    {
        "type": "generic",
        "serial": "CONT0001",
        "description": "Container description",
        "last_authentication": "2021-06-01T12:00:00+00:00",
        "last_synchronization": "2021-06-01T12:00:00+00:00",
        "states": ["active"],
        "users": [
            {
                "user_name": "user1",
                "user_realm": "realm1",
                "user_resolver": "resolver1",
                "user_id": 1
            }
            ],
        "tokens": [
            {
                "serial": "TOTP0001",
                "type": "totp",
                "active": true,
                ...
            }],
        "info": {"hash_algorithm": "SHA256", ...},
        "internal_info_keys": ["hash_algorithm"],
        "realms": ["realm1", "realm2"],
        "template": "template1"
    }, ...
]

privacyidea.lib.container.create_container_from_db_object(db_container: TokenContainer) → TokenContainerClass | None[source]¶

Create a TokenContainerClass object from the given db object.

Parameters:: db_container – The db object to create the container from
Returns:: The created container object or None if the container type is not supported

privacyidea.lib.container.create_container_template(container_type: str, template_name: str, options: dict, default: bool = False) → int[source]¶

Create a new container template.

Parameters:

container_type – The type of the container
template_name – The name of the template
options – The options for the template as dictionary
default – If True, the template is set as default, optional

Example for the options dictionary:

{
    "tokens": [{"type": "hotp", "genkey": True, "hashlib": "sha256"}, ...]
}

Returns:: ID of the created template

privacyidea.lib.container.create_container_template_from_db_object(db_template: TokenContainerTemplate) → ContainerTemplateBase | None[source]¶

Create a TokenContainerTemplate object from the given db object.

Parameters:: db_template – The DB object to create the container template from
Returns:: The created container template object or None if the container template type is not supported

privacyidea.lib.container.create_container_tokens_from_template(container_serial: str, template_tokens: list, request, user_role: str) → dict[str, dict][source]¶

Create tokens for the container from the given template. The token policies are checked and the enroll information is read from the policies for each token. The tokens owner and the enroll information are added to the request object to check the corresponding policies. All errors are caught and logged to be able to create the remaining tokens.

Parameters:

container_serial – The serial of the container
template_tokens – The template to create the tokens from as list of dictionaries where each dictionary contains the details for a token to be enrolled
request – The request object
user_role – The role of the user (‘admin’ or ‘user’)

Returns:

A dictionary containing the enroll details for each created token in the format:

{
    <token_serial>: {"serial": <token_serial>,
                     "type": <token_type>,
                     "init_params": <params used for the enrollment>, ...},
}

privacyidea.lib.container.create_endpoint_url(base_url: str, endpoint: str) → str[source]¶

Creates the url for an endpoint. It concat the base_url and the endpoint if the endpoint is not already in the base_url. base_url and endpoint are separated by a slash.

Parameters:

base_url – The base url of the host
endpoint – The endpoint

Returns:

The url for the endpoint

Return type:

str

privacyidea.lib.container.create_pagination(page: int, pagesize: int, sql_query: Query, object_list_key: str) → dict[str, int | None | list[any]][source]¶

Creates the pagination of a sql query.

Parameters:

page – The number of the page to view. Starts with 1
pagesize – The number of objects that shall be shown on one page
sql_query – The sql query to paginate
object_list_key – The key used in the return dictionary for the list of objects

Returns:

A dictionary with pagination information and a list of database objects

privacyidea.lib.container.delete_container_by_id(container_id: int) → int[source]¶

Delete the container with the given id. If it does not exist, raises a ResourceNotFoundError.

Parameters:: container_id – The id of the container to delete
Returns:: ID of the deleted container on success

privacyidea.lib.container.delete_container_by_serial(serial: str) → int[source]¶

Delete the container with the given serial. If it does not exist, raises a ResourceNotFoundError.

Parameters:: serial – The serial of the container to delete
Returns:: ID of the deleted container on success

privacyidea.lib.container.delete_container_info(serial: str, ikey: str = None) → dict[str, bool][source]¶

Delete the info of the given key or all infos if no key is given. Internal infos are not deleted

Parameters:

serial – The serial of the container
ikey – The info key or None to delete all info keys

Returns:

Dictionary with all info keys or only ikey if given and the value True on success, False otherwise

privacyidea.lib.container.finalize_container_rollover(container: TokenContainerClass)[source]¶

Finalize the rollover of a container. For each token in the container a rollover is performed. All previous challenges are deleted.

Parameters:: container – The container object

privacyidea.lib.container.finalize_registration(container_serial: str, params: dict) → dict[source]¶

Finalize the registration of a container if the challenge response is valid. If the container is in the registration_state rollover, it finalizes the container rollover.

Parameters:

container_serial – The serial of the container
params – The parameters for the registration as dictionary

Returns:

dictionary with container specific information

privacyidea.lib.container.find_container_by_id(container_id: int) → TokenContainerClass[source]¶

Returns the TokenContainerClass object for the given container id or raises a ResourceNotFoundError.

Parameters:: container_id – ID of the container
Returns:: container object

privacyidea.lib.container.find_container_by_serial(serial: str) → TokenContainerClass[source]¶

Returns the TokenContainerClass object for the given container serial or raises a ResourceNotFoundError.

Parameters:: serial – Serial of the container
Returns:: container object
Return type:: privacyidea.lib.containerclass.TokenContainerClass

privacyidea.lib.container.find_container_for_token(serial: str) → TokenContainerClass[source]¶

Returns a TokenContainerClass object for the given token or raises a ResourceNotFoundError if the token does not exist.

Parameters:: serial – Serial of the token
Returns:: container object or None if the token is not in a container

privacyidea.lib.container.get_all_containers(user: User = None, serial: str = None, ctype: str = None, token_serial: str = None, realm: str = None, allowed_realms: list[str] = None, sortby: str = 'serial', sortdir: str = 'asc', template: str = None, description: str = None, assigned: bool = None, resolver: str = None, info: dict = None, last_auth_delta: str = None, last_sync_delta: str = None, state: str = None, page: int = 0, pagesize: int = 0) → dict[str, int | None | list[TokenContainerClass]][source]¶

This function is used to retrieve a container list, that can be displayed in the Web UI. It supports pagination if either page or pagesize is given (e.g. >0). Each retrieved page will also contain a “next” and a “prev”, indicating the next or previous page. If page and pagesize are both smaller than 0, no pagination is used. The containers are filtered by the given parameters.

Parameters:

user – container owner, optional
serial – container serial (case-insensitive and allows ‘*’ as wildcard), optional
ctype – container type (case-insensitive and allows ‘*’ as wildcard), optional
token_serial – serial of a token which is assigned to the container (case-insensitive and allows ‘*’ as wildcard), optional
realm – name of the realm the container is assigned to (case-insensitive and allows ‘*’ as wildcard), optional
allowed_realms – list of realms the user is allowed to see (None if all realms are allowed), optional If realms and allowed_realms are given, the intersection of both lists is used. If there is no intersection, no container is returned.
template – The name of the template the container was created with (case-sensitive and allows ‘*’ as wildcard) , optional
description – The description of the container (case-insensitive and allows ‘*’ as wildcard), optional
assigned – True if the container is assigned to a user, False otherwise, optional
resolver – The resolver of the user (case-insensitive and allows ‘*’ as wildcard), optional
info – The info dictionary in the format {key: value} of length 1, optional Both key and value can contain ‘*’ as wildcard. key is case-sensitive, value is case-insensitive.
last_auth_delta – The maximum time difference the last authentication may have to now, e.g. “1y”, “14d”, “1h” The following units are supported: y (years), d (days), h (hours), m (minutes), s (seconds)
last_sync_delta – The maximum time difference the last synchronization may have to now, e.g. “1y”, “14d”, “1h” The following units are supported: y (years), d (days), h (hours), m (minutes), s (seconds)
state – State the container should have (case-insensitive and allows “*” as wildcard), optional
sortby – column to sort by, default is the container serial
sortdir – sort direction, default is ascending
page – The number of the page to view. Starts with 1 ;-)
pagesize – The size of the page

Returns:

A dictionary with a list of containers at the key ‘containers’ and optionally pagination entries (‘prev’, ‘next’, ‘current’, ‘count’)

privacyidea.lib.container.get_all_templates_with_type()[source]¶: Returns a list of display strings containing the name and type of all templates.

privacyidea.lib.container.get_container_classes() → dict[str, type[TokenContainerClass]][source]¶: Returns a dictionary of all available container classes in the format: { type: class }. New container types have to be added here.

privacyidea.lib.container.get_container_classes_descriptions() → dict[str, str][source]¶: Returns a dictionary of {“type”: “Type: description”} entries for all container types. Used to list the container types.

privacyidea.lib.container.get_container_generator(pagesize: int = 10, **kwargs) → Generator[list[TokenContainerClass], None, None][source]¶

Generator that yields pages of containers.

Parameters:

page_size – Number of containers per page
kwargs – Filter arguments for get_all_containers

Yield:

List of TokenContainerClass objects for each page

privacyidea.lib.container.get_container_info_dict(serial: str, ikey: str = None) → dict[str, str | None][source]¶

Returns the info of the given key or all infos if no key is given for the container with the given serial.

Parameters:

serial – The serial of the container
ikey – The info key or None to get all info keys

Returns:

The info dict

privacyidea.lib.container.get_container_realms(serial: str) → list[str][source]¶

Get the realms of the container.

Parameters:: serial – serial of the container
Returns:: List of realm names

privacyidea.lib.container.get_container_template_classes() → dict[str, type[ContainerTemplateBase]][source]¶: Returns a dictionary of all available container template classes in the format: { type: class }. New container template types have to be added here.

privacyidea.lib.container.get_container_token_types() → dict[str, list[str]][source]¶: Returns a dictionary of {“type”: [“tokentype0”, “tokentype1”, …]} entries for all container types. Used to list the supported token types for each container type.

privacyidea.lib.container.get_offline_token_serials(container: TokenContainerClass) → list[str][source]¶

Returns a list of serials of offline tokens in the container.

Parameters:: container – A TokenContainerClass object
Returns:: List of serials of offline tokens in the container

privacyidea.lib.container.get_template_obj(template_name: str) → ContainerTemplateBase[source]¶

Returns the template class object for the given template name. Raises a ResourceNotFoundError if no template with this name exists.

Parameters:: template_name – The name of the template
Returns:: The template class object

privacyidea.lib.container.get_templates_by_query(name: str = None, container_type: str = None, default: bool = None, page: int = 0, pagesize: int = 0, sortdir: str = 'asc', sortby: str = 'name') → dict[str, int | list[dict] | None][source]¶

Returns a list of all templates or a list filtered by the given parameters.

Parameters:

name – The name of the template, optional
container_type – The type of the container, optional
default – Filters for default templates if True or non-default if False, optional
page – The number of the page to view. 0 if no pagination shall be used
pagesize – The size of the page. 0 if no pagination shall be used
sortdir – The sort direction, either ‘asc’ or ‘desc’
sortby – The attribute to sort by

Returns:

a dictionary with a list of templates at the key ‘templates’ and optionally pagination entries (‘prev’, ‘next’, ‘current’, ‘count’)

privacyidea.lib.container.init_container(params: dict[str, any]) → dict[str, str | list][source]¶

Create a new container with the given parameters. Requires at least the type.

Parameters:

params –

The parameters for the new container as dictionary like

{
    "type": ...,
    "description": ..., (optional)
    "container_serial": ..., (optional)
    "user": ..., Name of the user (optional)
    "realm": ..., Name of the realm (optional)
    "template": {...}, Template as dictionary (optional)
    "template_name": ..., Name of the template (optional)
}

To assign a user to the container, the user and realm are required.

Returns:

Dictionary containing the serial of the created container and a list of init details for tokens if the container is created from a template

{
    "container_serial": "CONT0001",
    "template_tokens": [{"type": "hotp", ...}, ...]
}

privacyidea.lib.container.init_container_rollover(container: TokenContainerClass, server_url: str, challenge_ttl: int, registration_ttl: int, ssl_verify: bool, params: dict) → dict[source]¶

Initializes the rollover of a container. First the response to the challenge is validated. If it is valid, the registration is initialized. The new registration info is not finally set until the new container successfully finalized the registration.

Parameters:

container – The container object
server_url – The server url of the privacyIDEA server the client can contact
challenge_ttl – The time to live of the challenge in minutes
registration_ttl – The time to live of the challenge for the registration in minutes
ssl_verify – If the client has to verify the ssl certificate of the server
params – Container type specific parameters for the registration as dictionary

Returns:

dictionary with container specific information for the client

privacyidea.lib.container.init_registration(container: TokenContainerClass, container_rollover: bool, server_url: str, registration_ttl: int, ssl_verify: bool, challenge_ttl: int, params: dict) → dict[source]¶

Initiates the registration or rollover of a container. Checks if the container is in a valid registration state to do so. The last synchronization and authentication timestamps from a potential previous old registration are deleted and according registration data is written to the container info.

Parameters:

container – The container to be registered
container_rollover – True if a rollover should be performed instead of a fresh registration
server_url – The base url of the privacyIDEA server the container can contact
registration_ttl – The time in minutes the registration link is valid
ssl_verify – True if SSL should be used for the communication between the client and the server
challenge_ttl – Time in minutes a challenge is valid
params – Further container type specific parameters required for the registration

Returns:

A dictionary with the registration data (container type specific)

An example of a returned dictionary for a smartphone container:

{
    "container_url": {
        "description": "URL for privacyIDEA Container Registration",
        "value": <url>,
        "img": <qr code of the url>
    },
    "nonce": "ajhbdsuiuojno49877n4no3u09on38r98n",
    "time_stamp": "2020-08-25T14:00:00.000000+00:00",
    "key_algorithm": "secp384r1",
    "hash_algorithm": "SHA256",
    "ssl_verify": "True",
    "ttl": 10,
    "passphrase": <Passphrase prompt displayed to the user in the app> (optional)
}

privacyidea.lib.container.remove_multiple_tokens_from_container(container_serial: str, token_serials: str) → dict[str, bool][source]¶

Remove the given tokens from the container with the given serial. Raises a ResourceNotFoundError if no container for the given serial exist. Errors of removing tokens are caught and only logged, in order to be able to remove the remaining tokens in the list.

Parameters:

container_serial – The serial of the container
token_serials – A list of token serials to remove

Returns:

A dictionary in the format {token_serial: success}

privacyidea.lib.container.remove_token_from_container(container_serial: str, token_serial: str) → bool[source]¶

Remove the given token from the container with the given serial. Raises a ResourceNotFoundError if the container or token does not exist.

Parameters:

container_serial – The serial of the container
token_serial – the serial of the token to remove

Returns:

True on success

privacyidea.lib.container.set_container_description(serial: str, description: str)[source]¶

Set the description of a container.

Parameters:

serial – serial of the container
description – new description

privacyidea.lib.container.set_container_info(serial, info: dict) → dict[str, bool][source]¶

Set the given info to the container with the given serial. Keys of type PI_INTERNAL can not be modified and will be ignored.

Parameters:

serial – The serial of the container
info – The info dictionary in the format {key: value}

Returns:

Dictionary with the success state for each info key

privacyidea.lib.container.set_container_realms(serial: str, realms: list[str], allowed_realms: list[str] | None = []) → dict[str, bool][source]¶

Set the realms of a container.

Parameters:

serial – serial of the container
realms – new realms as list of str
allowed_realms – A list of realms the admin is allowed to set (None if all realms are allowed), optional

Returns:

Dictionary in the format {realm: success}, the entry ‘deleted’ indicates whether existing realms were deleted.

privacyidea.lib.container.set_container_states(serial: str, states: list[str]) → dict[str, bool][source]¶

Set the states of a container.

Parameters:

serial – serial of the container
states – new states as list of str

Returns:

Dictionary in the format {state: success}

privacyidea.lib.container.set_default_template(name: str)[source]¶

Sets the template of the given name as default and all other templates for the container type as non-default.

Parameters:: name – The name of the template to be the new default template

privacyidea.lib.container.set_options(serial: str, options: dict)[source]¶

Set the options of a container. The user has to be an admin or the owner of the container.

Parameters:

serial – The serial of the container
options – The options as dictionary

privacyidea.lib.container.unassign_user(serial: str, user: User) → bool[source]¶

Unassign a user from a container.

Parameters:

serial – container serial
user – user to unassign from the container

Returns:

True on success, False otherwise

privacyidea.lib.container.unregister(container: TokenContainerClass) → bool[source]¶

Unregister a container from the synchronization and deletes all challenges for the container.

Parameters:: container – The container object
Returns:: True on success