Configure the Okta Template App and Okta Plugin Template App

Template apps allow you to create application integrations in real-time on a running system. To create custom apps, choose from these common Secure Web Authentication (SWA) template apps:

• Template App: Use if the app supports authenticating through a form POST
• Template Plugin App: Use if the app site has username, password, or submit button fields on the page

  When you configure a Template Plugin App or a Template Frame 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.

• Template App 3 Fields: Similar to above; use if an app page also has an additional field such as Company ID
• Template 2 Page Plugin App: Also similar to the Template Plugin App; use if sign in flow is spread over two separate pages
• Template Basic Auth App: Use if the app supports basic auth
• Template Frame Plugin App: Use if the app supports iframes

Procedure

1. In the Admin Console, go to Applications > Applications.
2. Click Browse App Catalog.
3. Search for Template.
4. From the search results, add the desired type of template app:
Template App
You can use the template app if the app supports authenticating through 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 parameter and Password parameter fields: 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.
• Application Visibility: Specify whether to display the application icon to users.
• Browser plugin auto-submit: Specify whether to log users in automatically when they land on the login page.
Template Plugin App/Template Plugin App 3 Fields/Template 2 Page Plugin App/Template Frame Plugin App

Click: Knowing when to use the Template Plugin or Template Plugin 3 Fields app

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 XSRF 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 or Template Frame 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.

Enter information in the General Settings page.

• Application label: Enter the label you want to display under the app on end users' home page.
• Login URL: Enter the URL of the log-in form (the actual URL where you can view the form).
• Frame URL: Enter the Frame URL (This is the URL which contains the frame)
• Redirect URL: If going to the login page URL redirects to another page, then enter that URL here.
• Regular Expression: (Optional) This allows you to create a regular expression that serves as an allow list. 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).
• Username field: Enter the CSS selector for the username field.
• Password field: Enter the CSS selector for the password field.
• Login Button: Enter the CSS selector for the login button.
• Checkbox: Enter the CSS selector for the checkbox (it can be the checkbox for the Remember me, Agree terms, etc.).
• Next Button: Enter the CSS selector for the next button that would redirect you to the next page.
• Extra Field Selector: Enter the CSS selector for the extra field.
• Extra Field Value: Enter the value for the extra field.

 

• The fields you see depend upon the type of template you are configuring.
• If no regular expression field is provided, Okta generates a secure regular expression from the Login 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 CSS selector fields

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.

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

1. Open to the page containing the target login form.
2. 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 CSS selector.

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

• Username: #okta-signin-username Screenshot



• Password: #okta-signin-password Screenshot



• Button: #okta-signin-submit Screenshot



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.

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.

Template Basic Auth App
Use this template if your app supports basic authentication. Screenshot

• Application label: Enter the label you want to display under the app on end users' home page.
• URL: Enter the URL of the log-in form (the actual URL where you can view the form).
• Auth URL: Enter the URL of the authenticating site for the app.
• Application Visibility: Specify whether to display the application icon to users.
• 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.

Related topic

Configure the Okta Template WS Federation Application