14.2.1.2.4. eduPUSH Token

class edumfa.lib.tokens.pushtoken.PushTokenClass(db_token)[source]

The Legacy 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 eduMFA.

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://youredumfaserver/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/edupush HTTP/1.1
Host: https://youredumfaserver/

enrollment_credential=<hex nonce>
serial=<token serial>
fbtoken=<Firebase token>
pubkey=<public key>

For more information see:

Create a new token object.

Parameters:

db_token (Token) – A database token object

Returns:

A TokenClass object

class PUSH_ACTION[source]
ALLOW_POLLING = 'edupush_allow_polling'
FIREBASE_CONFIG = 'edupush_firebase_configuration'
MOBILE_TEXT = 'edupush_text_on_mobile'
MOBILE_TITLE = 'edupush_title_on_mobile'
REGISTRATION_URL = 'edupush_registration_url'
SSL_VERIFY = 'edupush_ssl_verify'
TTL = 'edupush_ttl'
WAIT = 'edupush_wait'
classmethod api_endpoint(request, g)[source]

This provides a function which is called by the API endpoint /ttype/edupush 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/edupush HTTP/1.1
Host: https://youredumfaserver

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 are accepted:

    POST /ttype/edupush HTTP/1.1
Host: https://youredumfaserver

serial=<token serial>
nonce=<the actual challenge>
signature=<signature over {nonce}|{serial}>

  • The smartphone can also decline the authentication request, by sending a response to the server:

    POST /ttype/edupush HTTP/1.1
Host: https://youredumfaserver

serial=<token serial>
nonce=<the actual challenge>
decline=1
signature=<signature over {nonce}|{serial}|decline

  • In some cases the Firebase service changes the token of a device. This needs to be communicated to eduMFA through this endpoint (https://github.com/privacyidea/privacyidea/wiki/concept%3A-pushtoken-poll#update -firebase-token):

    POST /ttype/edupush HTTP/1.1
Host: https://youredumfaserver

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/edupush HTTP/1.1
Host: https://youredumfaserver

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 eduMFA 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

client_mode = 'poll'
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 challenge reply_dict, which are displayed in the JSON challenges response.

create_push_token_url(url=None, ttl=10, issuer='eduMFA', serial='mylabel', tokenlabel='<s>', user_obj=None, extra_data=None, user=None, realm=None)[source]
Parameters:

  • url

  • ttl

  • issuer

  • serial

  • tokenlabel

  • user_obj

  • extra_data

  • user

  • realm

Returns:

classmethod enroll_via_validate(g, content, user_obj)[source]

This class method is used in the policy ENROLL_VIA_MULTICHALLENGE. It enrolls a new token of this type and returns the necessary information to the client by modifying the content.

Parameters:

  • g – context object

  • content – The content of a response

  • user_obj – A user object

Returns:

None, the content is modified

static get_class_description()[source]
classmethod 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_title()[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.

static get_policy_group()[source]
static get_push_url_prefix()[source]
classmethod get_pushtoken_add_config(*args, **kwargs)[source]
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

is_multichallenge_enrollable = True
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

use_for_authentication(options)[source]

This method checks, if this token should be used for authentication. Certain token classes could be excluded from the authentication request in certain situations.

Returns True, if the token should be used for authentication. Returns False, if the token should be completely ignored for authentication.

Parameters:

options – This is the option list, that basically contains the Request parameters.

Returns:

classmethod verify_signature(pubkey_obj, sign_data, signature)[source]