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 ,  

1 April,21 at 09:34 PM

What is the Centrify Browser Extension (CBE)?

The Centrify Browser Extension (CBE) is an add-in 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 so we can begin writing our script to log into web applications.

1. Installation of the CBE 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

loginData.order (type: array):

The order property is an important one so it gets its own section. This property contains the instructions for the CBE to log into the web application; using actions such as: click here, fill in data here, wait this long, etc. More information about the different actions below. There is also a great KB written about the order property that can be found here (KB-5440: How to use the Order box for advanced Centrify Browser Extension apps).

'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']]


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