Selector

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

Note

Authenticator type: Selector

Common Authenticator configuration can be found here.

Properties

Name	Description	Default	Mandatory
base_path	The base path for this authenticator and used to construct the path to the selected authenticator. (see Routing)		false
options	List of options to be presented to the user. A selector without options will block the authentication and therefore at least one option must be present.	[]	false
auto_select	Turns off automatic selection if only one option is available.	true	false
auto_complete	Turns on automatic authentication completion (flow continues) if no options are available (selector is not displayed).	false	false
lazy_expiry	Turns on automatic re-selection of previously selected option when authenticator has expired (selector is not displayed). Note! include_expr must be evaluated for this option before reselecting it.	false	false
verbose	Turns on extended trace logging. Use for troubleshooting only.	false	false
webroot_dir	See common authenticator documentation	web/authenticator/selector	false
reset_on_selected_cancel	Set to true when cancel in selectable method should return to the Selector instead of external cancel page from cancel_location	false	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",
        "order":1,
        "target" : "chain01",
        "label" : "BankID"
      }, {
        "id" : "option02",
        "order":2,
        "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.		true
target	Id of authenticator implementing the option.		true
label	Option label. Text or translation key.		true
logo	Logo URL for option. Preferably monochrome svg logo.		false
enabled	Flag controlling if the option is enabled or disabled.	true	false
include_expr	Predicate expression controlling if option should be included (displayed/selectable) or not.	true	false
order	Sort order for presentation.	MAX.Integer	false

Example

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

Option filtering

An option is first checked against enabled. If enabled is set to false, the option is excluded before include_expr is evaluated. If enabled is omitted, the option is treated as enabled.

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.

When reset_on_selected_cancel returns the user to the Selector after cancelling a selected authenticator, option filtering uses the same application context as the first Selector view. This is important when options depend on values such as exports.app_tag.

// 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')"

// Only include if the entityID of the service equals the configured value.
"include_expr": "str.isEqual(exports.spEntityID, 'https://service.company.org/saml/entityid')"

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.

Note

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	false
session	The current session.	false
state	The current authentication state.	false
exports	Exported properties.	false
input	Authenticator input	false
subject	Current authentication subject (not a scope)	false

Routing

When a user makes a selection, a redirect will occur to the chosen authenticator. The path to the authenticator is constructed by combining base_path with the selected authenticator's ID (specified in target).

Note that base_path is also used to generate the path for the current authenticator. This is intentional, as all authenticators in a flow must share the same path and session (which is managed by the path).

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.

Messages

Message	Purpose
init	Fetch the options to present.
action	Select an option.
cancel	Cancel the selection.

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>",
        "logo" : "<option-logo>"
      }
    ]
  }
}

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>"
  }
}

Cancel (request+response)

Cancel is available at any time and is handled as described in Web Authenticator API. The response carries the location to return to.

{
  "type" : "cancel"
}

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
eduid.svg
efos.svg
eidas.svg
fido.svg
fortified_app.svg
freja.svg
globe.svg
google.svg
id_porten.svg
mfa.svg
microsoft.svg
netid.svg
no_bid.svg
otp.svg
passkey.svg
qr_app.svg
sambi.svg
siths.svg
skolfederation.svg
suomi.svg
svenska_pass.svg
sweden_connect.svg
telia.svg
uid_pwd.svg
yubico.svg

adfs.svg

bankid.svg	. f f

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 occurred",
  "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": ""
}

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",
  "authentication.help_text": "",
  "change_language": ""
}