Custom login sequence

This is for:

In this article

Custom login sequence schema
Reference
Custom login sequence example

A custom login sequence is a JSON configuration which lets administrators build authentication processes that enhance and customize the login process. It’s used for either a Web source or a Sitemap source.

The standard Coveo form authentication login sequence can handle many use cases without a custom login sequence, including several authentication provider login pages (e.g., OneLogin, Google, Salesforce). Always try authenticating without a custom login sequence first. You should only start working on a custom login sequence when you’re sure your form authentication details (i.e., login address, user credentials) are accurate and that the standard form authentication doesn’t work.

The custom login sequence is a JSON object whose specifications are defined in the following schema.

{
  "name": <STRING>,                            ->  REQUIRED: The name of the login sequence.
  "url": <STRING>,                             ->  REQUIRED: The URL of the authentication form.
                                                   Wildcards ("*") can be used. The login sequence is only
                                                   performed if the authenticator is redirected to this URL.
  "steps": [                                   ->  REQUIRED: The steps to perform. The maximum number of steps
    {                                              in a login sequence is 5. Only one step may be used to enter
                                                   the password in an input element.
      "name": <STRING>,                        ->  The name to identify the current step.
      "waitDelayInMilliseconds": <INT>,        ->  Wait time in milliseconds before executing the current step.
      "actions": [                             ->  REQUIRED: The actions to perform in the current step. The
        {                                          maximum number of actions in a step is 10.
          "waitDelayInMilliseconds": <INT>,    ->  Wait time in milliseconds before executing the current
                                                   action.
          "type": <STRING>, 
                                               ->  REQUIRED: The user action type to perform (i.e., "Click",
                                                   "JavaScriptClick", "Clear", "SendKeys", etc.).
          "value": <STRING>, 
                                               ->  REQUIRED WITH ACTION TYPE "SendKeys": The value to use
                                                   when performing the action.
          "elementIdentifier": {               ->  REQUIRED WITH MANY ACTION TYPES: The tag or attribute name
                                                   and values to identify the target form element.
            "identifier": <STRING>,            ->  REQUIRED WITH elementIdentifier: The unique identifier of
                                                   the form element (i.e., tag name attribute value,
                                                   tag ID attribute value, tag name, etc.).
            "type": <STRING>, 
                                               ->  REQUIRED WITH elementIdentifier: The type of the form
                                                   element (i.e., "Default", "Username", or "Password").
            "findType": <STRING> 
                                               ->  REQUIRED WITH elementIdentifier: The method to find the
                                                   form element by (i.e., "Name", "Id", "TagName", etc.).
          }
        }
      ]
    }
  ]
}

	See Action `type` values.
	See `SendKeys`.
	See Element identifier `type` values.
	See Element identifier `findType` values.

Reference

Action `type` values

Coveo custom login sequences support keyboard and pointer actions.

With many action types, the target element must meet certain preconditions before the action is actually attempted. The source first tries to scroll into view the target element, if necessary. Then, the source ensures the element is in view, displayed, and can be interacted with, before executing the action.

`Clear`

Checks preconditions and then clears the content of the input element.

Example

{
  "type": "Clear",
  "elementIdentifier": {
    "identifier": "<ID_ATTRIBUTE_VALUE_OF_USERNAME_INPUT_ELEMENT>",
    "type": "Username",
    "findType": "Id"
  }
}

`SendKeys`

Checks preconditions and then types the text specified in the value parameter into the target input element.

Example

{
  "type": "SendKeys",
  "value": "<TEXT_TO_TYPE_IN_INPUT_ELEMENT>",
  "elementIdentifier": {
    "identifier": "<NAME_ATTRIBUTE_VALUE_OF_TARGET_INPUT_ELEMENT>",
    "type": "Default",
    "findType": "Name"
  }
}

When the element identifier type is Username, the source automatically sets the value to the username specified in the form authentication credentials. Similarly, when the element identifier type is Password, the source automatically sets the value to the password specified in the form authentication credentials.

Example

{
  "type": "SendKeys",
  "elementIdentifier": {
    "identifier": "<NAME_ATTRIBUTE_VALUE_OF_THE_USERNAME_INPUT_ELEMENT>",
    "type": "Username",
    "findType": "Name"
  }
}

`Click`

Simulates a mouse click on an element.

For interactability preconditions to be met, the target element must have a height and width greater than 0.

Example

{
  "type": "Click",
  "elementIdentifier": {
    "identifier": "<ID_ATTRIBUTE_VALUE_OF_USERNAME_INPUT_ELEMENT>",
    "type": "Username",
    "findType": "Id"
  }
}

`JavaScriptClick`

Simulates a mouse click on an element, but it doesn’t check preconditions.

Example

{
  "type": "JavaScriptClick",
  "elementIdentifier": {
    "identifier": "<ID_ATTRIBUTE_VALUE_OF_TARGET_ELEMENT>",
    "type": "Default",
    "findType": "Id"
  }
}

`Submit`

Checks preconditions and then performs the action of submitting the form.

The Click action type is recommended over Submit.

Example

{
  "type": "Submit",
  "elementIdentifier": {
    "identifier": "idSIButton9",
    "type": "Default",
    "findType": "Id"
  }
}

`PressTab`

Action type that simulates pressing the Tab key. PressTab can often be used to set the focus on the password input element after filling out the username input element. This action type requires no action value, nor elementIdentifier.

Usage

{
  "type": "PressTab"
}

`PressSpace`

Action type that simulates pressing the Space key. This action type requires no action value, nor elementIdentifier.

Usage

{
  "type": "PressSpace"
}

`PressEnter`

Action type that simulates selecting Enter. This action type requires no action value, nor elementIdentifier.

Usage

{
  "type": "PressEnter"
}

Element identifier `type` values

`Username`

Identifies the <input> element in which users enter their username or email address to authenticate with. When used in a SendKeys action, the source automatically types the form authentication username in the <input> element.

`Password`

Identifies the <input> element in which users enter their password. When used in a SendKeys action, the source automatically types the form authentication password in the <input> element.

`Default`

Use Default as the element identifier type value for all non-username, non-password elements used in the login sequence.

Element identifier `findType` values

`Name`

Used to select an element based on its name attribute value.

Example

To select the <input name="user"></input> HTML element in a form, use:

"elementIdentifier": {
  "identifier": "user",
  "type": "Username",
  "findType": "Name"
}

`Id`

Used to select an element based on its id attribute value.

Example

To select the <input id="userid"></input> HTML element in a form, use:

"elementIdentifier": {
  "identifier": "userid",
  "type": "Username",
  "findType": "Id"
}

`TagName`

Used to select an element based on the tag name.

Example

To select the <button id="submit"></button> HTML element in a form, use:

"elementIdentifier": {
  "identifier": "button",
  "type": "Default",
  "findType": "TagName"
}

Leading practice

Although this could work, other more distinctive selection methods should be used.

`ClassName`

Used to select an element based on its class attribute value.

Example

To select the <button class="o-auth__toggle-external-login js-o-auth__toggle-external-login">Show External Login</button> HTML element in a form, use:

"elementIdentifier": {
  "identifier": "o-auth__toggle-external-login",
  "type": "Default",
  "findType": "ClassName"
}

`CssSelector`

Used to select an element by specifying a CSS selector.

Example

To select the <input id="email-address"></input> HTML element in a form, use:

"elementIdentifier": {
  "identifier": "input#email-address",
  "type": "Username",
  "findType": "CssSelector"
}

`XPath`

Used to select an element by specifying an XPath expression.

Example

To select the <input placeholder="Email"></input> HTML element in a form, use:

"elementIdentifier": {
  "identifier": "//input[@placeholder='Email']",
  "type": "Username",
  "findType": "XPath"
}

{
  "url": "https://login.microsoftonline.com",
  "name": "Microsoft Online login sequence",
  "steps": [
    {
      "waitDelayInMilliseconds": 1000,
      "actions": [
        {
          "type": "Click",
          "elementIdentifier": {
            "identifier": "loginfmt",
            "type": "Username",
            "findType": "Name"
          }
        },
        {
          "type": "Clear",
          "elementIdentifier": {
            "identifier": "loginfmt",
            "type": "Username",
            "findType": "Name"
          }
        },
        {
          "type": "SendKeys",
          "elementIdentifier": {
            "identifier": "loginfmt",
            "type": "Username",
            "findType": "Name"
          }
        },
        {
          "type": "PressEnter"
        }
      ]
    },
    {
      "actions": [
        {
          "type": "Click",
          "elementIdentifier": {
            "identifier": "passwd",
            "type": "Password",
            "findType": "Name"
          }
        },
        {
          "type": "Clear",
          "elementIdentifier": {
            "identifier": "passwd",
            "type": "Password",
            "findType": "Name"
          }
        },
        {
          "type": "SendKeys",
          "elementIdentifier": {
            "identifier": "passwd",
            "type": "Password",
            "findType": "Name"
          }
        },
        {
          "type": "PressEnter"
        }
      ]
    },
    {
      "actions": [
        {
          "type": "Click",
          "elementIdentifier": {
            "identifier": "DontShowAgain",
            "type": "Default",
            "findType": "Name"
          }
        },
        {
          "type": "Click",
          "elementIdentifier": {
            "identifier": "idSIButton9",
            "type": "Default",
            "findType": "Id"
          }
        }
      ]
    }
  ]
}