Procedure

You can use the template app if the app supports authenticating via a form POST to the specified URL. It contains the username and password of a user filled in with the named parameters and static fields that you provide.

Enter information in the General Settings page.

URL – enter the URL of the login form you are POSTing to (not the URL where you see the form).

Username and password parameter(s) – enter the parameter names that contain the username and password data.

Optional parameter fields – enter extra static field data in the name/value pairs. For help determining what to enter in these optional fields, click here.

From the Chrome browser, log in to the app you want to integrate with.

Use Chrome developer tools to view the traffic that is being sent to the page.

Open to the page with the target login form, and switch to the Network tab.

Select the Preserve log checkbox.

Clear out the existing traffic and perform your login.

In the Headers tab, find and click the POST to the page to see all the data that was posted, as well as the URL to which it was sent.

If the app has cross-site request forgery XSRF protection, you need to use the Template Plugin App or Template Plugin 3 Fields app. To check, inspect the page to see if the server generated an XSFR token. Also look for fields such as EVENTVALIDATION or FORMVALIDATION which are generated on asp pages. In such cases, the Template Plugin App is required.

When you configure a Template Plugin App, instead of providing the parameters, you provide CSS selectors to the relevant fields because the plugin is used to populate these fields and click the login button.

URL/Target URL – enter the URL of the log-in form (the actual URL where you can view the form). Template Plugin App: the field is URL; Template Plugin App 3: the field is Target URL.

Regular Expression – (Optional) This allows you to create a regular expression that serves as a whitelist. This is done to improve app security by restricting access to the URLs that match the pattern that you define. For example, if your log-in URL is https://example.com/login, and your change password is https://example.com/change_password, then you might create a regular expression that matches https://example.com/(login|change_password).

If no regular expression field is provided, Okta generates a secure regular expression from the URL/Target URL that omits the path from the URL. For example, if you specify https://www.example.com/login, the Okta-generated regular expression will be:

(?:^https://example\.com(?:$|/))

where we omit the login path, escape the URL, and surround the resulting URL with (?:^ and (?:$|/))

Finding the selector fields

To determine the selectors, inspect the individual elements on a page. Using the Chrome developer tools:

Open to the page containing the target login form.

Right click an input field or button and select the Inspect option to see the actual Document Object Model (DOM) element. In the Elements tab view the id and class of the element and, using this information, compose a selector.

You may need the full hierarchy when you can't uniquely identify elements by ids or classes. If we examine the Okta Sign In page, for example, the selectors would be:

In cases where the app only uses a name attribute, and not id for its username, password, or submit buttons, you can try using input[type="text"]. For example, you can use input[type="password"] for a password, and input[type="submit"] for a submit button. Other attributes can be queried; for example, input[class="btn"] as an alternate way to specify the submit button.

Cases where the Template Plugin App will not work

The Template Plugin App is not effective for sites that:

Do a lot of dynamic HTML creation. Sites like this may fail with this approach because the elements the plugin is looking for won't be present when the plugin fires.

Require a parameter beyond just username and password, as they can use Template Plugin App 3 Fields if the parameter is static and doesn't change.

Have multiple steps in the login process, or load multiple pages between the initial URL and the one that contains the form.

Use frames or iframes to contain the form. Sometimes you can avoided this by using the URL of the frame content as the starting URL. (Use Inspect Element to figure this out.)

You can address the above cases with a plugin integration, but not within the context of the Plugin Template App. If you encounter such a case, you must write the app integration by hand. Contact Okta's Professional Services team to discuss pricing for the app.

Browser plugin auto-submit – specify whether to log users in automatically when they land on the login page.

Known issue

The Template Plugin App cannot work in cases where the app's login page redirects users back to the URL they came from, as this creates an infinite loop. The SWA application must redirect the user to the website's home page, not back to the login page. This means that the login page will accept the user's credentials, then redirect the user back to the Okta home page.