Token Class

The following token types are known to privacyIDEA. All are inherited from the base tokenclass describe below.

class privacyidea.lib.tokenclass.TokenClass(db_token)[source]
add_init_details(key, value)[source]

(was addInfo) Adds information to a volatile internal dict

add_tokeninfo(key, value, value_type=None)[source]

Add a key and a value to the DB tokeninfo :param key: :param value: :return:

classmethod api_endpoint(request, g)[source]

This provides a function to be plugged into the API endpoint /ttype/<tokentype> which is defined in api/ttype.py

The method should return
return “json”, {}
return “text”, “OK”
  • request – The Flask request
  • g – The Flask global object g

Flask Response or text

authenticate(passw, user=None, options=None)[source]

High level interface which covers the check_pin and check_otp This is the method that verifies single shot authentication like they are done with push button tokens.

It is a high level interface to support other tokens as well, which do not have a pin and otp separation - they could overwrite this method

If the authentication succeeds an OTP counter needs to be increased, i.e. the OTP value that was used for this authentication is invalidated!

  • passw (string) – the password which could be pin+otp value
  • user (User object) – The authenticating user
  • options (dict) – dictionary of additional request parameters

returns tuple of 1. true or false for the pin match, 2. the otpcounter (int) and the 3. reply (dict) that will be added as

additional information in the JSON response of /validate/check.

Return type:


static challenge_janitor()[source]

Just clean up all challenges, for which the expiration has expired.


Perform all checks on the token. Returns False if the token is either: * auth counter exceeded * not active * fail counter exceeded * validity period exceeded

This is used in the function token.check_token_list

Parameters:message_list – A list of messages
Returns:False, if any of the checks fail

This function checks the count_auth and the count_auth_success. If the count_auth is less than count_auth_max and count_auth_success is less than count_auth_success_max it returns True. Otherwise False.

Returns:success if the counter is less than max
Return type:bool
check_challenge_response(user=None, passw=None, options=None)[source]

This method verifies if there is a matching challenge for the given passw and also verifies if the response is correct.

It then returns the new otp_counter of the token.

In case of success the otp_counter will be >= 0.

  • user (User object) – the requesting user
  • passw (string) – the password (pin+otp)
  • options (dict) – additional arguments from the request, which could be token specific. Usually “transactionid”

return otp_counter. If -1, challenge does not match

Return type:



Checks if the failcounter is exceeded. It returns True, if the failcounter is less than maxfail :return: True or False


Check if the last successful authentication with the token is newer than the specified time delta which is passed as 10h, 7d or 1y.

It returns True, if the last authentication with this token is newer* than the specified delta.

Parameters:last_auth (basestring) – 10h, 7d or 1y
check_otp(otpval, counter=None, window=None, options=None)[source]

This checks the OTP value, AFTER the upper level did the checkPIN

In the base class we do not know, how to calculate the OTP value. So we return -1. In case of success, we should return >=0, the counter

  • otpval – the OTP value
  • counter (int) – The counter for counter based otp values
  • window – a counter window
  • options (dict) – additional token specific options

counter of the matching OTP value.

Return type:


check_otp_exist(otp, window=None)[source]

checks if the given OTP value is/are values of this very token. This is used to autoassign and to determine the serial number of a token.

  • otp – the OTP value
  • window (int) – The look ahead window

True or a value > 0 in case of success

check_pin(pin, user=None, options=None)[source]

Check the PIN of the given Password. Usually this is only dependent on the token itself, but the user object can cause certain policies.

Each token could implement its own PIN checking behaviour.

  • pin (string) – the PIN (static password component), that is to be checked.
  • user (User object) – for certain PIN policies (e.g. checking against the user store) this is the user, whose password would be checked. But at the moment we are checking against the userstore in the decorator “auth_otppin”.
  • options – the optional request parameters

If the PIN is correct, return True

Return type:



This checks if the datetime.datetime.now() is within the validity period of the token.

Return type:bool
create_challenge(transactionid=None, options=None)[source]

This method creates a challenge, which is submitted to the user. The submitted challenge will be preserved in the challenge database.

If no transaction id is given, the system will create a transaction id and return it, so that the response can refer to this transaction.

  • transactionid – the id of this challenge
  • options (dict) – the request context parameters / data

tuple of (bool, message, transactionid, attributes)

Return type:


The return tuple builds up like this: bool if submit was successful; message which is displayed in the JSON response; additional attributes, which are displayed in the JSON response.

static decode_otpkey(otpkey, otpkeyformat)[source]

Decode the otp key which is given in a specific format.

Supported formats:
  • hex, in which the otpkey is returned verbatim
  • base32check, which is specified in decode_base32check

In case the OTP key is malformed or if the format is unknown, a ParameterError is raised.

  • otpkey – OTP key passed by the user
  • otpkeyformat – “hex” or “base32check”

hex-encoded otpkey


delete the database token

generate_symmetric_key(server_component, client_component, options=None)[source]

This method generates a symmetric key, from a server component and a client component. This key generation could be based on HMAC, KDF or even Diffie-Hellman.

The basic key-generation is simply replacing the last n byte of the server component with bytes of the client component.

  • server_component (hex string) – The component usually generated by privacyIDEA
  • client_component – The component usually generated by the client (e.g. smartphone)
  • options

the new generated key as hex string


FIXME: Do we really use this?


This returns the token data as a dictionary. It is used to display the token list at /token/list.

Returns:The token data as dict
Return type:dict
static get_class_info(key=None, ret='all')[source]
static get_class_prefix()[source]
static get_class_type()[source]

Return the number of all authentication tries


Return the number of maximum allowed authentications


Return the number of successful authentications


Return the maximum allowed successful authentications

classmethod get_default_settings(params, logged_in_user=None, policy_object=None, client_ip=None)[source]

This method returns a dictionary with default settings for token enrollment. These default settings depend on the token type and the defined policies.

The returned dictionary is added to the parameters of the API call. :param params: The call parameters :type params: dict :param logged_in_user: The logged_in_user dictionary with “role”,

“username” and “realm”
Parameters:policy_object (PolicyClass) – The policy_object
Returns:default parameters
static get_hashlib(hLibStr)[source]

Returns a hashlib function for a given string :param hLibStr: the hashlib :type hLibStr: string :return: the hashlib :rtype: function

get_init_detail(params=None, user=None)[source]

to complete the token initialization, the response of the initialisation should be build by this token specific method. This method is called from api/token after the token is enrolled

get_init_detail returns additional information after an admin/init like the QR code of an HOTP/TOTP token. Can be anything else.

  • params (dict) – The request params during token creation token/init
  • user (User object) – the user, token owner

additional descriptions

Return type:



return the status of the token rollout

Returns:return the status dict.
Return type:dict
get_multi_otp(count=0, epoch_start=0, epoch_end=0, curTime=None, timestamp=None)[source]

This returns a dictionary of multiple future OTP values of a token.

  • count – how many otp values should be returned
  • epoch_start – time based tokens: start when
  • epoch_end – time based tokens: stop when
  • curTime (datetime object) – current time for TOTP token (for selftest)
  • timestamp (int) – unix time, current time for TOTP token (for selftest)

True/False, error text, OTP dictionary

Return type:



The default token does not support getting the otp value will return a tuple of four values a negative value is a failure.

Returns:something like: (1, pin, otpval, combined)

Return a list of realms the token is assigned to :return: realms :rtype:l list

static get_setting_type(key)[source]

This function returns the type of the token specific config/setting. This way a tokenclass can define settings, that can be “public” or a “password”. If this setting is written to the database, the type of the setting is set automatically in set_privacyidea_config

The key name needs to start with the token type.

Parameters:key – The token specific setting key
Returns:A string like “public”
get_tokeninfo(key=None, default=None)[source]

return the complete token info or a single key of the tokeninfo. When returning the complete token info dictionary encrypted entries are not decrypted. If you want to receive a decrypted value, you need to call it directly with the key.

  • key (string) – the key to return
  • default (string) – the default value, if the key does not exist

the value for the key

Return type:

int or string


Returns a tuple of a user identifier like user@realm and the displayname of “givenname surname”.


returns the end of validity period (if set) if not set, “” is returned. :return: the end of the validity period :rtype: string


returns the start of validity period (if set) if not set, “” is returned. :return: the start of the validity period :rtype: string

hKeyRequired = False

Increase the counter, that counts authentications - successful and unsuccessful


Increase the counter, that counts successful authentications Also increase the auth counter

inc_otp_counter(counter=None, increment=1, reset=True)[source]

Increase the otp counter and store the token in the database

Before increasing the token.count the token.count can be set using the parameter counter.

  • counter (int) – if given, the token counter is first set to counter and then increased by increment
  • increment (int) – increase the counter by this amount
  • reset (bool) – reset the failcounter if set to True

the new counter value

is_challenge_request(passw, user=None, options=None)[source]

This method checks, if this is a request, that triggers a challenge.

The default behaviour to trigger a challenge is, if the passw parameter only contains the correct token pin and the request contains a data or a challenge key i.e. if the options parameter contains a key data or challenge.

Each token type can decide on its own under which condition a challenge is triggered by overwriting this method.

please note: in case of pin policy == 2 (no pin is required) the check_pin would always return true! Thus each request containing a data or challenge would trigger a challenge!

The Challenge workflow is like this.

When an authentication request is issued, first it is checked if this is a request which will create a new challenge (is_challenge_request) or if this is a response to an existing challenge (is_challenge_response). In these two cases during request processing the following functions are called.

is_challenge_request or is_challenge_response


create_challenge check_challenge


challenge_janitor challenge_janitor

  • passw (string) – password, which might be pin or pin+otp
  • user (User object) – The user from the authentication request
  • options (dict) – dictionary of additional request parameters

true or false

Return type:


is_challenge_response(passw, user=None, options=None)[source]

This method checks, if this is a request, that is the response to a previously sent challenge.

The default behaviour to check if this is the response to a previous challenge is simply by checking if the request contains a parameter state or transactionid i.e. checking if the options parameter contains a key state or transactionid.

This method does not try to verify the response itself! It only determines, if this is a response for a challenge or not. The response is verified in check_challenge_response.

  • passw (string) – password, which might be pin or pin+otp
  • user (User object) – the requesting user
  • options (dict) – dictionary of additional request parameters

true or false

Return type:



Check if the token is in a locked state A locked token can not be modified

Returns:True, if the token is locked.

Return True is the token is orphaned.

An orphaned token means, that it has a user assigned, but the user does not exist in the user store (anymore) :return: True / False


Returns true if the pin of the token needs to be changed. :param password: Whether the password needs to be changed. :type password: bool

Returns:True or False
is_previous_otp(otp, window=10)[source]

checks if a given OTP value is a previous OTP value, that lies in the past or has a lower counter.

This is used in case of a failed authentication to return the information, that this OTP values was used previously and is invalid.

  • otp (basestring) – The OTP value.
  • window (int) – A counter window, how far we should look into the past.



Check if the token is in the revoked state

Returns:True, if the token is revoked
mode = ['authenticate', 'challenge']

Reset the failcounter

resync(otp1, otp2, options=None)[source]

This revokes the token. By default it 1. sets the revoked-field 2. set the locked field 3. disables the token.

Some token types may revoke a token without locking it.


Save the database token


Sets the counter for the occurred login attepms as key “count_auth” in token info :param count: a number :type count: int


Sets the counter for the maximum allowed login attempts as key “count_auth_max” in token info :param count: a number :type count: int


Sets the counter for the occurred successful logins as key “count_auth_success” in token info :param count: a number :type count: int


Sets the counter for the maximum allowed successful logins as key “count_auth_success_max” in token info :param count: a number :type count: int


Set the default values on the database level


Set the description on the database level

Parameters:description (string) – description of the token

Set the failcounter in the database

set_next_pin_change(diff=None, password=False)[source]

Sets the timestamp for the next_pin_change. Provide a difference like 90d (90 days).

Either provider the :param diff: The time delta. :type diff: basestring :param password: Do no set next_pin_change but next_password_change :return: None

set_pin(pin, encrypt=False)[source]

set the PIN of a token. Usually the pin is stored in a hashed way. :param pin: the pin to be set for the token :type pin: basestring :param encrypt: If set to True, the pin is stored encrypted and

can be retrieved from the database again
set_pin_hash_seed(pinhash, seed)[source]
set_realms(realms, add=False)[source]

Set the list of the realms of a token. :param realms: realms the token should be assigned to :type realms: list :param add: if the realms should be added and not replaced :type add: boolean


Set the tokeninfo field in the DB. Old values will be deleted. :param info: dictionary with key and value :type info: dict :return:


Set the tokentype in this object and also in the underlying database-Token-object.

Parameters:tokentype (string) – The type of the token like HOTP or TOTP
set_user(user, report=None)[source]

Set the user attributes (uid, resolvername, resolvertype) of a token.

  • user – a User() object, consisting of loginname and realm
  • report – tbdf.


set_user_identifiers(uid, resolvername, resolvertype)[source]

(was setUid) Set the user attributes of a token :param uid: The user id in the user source :param resolvername: The name of the resolver :param resolvertype: The type of the resolver :return: None


sets the end date of the validity period for a token :param end_date: the end date in the format YYYY-MM-DDTHH:MM+OOOO

if the format is wrong, the method will throw an exception

sets the start date of the validity period for a token :param start_date: the start date in the format YYYY-MM-DDTHH:MM+OOOO

if the format is wrong, the method will throw an exception
split_pin_pass(passw, user=None, options=None)[source]

Split the password into the token PIN and the OTP value

take the given password and split it into the PIN and the OTP value. The splitting can be dependent of certain policies. The policies may depend on the user.

Each token type may define its own way to slit the PIN and the OTP value.

  • passw – the password to split
  • user (User object) – The user/owner of the token
  • options (dict) – can be used be the token types.

tuple of pin and otp value


tuple of (split status, pin, otp value)

Return type:



callback to enable a status change, if auth failed


callback to enable a status change, if auth succeeds

static test_config(params=None)[source]

This method is used to test the token config. Some tokens require some special token configuration like the SMS-Token or the Email-Token. To test this configuration, this classmethod is used.

It takes token specific parameters and returns a tuple of a boolean and a result description.

Parameters:params (dict) – token specific parameters
Returns:success, description
Return type:tuple
update(param, reset_failcount=True)[source]

Update the token object

Parameters:param – a dictionary with different params like keysize, description, genkey, otpkey, pin
Type:param: dict

return the user (owner) of a token If the token has no owner assigned, we return None

Returns:The owner of the token
Return type:User object
using_pin = True