With QR or "app-switch"

Configuration

This is the configuration for the TaskViewAuthenticator

Note

Authenticator type: TaskViewAuthenticator

Common Authenticator configuration can be found here.

Properties

Name	Description	Default value	Mandatory
internal_http_destination	ID of the internal http client used to talk with backend.	"default"	false
username_parameter	Parameter to where the username is exported.	"username"	false
server_api_url	Address to the mobile server api module.	N/A	true
timeout_seconds	Time to live before the authenticator expires (0 is forever)	0	false
task_form	The task-form to be used in the authentication.	N/A	true
webroot_dir	See common authenticator configuration	web/mobileid/taskviewauthenticator	false

Example

{
  "id": "myauth01",
  "type": "TaskViewAuthenticator",
  "config":
  {
    "server_api_url":"http://<server_url>/mos",
    "context_path" : "/login/authn/login",
    "success_location": "http://<success_url>",
    "failure_location": "/login/authn/login/logout",
    "cancel_location": "/login/authn/login/logout",
    "task_form":
    {
          "elements":
          [
              {"id":"1","type":"label","value":"Confirm your login"},
              {"id":"2","type":"button_confirm","value":"Confirm"},
              {"id":"3","type":"button_reject","value":"Reject"}
          ]
    }
  }
}

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
init	Create the task and obtain the activation URL. Send it when the view loads.
poll	Fetch the current task state.
cancel	Cancel the task.

Note

This authenticator uses init and poll rather than the start and state messages used by most credential validators.

Init

Creates an unassigned task with the configured form and timeout, and answers with the activation URL to present as a QR code or an app-switch link.

Init is idempotent. When a task already exists for the session, the existing activation URL is returned instead of creating a new task, so a browser reload does not start over.

Request

{
    "type": "init"
}

Response

{
    "type": "init",
    "success": true,
    "data": {
        "activation_url": "<activation-url>"
    }
}

Errors

A failure message with the reason Failed to create task: followed by the underlying cause.

Poll

Fetch the current task state. Poll until the state is final.

Request

{
    "type": "poll"
}

Response

{
    "type": "poll",
    "success": true,
    "data": {
        "state": "opened",
        "activation_url": "<activation-url>"
    }
}

Errors

A failure message with the reason Failed to check task state.

Caution

The poll response for a confirmed task is still a poll message and carries no redirect location. Once the state is confirmed the user is authenticated, and the view completes the step by requesting the view URL again with GET, which lets the authenticator redirect onward.

Cancel a request

A request can be canceled at any time. This cancels the task and answers with a cancel message carrying the location to return to.

{
    "type": "cancel"
}

Response from server

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

The body is a JSON message whose data carries the task state and activation_url, or a cancel or failure message as described in Web Authenticator API.

Possible status messages

One of the following values is returned in data.state.

State	Meaning
unassigned	The task has been created and no device has picked it up. Show the QR code.
pending	A device has been assigned the task but has not opened it. Show the QR code.
opened	The user has opened the task in the app. Show a progress indicator.
confirmed	The user confirmed. The authentication is complete.
rejected	The user rejected the task. The authenticator fails.
cancelled	The task was cancelled. The authenticator fails.
expired	The task timed out after timeout_seconds. The authenticator fails.

Logging

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

Event ids are:

• MOBILE_ID_100101("MobileID authentication started")
  • IDENTIFIER (session trace id)
• MOBILE_ID_100102("MobileID authentication completed")
  • IDENTIFIER (session trace id)
  • SOURCE_USER_NAME (user subject)
• MOBILE_ID_100103("MobileID authentication rejected")
  • IDENTIFIER (session trace id)
• MOBILE_ID_100104("MobileID authentication canceled")
  • IDENTIFIER (session trace id)
• MOBILE_ID_100105("MobileID authentication expired")
  • IDENTIFIER (session trace id)

Data exposed to global state

After a user completes a transaction, the authenticator is marked as done. Data from the authentication response is then put into the global state, replacing existing values:

• "username_parameter" set to user subject