Configure the Okta Template App and Okta Plugin Template App Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005u9ksaq&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2fconfigure-the-okta-template-app-and-okta-plugin-template-app-1968514570
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Configure the Okta Template App and Okta Plugin Template App
Published: Sep 14, 2017   -   Updated: Jun 22, 2018

 

 

okta-doc-source

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 via a form POST
  • Template Plugin App – Use if the app site has username/password/submit button fields on the page
  • Template App 3 Fields – Similar to above; use if an app page also has an additional field such as Company ID
  • Template Basic Auth App – Use if the app supports basic auth

Procedure

  1. Go to Applications > Applications.
  2. Click Add Application.
  3. Search for Template.
  4. From the search results, add the desired type of template app:
  5. Template App

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

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

    Enter information in the General Settings page.

    • Application label – enter the label you want to display under the app on end users' home page.
    • 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).
    • Username field/UserName Selector – enter the CSS selector for the username fields.
    • Password field/Password Selector – enter the CSS selector for the password field in the log-in form.
    • Login Button – enter the CSS selector for the login button in the login form.
    • * Extra Field Selector – enter the CSS selector for the extra field in the form.
    • * Extra Field Value – enter the value for the extra field form field.

    Notes:

    • Items marked with an asterisk (*) apply to the Template Plugin App 3 Fields app only.
    • 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:

    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 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:

    • Username#okta-signin-username Screenshot
    • InspectElement_username

    • Password#okta-signin-password Screenshot
    • InspectElement_password

    • Button#okta-signin-submit Screenshot
    • InspectElement_submit

    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.

    Template Basic Auth App

    Use this template if your app supports basic authentication. Screenshot

    BasicAuthModal

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

Top