15.2.1.2.10. Push Token¶
-
class
privacyidea.lib.tokens.pushtoken.
PushTokenClass
(db_token)[source]¶ The Push Token uses the firebase service to send challenges to the user’s smartphone. The user confirms on the smartphone, signs the challenge and sends it back to privacyIDEA.
The enrollment occurs in two enrollment steps:
- Step 1:
The device is enrolled using a QR code, which encodes the following URI:
otpauth://pipush/PIPU0006EF85?url=https://yourprivacyideaserver/enroll/this/token&ttl=120
- Step 2:
In the QR code is a URL, where the smartphone sends the remaining data for the enrollment:
POST /ttype/push HTTP/1.1 Host: https://yourprivacyideaserver/ enrollment_credential=<hex nonce> serial=<token serial> fbtoken=<firebase token> pubkey=<public key>
For more information see:
-
classmethod
api_endpoint
(request, g)[source]¶ This provides a function which is called by the API endpoint
/ttype/push
which is defined in Tokentype endpointsThe method returns a tuple
("json", {})
This endpoint provides several functionalities:
It is used for the 2nd enrollment step of the smartphone. It accepts the following parameters:
POST /ttype/push HTTP/1.1 Host: https://yourprivacyideaserver serial=<token serial> fbtoken=<firebase token> pubkey=<public key>
It is also used when the smartphone sends the signed response to the challenge during authentication. The following parameters ar accepted:
POST /ttype/push HTTP/1.1 Host: https://yourprivacyideaserver serial=<token serial> nonce=<the actual challenge> signature=<the signed nonce>
In some cases the Firebase service changes the token of a device. This needs to be communicated to privacyIDEA through this endpoint (https://github.com/privacyidea/privacyidea/wiki/concept%3A-pushtoken-poll#update -firebase-token):
POST /ttype/push HTTP/1.1 Host: https://yourprivacyideaserver new_fb_token=<new firebase token> serial=<token serial> timestamp=<timestamp> signature=SIGNATURE(<new_fb_token>|<serial>|<timestamp>)
And it also acts as an endpoint for polling challenges:
GET /ttype/push HTTP/1.1 Host: https://yourprivacyideaserver serial=<tokenserial> timestamp=<timestamp> signature=SIGNATURE(<tokenserial>|<timestamp>)
More on polling can be found here: https://github.com/privacyidea/privacyidea/wiki/concept%3A-pushtoken-poll
- Parameters
request – The Flask request
g – The Flask global object g
- Returns
The json string representing the result dictionary
- Return type
tuple(“json”, str)
-
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. The challenge is send to the smartphone app and privacyIDEA waits for the response to arrive.
- Parameters
passw (string) – the password which could be pin+otp value
user (User object) – The authenticating user
options (dict) – dictionary of additional request parameters
- Returns
returns tuple of
true or false for the pin match,
the otpcounter (int) and the
reply (dict) that will be added as additional information in the JSON response of
/validate/check
.
- Return type
tuple
-
check_challenge_response
(user=None, passw=None, options=None)[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
-
check_if_disabled
= False¶
-
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.
-
static
get_class_info
(key=None, ret='all')[source]¶ returns all or a subtree of the token definition
- Parameters
key (str) – subsection identifier
ret (user defined) – default return value, if nothing is found
- Returns
subsection if key exists or user defined
- Return type
dict
-
get_init_detail
(params=None, user=None)[source]¶ This returns the init details during enrollment.
In the 1st step the QR Code is returned.
-
is_challenge_request
(passw, user=None, options=None)[source]¶ check, if the request would start a challenge
We need to define the function again, to get rid of the is_challenge_request-decorator of the base class
- Parameters
passw – password, which might be pin or pin+otp
options – dictionary of additional request parameters
- Returns
returns true or false
-
mode
= ['authenticate', 'challenge', 'outofband']¶
-
update
(param, reset_failcount=True)[source]¶ process the initialization parameters
We need to distinguish the first authentication step and the second authentication step.
- step:
param
contains:type
genkey
- step:
param
contains:serial
fbtoken
pubkey
- Parameters
param (dict) – dict of initialization parameters
- Returns
nothing