Tips for finding Knowledge Articles

  • - Enter just a few key words related to your question or problem
  • - Add Key words to refine your search as necessary
  • - Do not use punctuation
  • - Search is not case sensitive
  • - Avoid non-descriptive filler words like "how", "the", "what", etc.
  • - If you do not find what you are looking for the first time,reduce the number of key words you enter and try searching again.
  • - Minimum supported Internet Explorer version is IE9
Home  >
article

[HOWTO] Configure Centrify's Browser Extension (Advanced)

Privileged Access Service ,  

14 July,21 at 04:41 PM

What is the Centrify Browser Extension (CBE)?

The Centrify Browser Extension (CBE) is an add-on for Internet Explorer, Firefox, Chrome, and Safari to allow for automatic login when accessing web application services. Thus, eliminating otherwise time-consuming and complex login processes. The purpose of this article is to cover the configuration of the Centrify Browser Extension (advanced) using a script and finishing up with a demo of the application. No scripting experience is necessary!

This article is divided into the following sections:
A. Installation and setup
B. The Script's Properties
C. The Order Property
D. The LoginUser Object
E. Demonstration with the Centrify Admin Portal

 

A. Installation and Setup

We will first set up our CBE by installing the add-on, then creating a new web application in the Privileged Access Service (PAS) Portal.

1. Installation of the CBE add-on is dependant on the browser, specific instructions for each can be found here.
2. Add a Chrome Browser Extension (advanced) web application by going to the Admin Portal and navigating to:
Apps > Web Apps > Add Web Apps 
User-added image

Custom > Browser Extension (advanced)
User-added image

3. Now navigate to the Advanced section. This is where we will be spending most of our time.
User-added image


B. The Script's Properties

Before we begin writing our login script we'll first have to learn how to do so beginning with the script's properties. Think of these properties as all the different parts of the script that, when put together, allows us to seamlessly log into web applications automatically--much like all the different mechanical parts that make up a car.

1. We can identify properties as they are prepended with loginData.
2. Below is a list of properties and what they do.

loginData.addField (type: array):
  • Purpose: Gives the CBE information about what field it will need to fill, how to find them in the HTML document, and what to fill each field.
  • Parameters:
    • name (type: string): a name we give our field
    • pattern (type: string): a unique CSS selector
    • value (type: string): what to fill in
  • Example: loginData.addField('username', 'input#usernameForm', 'centrifyUser');

loginData.applicationUrl (type: string):
  • Purpose: Instructs the CBE on where to redirect the user to begin the login process.
  • Example: loginData.applicationUrl= 'https://www.centrify.com/login/';

loginData.detect_interrupt (type: bool, optional):
  • Purpose: Tells the CBE whether it should consider a command that is taking too long a failure or an interrupt. A failure (default) will abort the process. If set to "true" the user will see a dialog instructing the process has been interrupted and manual interaction is needed. If the user interacts with the page such that the sequence of instructions can continue, the CBE will proceed with the login process. This is useful if the web application is known to have a CAPTCHA.
  • Example: loginData.detect_interrupt = 'True';

loginData.formPattern (type: string, optional):
  • Purpose: If provided, the CBE will attempt to disable browser autocomplete features on the form element, which can sometimes help to avoid complications around browser auto-filling.
  • Example: loginData.formPattern = 'form.login';

loginData.globalSelectorTimeout (type: int, optional):
  • Purpose: Integer (in milliseconds - 1/1000 of a second) to wait when looking for any DOM element. The default is 15 seconds.
  • Example: loginData.globalSelectorTimeout = 30000;
 

C. The Order Property

The order property (below) is an important one and is the main differentiator between the basic and the advanced version of the CBE.

loginData.order (type: array):

In the basic version, the property can be seen in GUI form as the Order box and is not mandatory. It is used for login pages where the username and password fields may need to be filled in a special order, or if the username and password forms are located on separate pages (e.g. the username is entered first and then a second page is loaded with the password field). In the advanced version, the order property is mandatory but allows for greater flexibility in the number of forms (e.g. the username, password, email, address, etc. forms) the CBE can fill.

Basic:
User-added image

Advanced:
User-added image


The Order Syntax:
In both versions of the CBE, the order is constructed as a syntax of an array of commands.

Example 1 (this is the default setting of the basic CBE when the order property is not filled):
1. Load the login page.
2. Fill in the username, password, and the additional login field (as defined in the configuration of the basic CBE).
3. Click the submit button, or simulate an 'Enter' keypress.

[
   ["ups"]
]


Example 2:
1. Load the login page.
2. Fill in the username box.
3. Click the button with the CSS selector value of "button#idOfNextPage".
4. Wait for the next page to load.
5. Fill in the password box on the second page.
6. Click the submit button.

[
   ["fill", "username"], 
   ["click", "button#idOfNextPage"], 
   ["waitForNewPage"], 
   ["fill", "password"],
   ["submit"]
]


Example 3:
1. Load the login page.
2. Fill in the username box.
3. Wait 0.5 seconds.
4. Fill in the password box and simulate hitting the 'Enter' key.

[
   ["fill", "username"], 
   ["sleep", 500], 
   ["fillEnter", "password"]
]


The examples above have been indented for clarity; however, when entering them into the basic CBE, they will be entered all on one line (example below). The array may be entered in multiple lines in the advanced version.
[["fill", "username"], ["sleep", 500], ["fillEnter", "password"]]

If there are any special characters like ":" in the CSS selector sections in the Order field, they will need to be double-escaped by putting a double backslash "\\" in front of the characters. For example:
[["click", "input#idLoginForm\\:idLoginOption\\:1"],["waitForNewPage"],["fill", "username"],["fillEnter", "password"],["ups"]]


Available Commands:

'click'
  • Purpose: Instructs the CBE to click a DOM element
  • Parameters: 
    • pattern (type: string): a unqiue CSS selector
    • try (type: bool, optional): tells CBE it is ok to fail, default is to ensure click
  • Example: loginData.order = [['click', 'button[name=next]'],['click', 'button[name=confirm]', True]]

'expect'
  • Purpose: Instructs the CBE to search for a DOM element and not continue the login process until it is found. Often followed by commands like 'click' or 'fill' which might go wrong unless the CBE waits for the element to be ready.
  • Parameters:
    • pattern (type: string): a unqiue CSS selector
  • Example: loginData.order = [['expect', 'div.only-present-after-data-loading-async-things-are-done']

'fill'
  • Purpose: Instruct the CBE to fill a field.
  • Parameters:
    • name (type: string): must match the name of one of the previously defined loginData.addField by name.
  • Example: loginData.order = [['fill', 'username']]

'fillEnter'
  • Purpose: Same as 'fill' but will trigger an "enter" keypress after filling the field.
  • Parameter:
    • name (type: string): must match the name of one of the previously defined loginData.addField by name.
  • Example: loginData.order = [['fillEnter', 'username']]

'submit'
  • Purpose: Simulates an "enter" keypress. Often preceded by instructions to fill form fields.
  • Parameters: None
  • Example: loginData.order = [[...], 'submit']​​​​

'sleep'
  • Purpose: Pause between commands to allow the page to load or to wait for an element to appear.
  • Parameters:
    • amount (type: int): duration (in milliseconds - 1/1000 of a second) before continuing
  • Example: loginData.order = [['sleep', 300]]

'waitForNewPage'
  • Purpose: Instruct the browser extension to wait for the browser to navigate to a different page. This instruction is required when a sequence of instructions spans several URLs or "pages" on a target website. Without it, the sequence of instructions will fail as it was interrupted mid-sequence.
  • Parameters:
    • url (type: string, optional): if the current document matches this URL, then the CBE will ignore this current waitForNewPage command.
  • Example: loginData.order = [['waitForNewPage'],['waitForNewPage', {'url': 'https://app.com/url_which_means_i_dont_need_to_wait'}]]

'goto'
  • Purpose: Instructs the CBE to navigate to a new URL.
  • Parameters: 
    • url (type: string): URL to navigate to.
  • Example: loginData.order = [['goto', 'https://www.centrify.com']]

'ups'
  • Purpose: Shorthand notation, if present, should be the only instruction. The browser extension expands this to the following sequence of instructions: fill the username, fill the password, fill the additional field if available, and submit.
  • Parameters: None
  • Example: loginData.order = ['ups']



D. The LoginUser Object

Sometimes, instead of filling out a field (loginData.addField) statically, we want our input to change depending on the user that's logged, their group membership, etc. This is where the LoginUser variable comes in handy. Please visit this link (The LoginUser object) that goes in-depth with its different properties; however, two helpful ones are:

LoginUser.Username
Determined by the Map to User Accounts setting in the Application.
User-added image

LoginUser.Get(ADAttribute)
This returns any of the user's Active Directory attributes.
 

E. Demonstration with the Centrify Admin Portal

Now that we know all the parts of our script let's go ahead and put everything together. Watch the following video as I walk you through setting up the CBE to log in to my Centrify Admin Portal (aka Kibble-tenant).