16.3.1. The database model

privacyIDEA Database definition

class privacyidea.models.Admin(**kwargs)

The administrators for managing the system. To manage the administrators use the command pi-manage.

In addition certain realms can be defined to be administrative realms.

Parameters

• username (basestring) – The username of the admin

• password (basestring) – The password of the admin (stored using PBKDF2, salt and pepper)

• email (basestring) – The email address of the admin (not used at the moment)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.Audit(action='', success=0, authentication='', serial='', token_type='', container_serial='', container_type='', user='', realm='', resolver='', administrator='', action_detail='', info='', privacyidea_server='', client='', user_agent='', user_agent_version='', loglevel='default', clearance_level='default', thread_id='0', policies='', startdate=None, duration=None)

This class stores the Audit entries

class privacyidea.models.AuthCache(username, realm, resolver, authentication, first_auth=None, last_auth=None)

class privacyidea.models.CAConnector(name, catype)

The table “caconnector” contains the names and types of the defined CA connectors. Each connector has a different configuration, that is stored in the table “caconnectorconfig”.

class privacyidea.models.CAConnectorConfig(caconnector_id=None, Key=None, Value=None, caconnector=None, Type='', Description='')

Each CAConnector can have multiple configuration entries. Each CA Connector type can have different required config values. Therefor the configuration is stored in simple key/value pairs. If the type of a config entry is set to “password” the value of this config entry is stored encrypted.

The config entries are referenced by the id of the resolver.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.Challenge(serial, transaction_id=None, challenge='', data='', session='', validitytime=120)

Table for handling of the generic challenges.

get(timestamp=False)

return a dictionary of all vars in the challenge class

Parameters

timestamp (bool) – if true, the timestamp will given in a readable format 2014-11-29 21:56:43.057293

Returns

dict of vars

get_otp_status()

This returns how many OTPs were already received for this challenge. and if a valid OTP was received.

Returns

tuple of count and True/False

Return type

tuple

is_valid()

Returns true, if the expiration time has not passed, yet. :return: True if valid :rtype: bool

set_data(data)

set the internal data of the challenge :param data: unicode data :type data: string, length 512

class privacyidea.models.ClientApplication(**kwargs)

This table stores the clients, which sent an authentication request to privacyIDEA. This table is filled automatically by authentication requests.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.Config(Key, Value, Type='', Description='')

The config table holds all the system configuration in key value pairs.

Additional configuration for realms, resolvers and machine resolvers is stored in specific tables.

class privacyidea.models.CustomUserAttribute(user_id, resolver, realm_id, Key, Value, Type=None)

The table “customuserattribute” is used to store additional, custom attributes for users.

A user is identified by the user_id, the resolver_id and the realm_id.

The additional attributes are stored in Key and Value. The Type can hold extra information like e.g. an encrypted value / password.

Note: Since the users are external, i.e. no objects in this database,

there is not logic reference on a database level. Since users could be deleted from user stores without privacyIDEA realizing that, this table could pile up with remnants of attributes.

Create a new customuserattribute for a user tuple

class privacyidea.models.EventCounter(name, value=0, node='')

This table stores counters of the event handler “Counter”.

Note that an event counter name does not correspond to just one, but rather several table rows, because we store event counters for each privacyIDEA node separately. This is intended to improve the performance of replicated setups, because each privacyIDEA node then only writes to its own “private” table row. This way, we avoid locking issues that would occur if all nodes write to the same table row.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

decrease()

Decrease the value of a counter. :return:

increase()

Increase the value of a counter :return:

class privacyidea.models.EventHandler(name, event, handlermodule, action, condition='', ordering=0, options=None, id=None, conditions=None, active=True, position='post')

This model holds the list of defined events and actions to this events. A handler module can be bound to an event with the corresponding condition and action.

get()

Return the serialized eventhandler object including the options

Returns

complete dict

Rytpe

dict

class privacyidea.models.EventHandlerCondition(eventhandler_id, Key, Value, comparator='equal')

Each EventHandler entry can have additional conditions according to the handler module

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.EventHandlerOption(eventhandler_id, Key, Value, Type='', Description='')

Each EventHandler entry can have additional options according to the handler module.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.MachineResolver(name, rtype)

This model holds the definition to the machinestore. Machines could be located in flat files, LDAP directory or in puppet services or other…

The usual MachineResolver just holds a name and a type and a reference to its config

class privacyidea.models.MachineResolverConfig(resolver_id=None, Key=None, Value=None, resolver=None, Type='', Description='')

Each Machine Resolver can have multiple configuration entries. The config entries are referenced by the id of the machine resolver

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.MachineToken(machineresolver_id=None, machineresolver=None, machine_id=None, token_id=None, serial=None, application=None)

The MachineToken assigns a Token and an application type to a machine. The Machine is represented as the tuple of machineresolver.id and the machine_id. The machine_id is defined by the machineresolver.

This can be an n:m mapping.

class privacyidea.models.MachineTokenOptions(machinetoken_id, key, value)

This class holds an Option for the token assigned to a certain client machine. Each Token-Clientmachine-Combination can have several options.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.MethodsMixin

This class mixes in some common Class table functions like delete and save

class privacyidea.models.MonitoringStats(timestamp, key, value)

This is the table that stores measured, arbitrary statistic points in time.

This could be used to store time series but also to store current values, by simply fetching the last value from the database.

Create a new database entry in the monitoring stats table :param timestamp: The time of the measurement point :type timestamp: timezone-naive datetime :param key: The key of the measurement :type key: basestring :param value: The value of the measurement :type value: Int

class privacyidea.models.NodeName(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.PasswordReset(recoverycode, username, realm, resolver='', email=None, timestamp=None, expiration=None, expiration_seconds=3600)

Table for handling password resets. This table stores the recoverycodes sent to a given user

The application should save the HASH of the recovery code. Just like the password for the Admins the application shall salt and pepper the hash of the recoverycode. A database admin will not be able to inject a rogue recovery code.

A user can get several recoverycodes. A recovery code has a validity period

Optional: The email to which the recoverycode was sent, can be stored.

class privacyidea.models.PeriodicTask(name, active, interval, node_list, taskmodule, ordering, options=None, id=None, retry_if_failed=True)

This class stores tasks that should be run periodically.

Parameters

• name – Unique name of the periodic task as unicode

• active – a boolean

• retry_if_failed – a boalean

• interval – a unicode specifying the periodicity of the task

• node_list – a list of unicodes, denoting the node names that should execute that task. If we update an existing PeriodicTask entry, PeriodicTaskLastRun entries referring to nodes that are not present in node_list any more will be deleted.

• taskmodule – a unicode

• ordering – an integer. Lower tasks are executed first.

• options – a dictionary of options, mapping unicode keys to values. Values will be converted to unicode. If we update an existing PeriodicTask entry, all options that have been set previously but are not present in options will be deleted.

• id – the ID of an existing entry, if any

property aware_last_update

Return self.last_update with attached UTC tzinfo

get()

Return the serialized periodic task object including the options and last runs. The last runs are returned as timezone-aware UTC datetimes.

Returns

complete dict

save()

If the entry has an ID set, update the entry. If not, create one. Set last_update to the current time. :return: the entry ID

set_last_run(node, timestamp)

Store the information that the last run of the periodic job occurred on node at timestamp. :param node: Node name as a string :param timestamp: Timestamp as UTC datetime (without timezone information) :return:

class privacyidea.models.PeriodicTaskLastRun(periodictask_id, node, timestamp)

Each PeriodicTask entry stores, for each node, the timestamp of the last successful run.

Parameters

• periodictask_id – ID of the periodic task we are referring to

• node – Node name as unicode

• timestamp – Time of the last run as a datetime. A timezone must not be set! We require the time to be given in UTC.

property aware_timestamp

Return self.timestamp with attached UTC tzinfo

save()

Create or update a PeriodicTaskLastRun entry, depending on the value of self.id. :return: the entry id

class privacyidea.models.PeriodicTaskOption(periodictask_id, key, value)

Each PeriodicTask entry can have additional options according to the task module.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

save()

Create or update a PeriodicTaskOption entry, depending on the value of self.id :return: the entry ID

class privacyidea.models.Policy(name, active=True, scope='', action='', realm='', adminrealm='', adminuser='', resolver='', user='', client='', time='', pinode='', priority=1, check_all_resolvers=False, conditions=None, user_case_insensitive=False)

The policy table contains the policy definitions.

The Policies control the behaviour in the scopes

• enrollment

• authentication

• authorization

• administration

• user actions

• webui

get(key=None)

Either returns the complete policy entry or a single value :param key: return the value for this key :type key: string :return: complete dict or single value :rytpe: dict or value

get_conditions_tuples()

Returns

a list of 5-tuples (section, key, comparator, value, active).

get_policy_description()

set_conditions(conditions)

Replace the list of conditions of this policy with a new list of conditions, i.e. a list of 5-tuples (section, key, comparator, value, active).

class privacyidea.models.PolicyCondition(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

as_tuple()

Returns

the condition as a tuple (section, key, comparator, value, active)

class privacyidea.models.PolicyDescription(object_id, name='', object_type='', description='')

The description table is used to store the description of policy

class privacyidea.models.PrivacyIDEAServer(**kwargs)

This table can store remote privacyIDEA server definitions

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.RADIUSServer(**kwargs)

This table can store configurations of RADIUS servers. https://github.com/privacyidea/privacyidea/issues/321

It saves * a unique name * a description * an IP address a * a Port * a secret * timeout in seconds (default 5) * retries (default 3)

These RADIUS server definition can be used in RADIUS tokens or in a radius passthru policy.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

save()

If a RADIUS server with a given name is save, then the existing RADIUS server is updated.

class privacyidea.models.Realm(realm)

The realm table contains the defined realms. User Resolvers can be grouped to realms. This very table contains just contains the names of the realms. The linking to resolvers is stored in the table “resolverrealm”.

class privacyidea.models.Resolver(name, rtype)

The table “resolver” contains the names and types of the defined User Resolvers. As each Resolver can have different required config values the configuration of the resolvers is stored in the table “resolverconfig”.

class privacyidea.models.ResolverConfig(resolver_id=None, Key=None, Value=None, resolver=None, Type='', Description='')

Each Resolver can have multiple configuration entries. Each Resolver type can have different required config values. Therefor the configuration is stored in simple key/value pairs. If the type of a config entry is set to “password” the value of this config entry is stored encrypted.

The config entries are referenced by the id of the resolver.

class privacyidea.models.ResolverRealm(resolver_id=None, realm_id=None, resolver_name=None, realm_name=None, priority=None, node_uuid=None, node_name=None)

This table stores which Resolver is located in which realm This is a N:M relation

class privacyidea.models.SMSGateway(identifier, providermodule, description=None, options=None, headers=None)

This table stores the SMS Gateway definitions. See https://github.com/privacyidea/privacyidea/wiki/concept:-Delivery-Gateway

It saves the * unique name * a description * the SMS provider module

All options and parameters are saved in other tables.

as_dict()

Return the object as a dictionary

Returns

complete dict

Rytpe

dict

delete()

When deleting an SMS Gateway we also delete all the options. :return:

property header_dict

Return all connected headers as a dictionary

Returns

dict

property option_dict

Return all connected options as a dictionary

Returns

dict

class privacyidea.models.SMSGatewayOption(gateway_id, Key, Value, Type=None)

This table stores the options, parameters and headers for an SMS Gateway definition.

Create a new gateway_option for the gateway_id

class privacyidea.models.SMTPServer(**kwargs)

This table can store configurations for SMTP servers. Each entry represents an SMTP server. EMail Token, SMS SMTP Gateways or Notifications like PIN handlers are supposed to use a reference to a server definition. Each Machine Resolver can have multiple configuration entries. The config entries are referenced by the id of the machine resolver

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

get()

Returns

the configuration as a dictionary

class privacyidea.models.Serviceid(servicename, description=None)

The serviceid table contains the defined service IDs. These service ID describe services like “webservers” or “dbservers” which e.g. request SSH keys from the privacyIDEA system.

class privacyidea.models.Subscription(**kwargs)

This table stores the imported subscription files.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

get()

Return the database object as dict :return:

class privacyidea.models.TimestampMethodsMixin

This class mixes in the table functions including update of the timestamp

class privacyidea.models.Token(serial, tokentype='', isactive=True, otplen=6, otpkey='', userid=None, resolver=None, realm=None, **kwargs)

The “Token” table contains the basic token data.

It contains data like

• serial number

• secret key

• PINs

• …

The table privacyidea.models.TokenOwner contains the owner information of the specified token. The table privacyidea.models.TokenInfo contains additional information that is specific to the tokentype.

del_info(key=None)

Deletes tokeninfo for a given token. If the key is omitted, all Tokeninfo is deleted.

Parameters

key – searches for the given key to delete the entry

Returns

del_tokengroup(tokengroup=None, tokengroup_id=None)

Deletes the tokengroup from the given token. If tokengroup name and id are omitted, all tokengroups are deleted.

Parameters

• tokengroup (str) – The name of the tokengroup

• tokengroup_id (int) – The id of the tokengroup

Returns

get(key=None, fallback=None, save=False)

simulate the dict behaviour to make challenge processing easier, as this will have to deal as well with ‘dict only challenges’

Parameters

• key – the attribute name - in case of key is not provided, a dict of all class attributes are returned

• fallback – if the attribute is not found, the fallback is returned

• save – in case of all attributes and save==True, the timestamp is converted to a string representation

get_hashed_pin(pin)

calculate a hash from a pin Fix for working with MS SQL servers MS SQL servers sometimes return a ‘<space>’ when the column is empty: ‘’

Parameters

pin (str) – the pin to hash

Returns

hashed pin with current pin_seed

Return type

str

get_info()

Returns

The token info as dictionary

get_realms()

return a list of the assigned realms

Returns

the realms of the token

Return type

list

get_user_pin()

return the userPin :rtype : the PIN as a secretObject

set_hashed_pin(pin)

Set the pin of the token in hashed format

Parameters

pin (str) – the pin to hash

Returns

the hashed pin

Return type

str

set_info(info)

Set the additional token info for this token

Entries that end with “.type” are used as type for the keys. I.e. two entries sshkey=”XYZ” and sshkey.type=”password” will store the key sshkey as type “password”.

Parameters

info (dict) – The key-values to set for this token

set_pin(pin, hashed=True)

set the OTP pin in a hashed way

set_realms(realms, add=False)

Set the list of the realms.

This is done by filling the privacyidea.models.TokenRealm table.

Parameters

• realms (list[str]) – realms

• add (bool) – If set, the realms are added. I.e. old realms are not deleted

set_so_pin(soPin)

For smartcards this sets the security officer pin of the token

:rtype : None

set_tokengroups(tokengroups, add=False)

Set the list of the tokengroups.

This is done by filling the privacyidea.models.TokenTokengroup table.

Parameters

• tokengroups (list[str]) – the tokengroups

• add (bool) – If set, the tokengroups are added. I.e. old tokengroups are not deleted

update_otpkey(otpkey)

in case of a new hOtpKey we have to do some more things

update_type(typ)

in case the previous has been different type we must reset the counters But be aware, ray, this could also be upper and lower case mixing…

class privacyidea.models.TokenContainer(serial, container_type='Generic', tokens=None, description='', states=None)

The “Tokencontainer” table contains the containers and their associated tokens.

set_info(info)

Set the additional container info for this container

Entries that end with “.type” are used as type for the keys. I.e. two entries sshkey=”XYZ” and sshkey.type=”password” will store the key sshkey as type “password”.

Parameters

info (dict) – The key-values to set for this container

class privacyidea.models.TokenContainerInfo(container_id, key, value, type=None, description=None)

The table “tokencontainerinfo” is used to store additional, long information that is specific to the containertype.

The tokencontainerinfo is reference by the foreign key to the “tokencontainer” table.

Create a new tokencontainerinfo for a given token_id

class privacyidea.models.TokenContainerOwner(container_id=None, container_serial=None, resolver=None, user_id=None, realm_id=None, realm_name=None)

Create a new TokenContainerOwner assignment.

Parameters

• container_id –

• container_serial – alternative to container_id

• resolver –

• user_id –

• realm_id –

• realm_name – alternative to realm_id

class privacyidea.models.TokenContainerRealm(**kwargs)

This table stores to which realms a container is assigned. A container is in the realm of the user it is assigned to. But a container can also be put into many additional realms.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.TokenContainerStates(container_id=None, state='active')

state

The table “tokencontainerstates” is used to store the states of the container. A container can be in several states.

class privacyidea.models.TokenContainerToken(**kwargs)

Association table to link tokens to containers.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class privacyidea.models.TokenInfo(token_id, Key, Value, Type=None, Description=None)

The table “tokeninfo” is used to store additional, long information that is specific to the tokentype. E.g. the tokentype “TOTP” has additional entries in the tokeninfo table for “timeStep” and “timeWindow”, which are stored in the column “Key” and “Value”.

The tokeninfo is reference by the foreign key to the “token” table.

Create a new tokeninfo for a given token_id

class privacyidea.models.TokenOwner(token_id=None, serial=None, user_id=None, resolver=None, realm_id=None, realmname=None)

This tables stores the owner of a token. A token can be assigned to several users.

Create a new token assignment to a user.

Parameters

• token_id – The database ID of the token

• serial – The alternate serial number of the token

• resolver – The identifying name of the resolver

• realm_id – The database ID of the realm

• realmname – The alternate name of realm

class privacyidea.models.TokenRealm(realm_id=0, token_id=0, realmname=None)

This table stores to which realms a token is assigned. A token is in the realm of the user it is assigned to. But a token can also be put into many additional realms.

Create a new TokenRealm entry. :param realm_id: The id of the realm :param token_id: The id of the token

save()

We only save this, if it does not exist, yet.

class privacyidea.models.TokenTokengroup(tokengroup_id=0, token_id=0, tokengroupname=None)

This table stores the assignment of tokens to tokengroups. A token can be assigned to several different token groups.

Create a new TokenTokengroup assignment :param tokengroup_id: The id of the token group :param tokengroupname: the name of the tokengroup :param token_id: The id of the token

save()

We only save this, if it does not exist, yet.

class privacyidea.models.Tokengroup(groupname, description=None)

The tokengroup table contains the definition of available token groups. A token can then be assigned to several of these tokengroups.

class privacyidea.models.UserCache(username, used_login, resolver, user_id, timestamp)

privacyidea.models.cleanup_challenges(serial)

Delete all challenges, that have expired.

Returns

None

privacyidea.models.get_machineresolver_id(resolvername)

Return the database ID of the machine resolver :param resolvername: :return:

privacyidea.models.get_machinetoken_ids(machine_id, resolver_name, serial, application)

Returns a list of the ID in the machinetoken table

Parameters

• machine_id (basestring) – The resolverdependent machine_id

• resolver_name (basestring) – The name of the resolver

• serial (basestring) – the serial number of the token

• application (basestring) – The application type

Returns

A list of IDs of the machinetoken entry

Return type

list of int

privacyidea.models.get_token_id(serial)

Return the database token ID for a given serial number :param serial: :return: token ID :rtpye: int

privacyidea.models.save_config_timestamp(invalidate_config=True)

Save the current timestamp to the database, and optionally invalidate the current request-local config object. :param invalidate_config: defaults to True