13.2.1.2.14. TiQR Token¶
The TiQR token is a special App based token, which allows easy login and which is based on OCRA.
It generates an enrollment QR code, which contains a link with the more detailed enrollment information.
For a description of the TiQR protocol see
- https://www.usenix.org/legacy/events/lisa11/tech/full_papers/Rijswijk.pdf
- https://github.com/SURFnet/tiqr/wiki/Protocol-documentation.
- https://tiqr.org
The TiQR token is based on the OCRA algorithm. It lets you authenticate with your smartphone by scanning a QR code.
The TiQR token is enrolled via /token/init, but it requires no otpkey, since the otpkey is generated on the smartphone and pushed to the privacyIDEA server in a seconds step.
13.2.1.2.14.1. Enrollment¶
- Start enrollment with /token/init
- Scan the QR code in the details of the JSON result. The QR code contains a link to /ttype/tiqr?action=metadata
- The TiQR Smartphone App will fetch this link and get more information
- The TiQR Smartphone App will push the otpkey to a link /ttype/tiqr?action=enrollment and the token will be ready for use.
13.2.1.2.14.2. Authentication¶
An application that wants to use the TiQR token with privacyIDEA has to use the token in challenge response.
- Call
/validate/check?user=<user>&pass=<pin>
with the PIN of the TiQR token - The details of the JSON response contain a QR code, that needs to
be shown to the user.
In addition the application needs to save the
transaction_id
in the response. - The user scans the QR code.
- The TiQR App communicates with privacyIDEA via the API /ttype/tiqr. In this step the response of the App to the challenge is verified. The successful authentication is stored in the Challenge DB table. (No need for the application to take any action)
- Now, the application needs to poll
/validate/check?user=<user>&transaction_id=*&pass=
to verifiy the successful authentication. Thepass
can be empty. Ifvalue=true
is returned, the user authenticated successfully with the TiQR token.
This code is tested in tests/test_lib_tokens_tiqr.
13.2.1.2.14.3. Implementation¶
-
class
privacyidea.lib.tokens.tiqrtoken.
TiqrTokenClass
(*args, **kwds)[source]¶ The TiQR Token implementation.
-
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 See Tokentype endpoints.
Parameters: - request – The Flask request
- g – The Flask global object g
Returns: Flask Response or text
-
check_challenge_response
(*args, **kwds)[source]¶ This function checks, if the challenge for the given transaction_id was marked as answered correctly. For this we check the otp_status of the challenge with the transaction_id in the database.
We do not care about the password
Parameters: - 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 “transaction_id”
Returns: return otp_counter. If -1, challenge does not match
Return type: int
-
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.
Parameters: - transactionid – the id of this challenge
- options (dict) – the request context parameters / data
Returns: tuple of (bool, message, transactionid, attributes)
Return type: tuple
The return tuple builds up like this:
bool
if submit was successful;message
which is displayed in the JSON response; additionalattributes
, which are displayed in the JSON response.
-
classmethod
get_class_info
(*args, **kwds)[source]¶ returns a subtree of the token definition
Parameters: - key (string) – subsection identifier
- ret (user defined) – default return value, if nothing is found
Returns: subsection if key exists or user defined
Return type: dict or scalar
-
classmethod
get_class_prefix
()[source]¶ Return the prefix, that is used as a prefix for the serial numbers. :return: TiQR :rtype: basestring
-
classmethod
get_class_type
()[source]¶ Returns the internal token type identifier :return: tiqr :rtype: basestring
-
get_init_detail
(*args, **kwds)[source]¶ At the end of the initialization we return the URL for the TiQR App.
-
is_challenge_request
(*args, **kwds)[source]¶ check, if the request would start a challenge In fact every Request that is not a response needs to start a challenge request.
At the moment we do not think of other ways to trigger a challenge.
- This function is not decorated with
- @challenge_response_allowed
as the TiQR token is always a challenge response token!
Parameters: - passw – The PIN of the token.
- options – dictionary of additional request parameters
Returns: returns true or false
-
classmethod