Impersonate with search

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

Configuration

Note

Authenticator type: ImpersonateWithSearch

Common Authenticator configuration can be found here.

Properties

Name	Description	Default	Mandatory
pipe_id	Reference to the pipe responsible for collecting the data to be presented in the grid. Request parameter "search" contains the value from the search input field.	N/A	true
identifier_attribute	What attribute serves as the selected identifier.	"sAMAccountName"	false
selected_id_parameter	Name of attribute where selected identifier will be put.	"object_id"	false
include_self	If the authenticated user should be a selectable option. Enables the 'Login as myself' button.	false	false
show_filtering	Enable filtering in UI.	true	false
values	See Values below.	N/A	true
exec_if	An expression that determins if this authenicator should be executed or not. If left unconfigured, the authenticator will execute.	N/A	false
webroot_dir	See common authenticator configuration	"web/authenticator/impersonate_selector"	false

Example

{
   "id":"auth00_select_object",
   "type":"ImpersonateWithSearch",
   "config":{
      "base_path":"/test/authn",
      "pipe_id":"search_pipe",
      "values":[
         {
            "key":"role",
            "label":"label1"
         },
         {
            "key":"givenName",
            "label":"label2"
         },
         {
            "key":"mail",
            "label":"label3"
         }
      ],
      "custom_identifier":"FortifiedID",
      "identifier_attribute":"sAMAccountName",
      "selected_id_parameter":"object_id",
      "include_self":false,
      "show_filtering":true,
      "webroot_dir":"web/authenticator/impersonate_selector"
   }
}

Values

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

Properties

Name	Description	Default	Mandatory
key	Item parameter. The value will be presented in the column for each object.		true
label	Column label translation key.		true

Example

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

Data exposed to global state

When a value is selected, the ImpersonateWithSearch 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 (subject of authenticated user)
  • SOURCE_ADDRESS (ip of the remote session)

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 columns to present. No rows are returned; use search to populate them.
search	Search for rows to present.
action	Select a row, or select oneself.
cancel	Cancel the authentication.

Init (request+response)

Init must be sent before or while the view is loading. The response contains the columns to render and the rows the user can choose from.

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

• Browser reload (user refreshes page)
• Browser back (user navigates back to the view)

Request

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

Response

{
  "type": "init",
  "success": true,
  "data": {
    "columns": ["<column-label>"],
    "self": false,
    "make_myself_selectable": false,
    "filter": true,
    "search": true,
    "object_data": [
      {
        "id": "<row-id>",
        "<column-label>": "<value>"
      }
    ]
  }
}

Properties

Name	Description
columns	Column labels, in the order they are configured in values. Each row in object_data carries one property per label.
self	Whether the user may select themselves. Mirrors the include_self configuration.
make_myself_selectable	Same value as self.
filter	Whether the view should offer client-side filtering. Mirrors the show_filtering configuration.
search	Always true. Tells the view that rows are fetched with the search message rather than returned by init.
object_data	Rows to present. id is a per-session identifier that must be sent back in action; it is not the underlying object identifier.

Note

Init answers with a complete message instead when there is nothing to choose from. The view must follow the supplied location in that case.

Action (request+response)

The action message selects a row. This message is triggered by a user action. Use the id from object_data; identifiers from an earlier init in the same session are not valid.

Request

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

Response

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

Errors

Reason	Description
Selected 'id' is missing	No id was supplied, or the supplied id is not one returned by the current init.

When the user is allowed to select themselves, the view sends a self flag instead of an id. The response is the same complete message.

Search (request+response)

The search message runs the configured search pipe and returns the matching rows. The response is of type init, not search, and replaces the rows currently shown.

Request

{
  "type": "search",
  "data": {
    "search": "<search-term>"
  }
}

Response

{
  "type": "init",
  "success": true,
  "data": {
    "columns": ["<column-label>"],
    "object_data": [
      {
        "id": "<row-id>",
        "<column-label>": "<value>"
      }
    ]
  }
}

Caution

Each search issues new row identifiers and invalidates the previous ones. Send the id from the most recent response in action.

Cancel (request+response)

Cancel is available at any time and is handled as described in Web Authenticator API.

{
  "type": "cancel"
}

Translation keys

Default translations provided:

English, assets/locales/en.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

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