OTP validator

Note

Note: If validating an OATH token OTP click here: ref:tokens/oath/

Using tokens when authenticating assumes that the user has a token.
Fortified ID have a product called Fortified ID Enrollment to help user to easily enroll for tokens.

Configuration

Note

Authenticator type: OTP | OTPAuthenticator | OTPValidator

Common Authenticator configuration can be found here.

Properties

Name	Description	Default value	Mandatory
pipe_id	Pipe to use for validation.	N/A	true
pre_pipe_id	Pipe commonly used for sending OTPs.	N/A	false
allowed_otp_retry	Allowed number of times a user is allowed to enter OTP before process is aborted.	2	false
webroot_dir	See common authenticator configuration	web/authenticator/otp_validation	false
custom_identifier	Tag used for event separation	N/A	false

Example

{
  "id": "iodpwd",
  "type": "OTPValidator",
  "config": {
    "base_path": "/saml/authn",
    "context_path": "/saml/authn/otp",
    "pipe_id": "otp_validation_pipe"
  }
}

Caution

Property base_path should not contain the full path when used in conjunction with the Selector, instead, the full URI will be handled by the selector. The full path will be base_path + / + id.

Logging

Apart from system logging, event logging is done when completing and failing a transaction.

Event ids are:

• WEB_100019("OTP validated")

  • IDENTIFIER (user trace id)
  • CUSTOMER_IDENTIFIER (if configured)
  • SOURCE_ADDRESS (ip of the remote session)

• WEB_100020("OTP validation failed")

  • IDENTIFIER (user trace id)
  • CUSTOMER_IDENTIFIER (if configured)
  • SOURCE_ADDRESS (ip of the remote session)

Data sent to validation pipe

On otp-validation, data sent to pipe is:

• otp - entered by user

Data exposed to global state

None

API

API follows the general conventions of the Fortified Web Authenticator API.

General requirements

All requests use the HTTP PUT method with Content-Type: application/json, sent to the directory URL the view was loaded from. The session cookie must be sent with every request.

Messages

Message	Purpose
state	Fetch the current state. Send it when the view loads.
start	Submit the one-time password for validation.
cancel	Cancel the authentication.

Getting state

Send this when the view loads, and after a browser reload. It moves a pending authenticator into progress and reports that the view may collect input.

Request

{
    "type": "state"
}

Response

{
    "status": "ABOUT_TO_START"
}

Note

When pre_pipe_id is configured, the pipe that delivers the one-time password runs as part of the first state request. A view that never sends state will therefore never trigger the SMS or e-mail.

Starting an authentication

Send the one-time password entered by the user.

Request

{
    "type": "start",
    "data": {
        "otp": "<otp>"
    }
}

Response

{
    "type": "complete",
    "success": true,
    "data": {
        "location": "<next-location>"
    }
}

Errors

{
    "status": "ERROR"
}

Returned when the one-time password is missing from the request, when the authenticator is not in progress, or when validation fails. The view should show an error and let the user try again.

Caution

The number of attempts is limited by allowed_otp_retry. When it is exceeded the authenticator fails instead of answering ERROR, and the response is a failure message with the reason OTP validation failed. The view must not offer another attempt after that.

Cancel a request

A request can be canceled at any time. This is done by sending a cancel request.

{
    "type": "cancel"
}

Response from server

Expect HTTP status code 200. Anything else is to be considered an error.

The body is a JSON object. A step that is still in progress answers with a status property; a step that ends the authenticator answers with a complete, cancel, or failure message as described in Web Authenticator API.

Possible status messages

Status	Meaning
ABOUT_TO_START	The authenticator is ready and the view should collect the one-time password.
ERROR	The one-time password was missing or rejected. Attempts remain.

Translation keys

{
  "otp_validation.otp": "One-time password",
  "otp_validation.start_validate": "Verify one-time password",
  "otp_validation.verified": "One-time password verified",
  "otp_validation.redirecting": "Redirecting...",
  "otp_validation.cancel": "Cancel",
  "otp_validation.ERROR": "Wrong one-time password",
  "allow-cookies-body": "To save your language settings on this device you need to approve a language cookie.",
  "allow-cookies-button": "Approve language cookie",
  "authentication.help_text": "",
  "change_language": ""
}

{
  "otp_validation.otp": "Engångslösenord",
  "otp_validation.start_validate": "Verifiera engångslösenord",
  "otp_validation.verified": "Engångslösenord verifierat",
  "otp_validation.redirecting": "Omdirigerar...",
  "otp_validation.cancel": "Avbryt",
  "otp_validation.ERROR": "Felaktigt engångslösenord",
  "allow-cookies-body": "Vill du spara dina språkinställningar på denna enhet behövs ett godkännande av  språk-cookie.",
  "allow-cookies-button": "Godkänn språk-cookie",
  "authentication.help_text": "",
  "change_language": ""
}