Selector

Customisable authentication menu

Introduction

The Selector authenticator is responsible for presenting a list of authentication options for the user to select from (a "menu").

The selector completes when the user selected authentication option (single authenticator or chain) completes.

Selectors can be nested with other selectors and chains.

Configuration

Authenticator type: Selector

Common Authenticator configuration can be found here.

Properties

Name	Description	Default	Mandatory
options	List of options to be presented to the user. A selector without options will block the authentication and therefor at least one option must be present.	[]
auto_select	Turns off automatic selection if only one option is available.	true
auto_complete	Turns on automatic authentication completion (flow continues) if no options is available (selector is not displayed).	false
lazy_expiry	Turns on automatic re-selection of previously selected option when authenticator has expired (selector is not displayed).	false
verbose	Turns on extended trace logging. Use for troubleshooting only.	false

Example

{
    "id" : "select00",
    "type" : "Selector",
    "config" : {
      "base_path" : "/test/authn",
      "webroot_dir" : "web/authenticator/selector",
      "auto_select": true,
      "auto_complete" false,
      "lazy_expiry": false,
      "options" : [ {
        "id" : "option01",
        "target" : "chain01",
        "label" : "BankID"
      }, {
        "id" : "option02",
        "target" : "chain02",
        "label" : "keys.bankid.selector.label"
      } ]
    }
  }

Option

An option represents a user selectable option in the view.

Properties

Name	Description	Default	Mandatory
id	Configuration unique identifier for option.
target	Id of authenticator implementing the option.
label	Option label. Text or translation key.
logo	Logo URL for option. Preferably monochrome svg logo.
include_expr	Predicate expression controlling if option should be included (displayed/selectable) or not.	true

Example

"options" : [
      {
        "id" : "<option-id>",
        "target" : "<authenticator-id>",
        "label" : "<option-text-or-translation-key>",
        "logo" : "<option-logo>" 
      }
    ]

Option filtering

The include predicate is a boolean expression. If the expression is evaluated to true the option is included in the list of available options and displayed to the user.

If filtering results in only one option, automatic selection is performed unless turned off ("auto_select": false). If filtering results in no option an error is displayed unless automatic completion is turned on ("auto_complete": true).

The actual filter is an ECMA-script (JavaScript) that MUST evaluate to true, false or to a boolean function returning true or false.

// Always exclude
"include_expr": "false"

// Only include if session property 'required_auth_level' is greater than 2
"include_expr": "session.required_auth_level > 2"

// Only include if multi-value property 'roles' contains a specific value (a multi
// value is a JavaScript Array)
"include_expr": "exports.roles.includes('admin')"

During expression evaluation data is made available in scopes. A scope is a map (i.e key-values or hash) where values are accessed using a name and plain dot notation.

In JavaScript dot notation is NOT supported for list/array indexing.

Use the following syntax to address an element in a list:

session.roles[0].name

The following scopes are available:

Name	Description	Case-insensitive
request	The current authentication request including HTTP headers and params
session	The current session.
state	The current authentication state.
exports	Exported properties.
input	Authenticator input
subject	Current authentication subject (not a scope)

API

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

Messages

Selector authenticators supports the following messages:

Init (request+response)

Init message must be sent before/during the view is loading. Response contains the options that should be presented to the user.

Init may be called while authenticator is in progress under the following circumstances:

• Callback from selected authenticator

• Browser reload (user refreshes page)

• Browser back (user cancels selected authenticator and navigates back)

Request

{
  "type" : "init",
  "data" : {}
}

Response

{
  "type" : "init",
  "success" : true,
  "data" : {
    "options" : [
      {
        "id" : "<option-id>",
        "target" : "<authenticator-id>",
        "label" : "<option-text-or-translation-key> 
      },
    ]
  }
}

Errors

Reason	Description
Selected authenticator failed	The selected authenticator failed.
Unknown status: <status>	The selected authenticator has an unknown status (Not PENDING, IN_PROGRESS, COMPLETED or FAILED)
Invalid status: <status>	Protocol error. Init called when authenticator is not in status PENDING or IN_PROGRESS.

Action (request+response)

The action message is used for selecting an option. This message is triggered by a user action.

Request

{
  "type" : "action",
  "data" : {
    "selected" : "<option-id>"
  }
}

Response

{
  "type" : "action",
  "success" : true,
  "data" : { 
    "location" : "<path-to-selected-authenticator>"
  }
}

Errors

Reason	Description
Invalid option: <option-id>	An invalid option-id was supplied. Only option-ids from init are valid.
Invalid state	Protocol error. Operation is called in an invalid state, for example if action is called before init.

Complete (response)

The complete response message is sent when the authentication has completed. If message contains a location property; view must redirect user agent to the supplied location.

Response

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

Option logos

There are a number of logos that comes default. All are located in the assets/svg/ folder

adfs.svg
bankid.svg
certificate.svg
efos.svg
eidas.svg
fido.svg
fortified_app.svg
freja.svg
netid.svg
otp.svg
sambi.svg
siths.svg
skolfederation.svg
sweden_connect.svg
telia.svg
yubico.svg

Example

"options" : [
  {
    ...
    "logo" : "assets/svg/sambi.svg" 
  }
]

Custom logos

For custom logos use overlay method and refer to the image location as above

Translation keys

Default translations provided:

English, assets/locales/en.json

{
  "selector.header": "Choose authentication method",
  "selector.error": "An error occured",
  "allow-cookies-body": "To save your language settings on this device you need to approve a language cookie.",
  "allow-cookies-button": "Approve language cookie",
  "change_language": ""
}

Swedish, assets/locales/sv.json

{
  "selector.header": "Välj inloggningsmetod",
  "selector.error": "Ett fel har inträffat",
  "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",
  "change_language": ""
}