16.2.1.5. 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, ikey, ivalue, user, user_role='user')[source]¶

Add the given info to the container with the given serial.

Parameters

serial – The serial of the container
ikey – The info key
ivalue – The info value
user – The user adding the info
user_role – The role of the user (‘admin’ or ‘user’)

Returns

True on success

privacyidea.lib.container.add_container_realms(serial, realms, allowed_realms)[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, states, user: privacyidea.lib.user.User = None, user_role='user')[source]¶

Add the states to a container.

Parameters

serial – serial of the container
states – additional states as list of str
user – user setting the states
user_role – role of the logged-in user (“admin” or “user”)

Returns

Dictionary in the format {state: success}

privacyidea.lib.container.add_multiple_tokens_to_container(container_serial, token_serials, user: privacyidea.lib.user.User = None, user_role='user', allowed_realms=[])[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. A user is only allowed to add a token to a container if the user is an admin or the owner of both. If the token is already in a container, the user also has to be the owner of the old container.

Parameters

container_serial – The serial of the container
token_serials – A list of token serials to add
user – The user adding the tokens
user_role – The role of the user (‘admin’ or ‘user’)
allowed_realms – A list of realms the admin is allowed to add tokens to, optional

Returns

A dictionary in the format {token_serial: success}

privacyidea.lib.container.add_token_to_container(container_serial, token_serial, user: privacyidea.lib.user.User = None, user_role='user')[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. Raises a PolicyError if the user is not allowed to add the token to the container. The user/admin needs the rights to edit the container, the token and if the token is already in a container, also the rights for this container.

Parameters

container_serial – The serial of the container
token_serial – The serial of the token
user – The user adding the token
user_role – The role of the user (‘admin’ or ‘user’)

Returns

True on success

privacyidea.lib.container.assign_user(serial, user: privacyidea.lib.user.User, logged_in_user: privacyidea.lib.user.User = None, user_role='user')[source]¶

Assign a user to a container.

Parameters

serial – container serial
user – user to assign to the container
logged_in_user – user performing this action
user_role – role of the logged-in user (“admin” or “user”)

Returns

True on success, False otherwise

privacyidea.lib.container.create_container_from_db_object(db_container: privacyidea.models.TokenContainer)[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.delete_container_by_id(container_id: int, user: privacyidea.lib.user.User, user_role='user')[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
user – The user deleting the container
user_role – The role of the user (‘admin’ or ‘user’)

Returns

ID of the deleted container on success

privacyidea.lib.container.delete_container_by_serial(serial: str, user: privacyidea.lib.user.User, user_role='user')[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
user – The user deleting the container
user_role – The role of the user (‘admin’ or ‘user’)

Returns

ID of the deleted container on success

privacyidea.lib.container.delete_container_info(serial, ikey=None, user=None, user_role='user')[source]¶

Delete the info of the given key or all infos if no key is given.

Parameters

serial – The serial of the container
ikey – The info key or None to delete all info keys
user – The user adding the info
user_role – The role of the user (‘admin’ or ‘user’)

Returns

True on success, False otherwise

privacyidea.lib.container.find_container_by_id(container_id: int)[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)[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)[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: privacyidea.lib.user.User = None, serial=None, ctype=None, token_serial=None, realms=None, sortby='serial', sortdir='asc', page=0, pagesize=0)[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, optional
ctype – container type, optional
token_serial – serial of a token which is assigned to the container, optional
realms – list of realms the container is assigned to, 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_container_classes()[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()[source]¶: Returns a dictionary of {“type”: “Type: description”} entries for all container types. Used to list the container types.

privacyidea.lib.container.get_container_info_dict(serial, ikey=None, user=None, user_role='user')[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
user – The user getting the info
user_role – The role of the user (‘admin’ or ‘user’)

Returns

The info dict

privacyidea.lib.container.get_container_policy_info(container_type=None)[source]¶

Returns the policy info for the given container type or for all container types if no type is defined.

Parameters: container_type – The type of the container, optional
Returns: The policy info for the given container type or for all container types

privacyidea.lib.container.get_container_realms(serial)[source]¶

Get the realms of the container.

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

privacyidea.lib.container.get_container_token_types()[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.init_container(params)[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)
}

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

Returns

The serial of the created container

privacyidea.lib.container.remove_multiple_tokens_from_container(container_serial, token_serials, user: privacyidea.lib.user.User = None, user_role='user', allowed_realms=[])[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. A user is only allowed to remove a token from a container if it is an admin or the owner of both, the token and the container.

Parameters

container_serial – The serial of the container
token_serials – A list of token serials to remove
user – The user adding the tokens
user_role – The role of the user (‘admin’ or ‘user’)
allowed_realms – A list of realms the user is allowed to remove tokens from (only for admins), optional

Returns

A dictionary in the format {token_serial: success}

privacyidea.lib.container.remove_token_from_container(container_serial, token_serial, user: privacyidea.lib.user.User = None, user_role='user')[source]¶

Remove the given token from the container with the given serial. Raises a ResourceNotFoundError if the container or token does not exist. Raises a PolicyError if the user is not allowed to remove the token from the container. The user/admin needs the rights to edit the container, the token and if the token is already in a container, also the rights for this container.

Parameters

container_serial – The serial of the container
token_serial – the serial of the token to remove
user – The user adding the token
user_role – The role of the user (‘admin’ or ‘user’)

Returns

True on success

privacyidea.lib.container.set_container_description(serial, description, user: privacyidea.lib.user.User = None, user_role='user')[source]¶

Set the description of a container.

Parameters

serial – serial of the container
description – new description
user – user setting the description
user_role – role of the logged-in user (“admin” or “user”)

privacyidea.lib.container.set_container_info(serial, info, user, user_role='user')[source]¶

Set the given info to the container with the given serial.

Parameters

serial – The serial of the container
info – The info dictionary in the format {key: value}
user – The user adding the info
user_role – The role of the user (‘admin’ or ‘user’)

Returns

True on success

privacyidea.lib.container.set_container_realms(serial, realms, allowed_realms=[])[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, states, user: privacyidea.lib.user.User = None, user_role='user')[source]¶

Set the states of a container.

Parameters

serial – serial of the container
states – new states as list of str
user – user setting the states
user_role – role of the logged-in user (“admin” or “user”)

Returns

Dictionary in the format {state: success}

privacyidea.lib.container.unassign_user(serial, user: privacyidea.lib.user.User, logged_in_user: privacyidea.lib.user.User = None, user_role='user')[source]¶

Unassign a user from a container.

Parameters

serial – container serial
user – user to unassign from the container
logged_in_user – user performing this action
user_role – role of the logged-in user (“admin” or “user”)

Returns

True on success, False otherwise