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 endpoints

The 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

  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

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; additional attributes, 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

static get_class_prefix()[source]
static get_class_type()[source]

return the generic token class identifier

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.

  1. step:

    param contains:

    • type

    • genkey

  2. step:

    param contains:

    • serial

    • fbtoken

    • pubkey

Parameters

param (dict) – dict of initialization parameters

Returns

nothing