> 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/impersonate.md).

# Impersonate

Customisable object selector.

## Introduction

The Impersonate selector is responsible for presenting a list of objects (in a grid) for the user to select from.

The Impersonate selector completes when the user has selected an option.

Can be nestled with other authenticators, selectors and [chain](/access/key-components/authenticators/flow-control/chain.md)s.

## Configuration

{% hint style="info" %}
**Authenticator type:** `Impersonate`
{% 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>pipe_id</code></td><td>Reference to the pipe responsible for collecting the data to be presented in the grid.</td><td>N/A</td><td>true</td></tr><tr><td><code>identifier_attribute</code></td><td>What attribute serves as the selected identifier.</td><td><code>"sAMAccountName"</code></td><td>false</td></tr><tr><td><code>selected_id_parameter</code></td><td>Name of attribute where selected identifier will be put.</td><td><code>"object_id"</code></td><td>false</td></tr><tr><td><code>include_self</code></td><td>If the authenticated user should be a selectable option. Enables the 'Login as myself' button.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>show_filtering</code></td><td>Enable filtering in UI.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>values</code></td><td>See <a href="#values">Values</a> below.</td><td>N/A</td><td>true</td></tr><tr><td><code>exec_if</code></td><td>An expression that determins if this authenicator should be executed or not. If left unconfigured, the authenticator will execute.</td><td>N/A</td><td>false</td></tr><tr><td><code>auto_select</code></td><td>Automatic selection if only one option is available.</td><td>false</td><td>false</td></tr><tr><td><code>webroot_dir</code></td><td>See common authenticator configuration</td><td>web/authenticator/impersonate_selector</td><td>false</td></tr><tr><td><code>custom_identifier</code></td><td>Tag used for event separation</td><td>N/A</td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example 1" %}

```json
// Use case - To act on behalf of someone else
// Supported by default together with Fortified ID Password reset same Fortified ID Enrollment.
// Function is supported to be used for any SAML SP application.
{
  "id": "impersonate",
  "type": "Impersonate",
  "display_name": "Impersonate",
  "config": {
    "base_path": "${globals.default_login_suffix}",
    "expiry": "PT1S",
    "overlay_dir": "${globals.default_overlay_dir}",
    "exec_if": "mv.containsAny(exports.spEntityID, 'https://dev.fortifiedid.se/pwdreset/', 'https://dev.fortifiedid.se/enrollment/')",
    "pipe_id": "impersonate_selector_pipe",
    "values": [
      {
        "key": "displayName",
        "label": "label1"
      },
      {
        "key": "sAMAccountName",
        "label": "label2"
      },
      {
        "key": "mail",
        "label": "label3"
      }
    ],
    "show_filtering": true,
    "include_self": true,
    "custom_identifier": "FortifiedID_Test",
    "identifier_attribute": "mail",
    "selected_id_parameter": "object_id"
  },
  "description": "The Impersonate selector is responsible for presenting a list of objects (in a grid) for the user to select from."
}   
```

{% endtab %}

{% tab title="Example 2" %}

```json
// Use case - Choose persona
// If your login is associated with multiple accounts, select the account you want to log in with.
{
  "id": "choose_persona",
  "type": "Impersonate",
  "display_name": "Choose persona",
  "config": {
    "base_path": "${globals.default_login_suffix}",
    "expiry": "PT1S",
    "overlay_dir": "${globals.default_overlay_dir}",
    "pipe_id": "choose_persona_pipe",
    "auto_select": true,
    "values": [
      {
        "key": "displayName",
        "label": "ChoosePersonaName"
      },
      {
        "key": "sAMAccountName",
        "label": "ChoosePersonaUserID"
      },
      {
        "key": "mail",
        "label": "ChoosePersonaMail"
      }
    ],
    "show_filtering": true,
    "include_self": false,
    "custom_identifier": "FortifiedID_Test",
    "identifier_attribute": "mail",
    "selected_id_parameter": "mail"
  },
  "description": "The Impersonate selector is responsible for presenting a list of objects (in a grid) for the user to select from."
}
```

{% endtab %}
{% endtabs %}

### Values

The values array represents the columns to be shown in the grid.

{% 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>key</code></td><td>Item parameter. The value will be presented in the column for each object.</td><td></td><td>true</td></tr><tr><td><code>label</code></td><td>Column label translation key.</td><td></td><td>true</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"values":[
         {
            "key":"displayName",
            "label":"label1"
         },
         {
            "key":"givenName",
            "label":"label2"
         },
         {
            "key":"sAMAccountName",
            "label":"label3"
         },
         {
            "key":"mail",
            "label":"label4"
         },
         {
            "key":"cn",
            "label":"label5"
         }
      ]
```

{% endtab %}
{% endtabs %}

## Data exposed to global state

When a value is selected, the Impersonate authenticator is marked as done and populates the configured `selected_id_parameter` property with the identifier value obtained from the selection.

## Logging

WEB\_100040("Impersonate selector completed")

* IDENTIFIER (user trace id)
* CUSTOMER\_IDENTIFIER (if configured)
* SOURCE\_USER\_NAME (id of selected object if anything selected, pipe not empty)
* SOURCE\_ADDRESS (ip of the remote session)
* AUTHENTICATOR\_ID (id + display\_name of authenticator)

WEB\_100041("Impersonate selector completed - self selected")

* IDENTIFIER (user trace id)
* CUSTOMER\_IDENTIFIER (if configured)
* SOURCE\_ADDRESS (ip of the remote session)
* AUTHENTICATOR\_ID (id + display\_name of authenticator)

## 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 %}

## Translation keys

Default translations provided:

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

```json
{
  "impersonate_selector.header": "Choose",
  "impersonate_selector.paragraph": "Choose a user to impersonate",
  "impersonate_selector.label1": "Label 1",
  "impersonate_selector.label2": "Label 2",
  "impersonate_selector.label3": "Label 3",
  "impersonate_selector.label4": "Label 4",
  "impersonate_selector.label5": "Label 5",
  "impersonate_selector.label6": "Label 6",
  "impersonate_selector.label7": "Label 7",
  "impersonate_selector.label8": "Label 8",
  "impersonate_selector.label9": "Label 9",
  "impersonate_selector.label10": "Label 10",
  "impersonate_selector.error": "An error occurred",
  "impersonate_selector.cancel": "Cancel",
  "impersonate_selector.search": "Search",
  "impersonate_selector.search.no_results": "Search returned no results",
  "impersonate_selector.self_button": "Login as myself",
  "impersonate_selector.processing": "Your selection is being processed, please wait ...",
  "allow-cookies-header": "Allow cookies",
  "allow-cookies-body": "To save your language settings on this device you need to allow cookies.",
  "allow-cookies-button": "Allow cookies",
  "allow-cookies-dismiss": "Dismiss",
  "table.page": "Page {{pageIndex}} of {{pageCount}}",
  "table.select_placeholder": "Select...",
  "change_language": "Change language",
  "table.export": "Export",
  "table.no_results": "No results",
  "authentication.help_text": ""
}

```

#### Swedish, assets/locales/sv.json

```json
{
  "impersonate_selector.header": "Välj",
  "impersonate_selector.paragraph": "Välj en användare att logga in som",
  "impersonate_selector.label1": "Rubrik 1",
  "impersonate_selector.label2": "Rubrik 2",
  "impersonate_selector.label3": "Rubrik 3",
  "impersonate_selector.label4": "Rubrik 4",
  "impersonate_selector.label5": "Rubrik 5",
  "impersonate_selector.label6": "Rubrik 6",
  "impersonate_selector.label7": "Rubrik 7",
  "impersonate_selector.label8": "Rubrik 8",
  "impersonate_selector.label9": "Rubrik 9",
  "impersonate_selector.label10": "Rubrik 10",
  "impersonate_selector.error": "Ett fel har inträffat",
  "impersonate_selector.cancel": "Avbryt",
  "impersonate_selector.search": "Sök",
  "impersonate_selector.search.no_results": "Sökningen gav inga resultat",
  "impersonate_selector.self_button": "Logga in som mig själv",
  "impersonate_selector.processing": "Ditt val behandlas, vänta ...",
  "allow-cookies-header": "Tillåt cookies",
  "allow-cookies-body": "Vill du spara dina språkinställningar på denna enhet behöver du tillåta cookies",
  "allow-cookies-button": "Tillåt cookies",
  "allow-cookies-dismiss": "Avfärda",
  "table.page": "Sida {{pageIndex}} av {{pageCount}}",
  "table.select_placeholder": "Välj...",
  "change_language": "Byt språk",
  "table.export": "Exportera",
  "table.no_results": "Inget resultat",
  "authentication.help_text": ""
}

```


---

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