> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/access/key-components/authenticators/flow-control/selector.md).

# 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 [chain](/access/key-components/authenticators/flow-control/chain.md)s.

## Configuration

{% hint style="info" %}
**Authenticator type:** `Selector`
{% endhint %}

Common Authenticator configuration can be found [here](/access/key-components/authenticators/common-configuration.md).

{% tabs %}
{% tab title="Properties" %}

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>base_path</code></td><td>The base path for this authenticator <em>and</em> used to construct the path to the selected authenticator. (see <a href="#routing">Routing</a>)</td><td></td><td>false</td></tr><tr><td><code>options</code></td><td>List of <a href="#option">option</a>s to be presented to the user. A selector without options will block the authentication and therefore at least one option must be present.</td><td><code>[]</code></td><td>false</td></tr><tr><td><code>auto_select</code></td><td>Turns off automatic selection if only one option is available.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>auto_complete</code></td><td>Turns on automatic authentication completion (flow continues) if no options are available (selector is not displayed).</td><td><code>false</code></td><td>false</td></tr><tr><td><code>lazy_expiry</code></td><td>Turns on automatic re-selection of previously selected option when authenticator has expired (selector is not displayed).<br>Note! include_expr must be evaluated for this option before reselecting it.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>verbose</code></td><td>Turns on extended trace logging. Use for troubleshooting only.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>webroot_dir</code></td><td>See common authenticator documentation</td><td>web/authenticator/selector</td><td>false</td></tr><tr><td><code>reset_on_selected_cancel</code></td><td>Set to <code>true</code> when cancel in selectable method should return to the Selector instead of external cancel page from <code>cancel_location</code></td><td><code>false</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
    "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"
      } ]
    }
  }
```

{% endtab %}
{% endtabs %}

## Option

An option represents a user selectable option in the view.

{% tabs %}
{% tab title="Properties" %}

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>id</code></td><td>Configuration unique identifier for option.</td><td></td><td>true</td></tr><tr><td><code>target</code></td><td>Id of authenticator implementing the option.</td><td></td><td>true</td></tr><tr><td><code>label</code></td><td>Option label. Text or translation key.</td><td></td><td>true</td></tr><tr><td><code>logo</code></td><td>Logo URL for option. Preferably monochrome svg logo.</td><td></td><td>false</td></tr><tr><td><code>enabled</code></td><td>Flag controlling if the option is enabled or disabled.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>include_expr</code></td><td>Predicate expression controlling if option should be included (displayed/selectable) or not.</td><td><code>true</code></td><td>false</td></tr><tr><td>order</td><td>Sort order for presentation.</td><td>MAX.Integer</td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"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
      }
    ]
```

{% endtab %}
{% endtabs %}

#### 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.

{% hint style="info" %}
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`
{% endhint %}

The following scopes are available:

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th data-type="checkbox">Case-insensitive</th></tr></thead><tbody><tr><td><code>request</code></td><td>The current authentication request including HTTP <code>headers</code> and <code>params</code></td><td>false</td></tr><tr><td><code>session</code></td><td>The current session.</td><td>false</td></tr><tr><td><code>state</code></td><td>The current authentication state.</td><td>false</td></tr><tr><td><code>exports</code></td><td>Exported properties.</td><td>false</td></tr><tr><td><code>input</code></td><td>Authenticator input</td><td>false</td></tr><tr><td><code>subject</code></td><td>Current authentication subject (not a scope)</td><td>false</td></tr></tbody></table>

### 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](/access/key-components/authenticators/web-authenticator-api.md).

### 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)

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}

{% tab title="Response" %}

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

{% endtab %}

{% tab title="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`.              |
| {% endtab %}                  |                                                                                                          |
| {% endtabs %}                 |                                                                                                          |

#### Action (request+response)

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

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}

{% tab title="Response" %}

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

{% endtab %}

{% tab title="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`. |
|                              |                                                                                                           |
| {% endtab %}                 |                                                                                                           |
| {% endtabs %}                |                                                                                                           |

#### 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.

{% tabs %}
{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}

## 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
```

<figure><img src="https://content.gitbook.com/content/rgBDaXqun2PdSBf0pgQt/blobs/tPs0hufGazhCpDG7Ujhu/adfs.svg" alt=""><figcaption><p>adfs.svg</p></figcaption></figure>

|              |                                                                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
|              |                                                                                                                                             |
| `bankid.svg` | <img src="https://content.gitbook.com/content/rgBDaXqun2PdSBf0pgQt/blobs/LwJJlIk5Z9rIyiMFiXqS/bankid.svg" alt="" data-size="line">. f f     |
|              | <img src="https://content.gitbook.com/content/rgBDaXqun2PdSBf0pgQt/blobs/c55hYocV4yNj9XoRsvLi/certificate.svg" alt="" data-size="original"> |

<figure><img src="https://content.gitbook.com/content/rgBDaXqun2PdSBf0pgQt/blobs/c55hYocV4yNj9XoRsvLi/certificate.svg" alt="" width="75"><figcaption></figcaption></figure>

#### Example

<figure><img src="https://content.gitbook.com/content/rgBDaXqun2PdSBf0pgQt/blobs/c55hYocV4yNj9XoRsvLi/certificate.svg" alt=""><figcaption></figcaption></figure>

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

#### Custom logos

For custom logos use [overlay method](https://docs.fortifiedid.se/common/overlay) and refer to the image location as above

## Translation keys

Default translations provided:

#### English, assets/locales/en.json

```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

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

```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fortifiedid.se/access/key-components/authenticators/flow-control/selector.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.