This site requires JavaScript to be enabled
External Customer KB > General > Building Custom Connectors
Building Custom Connectors
Article: KB0010526 Published: 09/30/2020 Last modified: 09/30/2020

Note: Please first attempt to use the OneLogin Browser Extension or the UC2 connector before building a custom connector. 

Introduction

Custom connectors are used because the OneLogin Browser Extension is not able to create an application successfully and the application is private and not in our App Catalogue. 

Login URL

This is the URL that the user is directed to when clicking on an app on the dashboard.

Form Fill Trigger

The Trigger URL and the Trigger Domain must be in Regular Expression Format. Rubular is a good interactive regexp tester.

Please do the following:

  • Start your regular expressions with ^ and end them with $.
  • Escape periods (.), forward slashes(/), and question marks like this: https: \/\/www\.niceapp\.com\/\?account_id={accountid}
  • Use . instead of \S. Some of the browsers seem to handle . better as a wildcard.

Trigger URL 

This is the URL that the browser add-on looks for before it fills in the user's credentials. Trigger URLs should always start with ^ and end with $. Make sure the Trigger URL value matches the entire string.

Trigger Domain

This is the URL that the OneLogin Browser Extension matches on to verify this is a login that you have. A blue bar will appear at the top of the page (URL entered) asking to form fill saved credentials for this domain.

Form Fill method

Method

The login method depends on the markup of the login form. Most forms contain plain HTML that OneLogin can easily navigate and simply post the user credentials to, which is what the form method does. Other login pages are complex and include lots of Javascript, which can make it impossible for the add-on to fill in the credentials. In these situations, you can use the script method to hand-write a script that does the trick.

Form Identified by

This field is used by the form login method to identify the relevant form on the page, which can be done by looking at the form's attributes, for example, action, id, name or method. This is a regular expression as form actions can often have parameters provided by the server.

Form Value

This value is determined by the variable selected in the 'Form Identified by' drop-down. For example, if you select id then enter the id for the form or script. This must be a regex expression to identify the value.

Login Script 

If you have an existing configuration, you will be able to view, but not edit or delete.  Call Customer Support to update this field.

Form Submitted by 

Once the user credentials have been filled in, the login is posted to the server, which is usually done by a button. This button can be identified by its name, id, value, type or alt attribute. Some login forms have graphical buttons or call a Javascript function that needs to process the values before posting them to the server. In these cases, you can provide a Javascript snippet that emulates clicking the button.

Button Identified by

This is how the button is identified by the form. Examples are alt, id, value, type or the alt attribute. Do not select a value unless you are using the Form Method.

Submit Value

This is the value of the attribute for the button. For example, the value of the id attribute. Do not select a value unless you are using the Form Method.

 

Parameters

A connector can have as many Parameters as needed. Typically for a Forms-Based connector, Username & Password are all that is required, however, some applications additionally require a subdomain, account number, etc.

Available Parameter fields:

  • User Interface Label - The name shown to the user in the UI.
  • Shortname - This is the metadata name of the parameter field.
  • Tip - Help Text visible to users.
  • Flags 
    • Required: This requires that there be a value for this field.
    • Visible: Whether or not the field is visible to the user.
    • User Editable: Whether or not the field can be edited by the end-user.
    • Search: Whether or not this parameter can be searched.
  • Type - The string values are stored in clear text in OneLogin whereas passwords are encrypted.
    • String: This is just a text string. Commonly used for Username or an Email attribute.
    • Password: This is a text string that is enshrouded with asterisks (***).
  • At Level - This determines if this field is at the User or Application level.
  • Format - Most commonly, email, username or subdomain are required formats. This ensures your users enter the correct format of the parameter you've created (being that they're the most common Forms-based connector parameters).
  • Default User Attribute Mapping - By default, you can map a User Attribute to a Parameter, such as mapping the Username or Email OneLogin attribute to a (or this possibly) Username or Email application parameter.
  • Default User Attribute Transformation - Used when sending over one or more Parameter values in a string.
  • Name in HTML form - This is the name of the HTML form element, e.g. username or password. You can use this name to substitute strings in login URL, trigger URL and action by enclosing it with { }. For example, you might have a parameter called subdomain and a login URL with the value: http://{subdomain}.niceapp.com/login.
  • Test value - The value you can use to test the connector without having to first create an application.

Note: If an admin alters a parameter after an app has been added to the connector, the parameter must be deleted and reinstalled. 


Expand/Collapse Comments
:     
Was this helpful?
YesYesNoNo