8. Challenge Response¶
Starting with version 2.6 all tokens have the possibility to do challenge response.
In detail this can be a token specific behaviour. The usual steps are as follows:
The user does a first authentication step,
the LinOTP server sends some kind of a challenge and,
then the user needs to do a second authentication step.
The OCRA token is a real challenge response token, where the OTP value is calculated based on a challenge. But the challenge response mechanism is also used for the SMS and the e-mail token and can be used for ordinary push button tokens like HOTP and TOTP.
Note
For tokens like HOTP and TOTP that are not challenge response token by design, you need to set a policy (Challenge Response) to activate the challenge response behaviour.
8.1. HOTP and TOTP Tokens¶
Also other tokens like the HMAC/HOTP and TOTP support challenge response.
In this case the challenge is triggered by providing only the OTP PIN to the /validate/check API:
/validate/check?user=frank&pass=mypin
LinOTP verifies that this is the valid PIN for frank’s token and response with addition information:
"detail": {
"transactionid": "041621212047",
"message": "Please enter your otp value: "
},
The second in the authentication would be to pass the requested information (the OTP value) to the LinOTP server. This will be done this way:
/validate/check?user=frank&transactionid=041621212047&pass=698432
LinOTP will grant access, if the correct OTP value was provided.
Note
The second authentication step does not provide the OTP PIN anymore. But the transaction ID from the first response is needed to proof, that the correct OTP PIN was presented earlier - in the first step.
8.2. SMS and e-mail¶
The workflow for the SMS and e-mail token are the same as described in HOTP and TOTP Tokens.
The interesting thing is, that the LinOTP server can send an SMS or an e-mail, if the OTP PIN provided in the first step, was correct.
The user then can receive the SMS or the e-mail and provide the sent OTP value in the second authentication step.
8.3. Configure Challenge Message¶
Every type of token has a built in challenge message. The message for the SMS token for example is “sms submitted”. Beginning with LinOTP version 2.10.1 it is possible to configure the messages for each type of challenge response tokens.
The setting is performed via the LinOTP API. In general the call looks like this:
https://LINOTP/system/setConfig?session=COOKIE&TOKENTYPE_CHALLENGE_PROMPT=MESSAGE
Here is an example how to change the challenge message for SMS token:
https://LINOTP/system/setConfig?session=7fc4f946a91841737f510ed8eae6763d9ff7727aab44239831550d13bd7a8d46
&SMS_CHALLENGE_PROMPT=Your SMS has been sent
Hint
The cookie can be extracted from a valid /manage session in the web browser.
Details about receiving the cookie and how to use the LinOTP API can be found here:
8.4. RADIUS¶
If you are using a RADIUS client, that is capable of interpreting the ACCESS_CHALLENGE packet, this work completely transparent.
The user would enter his username and OTP PIN in the first step. These values are sent to the LinOTP server. The LinOTP server responds with a transaction ID and a message “Please enter your otp value”. The rlm_linotp FreeRADIUS module sends an ACCESS_CHALLENGE packet back to the client and the RADIUS client displays the message and asks for the OTP value.
The user only has to enter the OTP received value during the second step.
Note
Please note that challenge response needs to be activated for tokens other than OCRA, SMS and e-mail. See Challenge Response for how to do this.
8.5. Test Challenge Response¶
Starting with version 2.10 LinOTP offers a test page for challenge response tokens:
https://LINOTP/auth/challenge-response
Enter username[@realmname] and OTP PIN (the PIN depends on the otppin policy, realmname is necessary for users in non-default realm) and press trigger. Now the OTP should be received depending on the used token (SMS, Voice, etc.). Enter the OTP in the “Submit response” section. Then press submit. A pop up appears which tells whether the authenication was successful or not.
