14.2.1.2.16. SMS Token

class edumfa.lib.tokens.smstoken.SmsTokenClass(db_token)

The SMS token sends an SMS containing an OTP via some kind of gateway. The gateways can be an SMTP or HTTP gateway or the special sipgate protocol. The Gateways are defined in the SMSProvider Modules.

The SMS token is a challenge response token. I.e. the first request needs to contain the correct OTP PIN. If the OTP PIN is correct, the sending of the SMS is triggered. The second authentication must either contain the OTP PIN and the OTP value or the transaction_id and the OTP value.

Example 1st Authentication Request:

POST /validate/check HTTP/1.1
Host: example.com
Accept: application/json

user=cornelius
pass=otppin

Example 1st response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "detail": {
     "transaction_id": "xyz"
   },
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "status": true,
     "value": false
   },
   "version": "eduMFA unknown"
 }

After this, the SMS is triggered. When the SMS is received the second part of authentication looks like this:

Example 2nd Authentication Request:

POST /validate/check HTTP/1.1
Host: example.com
Accept: application/json

user=cornelius
transaction_id=xyz
pass=otppin

Example 1st response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "detail": {
   },
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "status": true,
     "value": true
   },
   "version": "eduMFA unknown"
 }

Create a new HOTP Token object

Parameters:

db_token (DB object) – instance of the orm db object

check_otp(anOtpVal, counter=None, window=None, options=None)

check the otpval of a token against a given counter and the window

Parameters:

passw (string) – the to be verified passw/pin

Returns:

counter if found, -1 if not found

Return type:

int

create_challenge(transactionid=None, options=None)

create a challenge, which is submitted to the user

Parameters:

• transactionid – the id of this challenge

• options – the request context parameters / data You can pass exception=1 to raise an exception, if the SMS could not be sent.

Returns:

tuple of (bool, message and data) bool, if submit was successful message is submitted to the user data is preserved in the challenge reply_dict - additional reply_dict, which is added to the response

classmethod enroll_via_validate(g, content, user_obj)

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

enroll_via_validate_2nd_step(passw, options=None)

This method is the optional second step of ENROLL_VIA_MULTICHALLENGE. It is used in situations like the email token, sms token or push, when enrollment via challenge response needs two steps.

The passw is entered during the first authentication step and it contains the email address.

So we need to update the token with the email address and we need to create a new challenge for the final authentication.

Parameters:

options

Returns:

static get_class_info(key=None, ret='all')

returns all or 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

:rtype : s.o.

static get_class_prefix()

Return the prefix, that is used as a prefix for the serial numbers. :return: oath

static get_class_type()

return the generic token class identifier

is_challenge_request(passw, user=None, options=None)

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 HOTP-Token

Parameters:

• passw – password, which might be pin or pin+otp

• options – dictionary of additional request parameters

Returns:

returns true or false

mode = ['challenge']

prepare_verify_enrollment()

This is called, if the token should be enrolled in a way, that the user needs to provide a proof, that the server can verify, that the token was successfully enrolled. The email token needs to send an email with OTP.

The returned dictionary is added to the response in “detail” -> “verify”.

Returns:

A dictionary with information that is needed to trigger the verification.

update(param, reset_failcount=True)

process initialization parameters

Parameters:

param (dict) – dict of initialization parameters

Returns:

nothing