Configure a custom Okta-hosted Sign-In page Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Configure a custom Okta-hosted Sign-In page
Published: May 15, 2018   -   Updated: Jun 22, 2018




This is an Early Access feature. To enable it, please contact Okta Support.

Configure a custom Okta-hosted Sign-In page

Settings > Customization > Custom Sign In

You can customize the text and the look and feel of the Okta-hosted sign-in page using form controls and an embedded HTML editor provided in the Customization page. When used together with custom URL domain (required) and custom Okta-hosted error page, this feature offers a fully customized end-user sign-in experience hosted by Okta. If you want to build your end-user experience from scratch and host it yourself, you can use the Okta Sign-In Widget and Auth.js SDK to build this functionality (see Related Topics). Screenshot


Key benefits
  • No need to host the sign-in page on a separate server.
  • Modify the current HTML/CSS and JavaScript as much as you like, or paste your own code in the embedded editor to create a completely transformed sign-in experience.
  • Easily preview your custom sign-in page before publishing.
  • Deploy specific configurations and capabilities of the Sign-In Widget by selecting major and minor versions.


For this feature to work, Custom URL Domain must be configured.

  • Your custom Okta-hosted sign-in page is available only when end users access Okta through your custom URL domain. End users will continue to see your default Okta sign-in page when accessing your * or * orgs.
  • You can replace, but not edit, the provided macros when editing code in the embedded editor. For details, see the Important note below.
  • The custom Okta-hosted sign-in page feature is supported in mobile browsers but not supported for use with Okta Mobile.

  1. Go to Settings > Customization.
  2. Click the Custom Sign In tab.
  3. (Optional) Select the Okta Sign-In Widget Version:

    This option allows you to leverage or omit specific sign-in page capabilities by specifying a particular version of the Okta Sign-In Widget. If you are not familiar with the Okta Sign-In Widget, Okta recommends that you simply select the highest Major Version and the latest Minor Version (default). For details about the Okta Sign-In Widget capabilities supported by major and minor versions, see this Github page.

    1. Click Edit. Screenshot


    2. Click Save.
  4. Customize the sign-in page:
  5. You can use the form fields on the left side of the page and the HTML editor together or separately to customize the sign-in page.

    • Form fields – If you only want to edit links, labels, and headings, use the form fields provided on the left side of the page. These same options are also available in the General tab of the Customization page and changes you make here also appear there, and vice versa.

      You can also customize the placeholder text that appears in recovery flows when end users click account recovery links (for example, Forgot password and Unlock account). If you leave a label field blank, Okta uses default text.

      Note: Although Okta displays default labels, links, and headings in the end user's Display language or the browser language, Okta does not display localized versions of your custom text and links. If you entered custom text and links in a different language than the end users' Display or browser language, the Sign-In page will have text in more than one language.

    • HTML editor – If you are familiar with using HTML and want to change colors, line widths, page layout, button shapes, and other elements, use the embedded editor in the middle of the page to change anything you like according to your needs.
    • Important: You can replace, but not edit, the provided macros. To replace a macro, you must replace the text and the brackets that surround the text. Otherwise, your changes are not implemented and the original text or element is removed from the error page.

      For more about the macros used in the provided code, see Macros. For additional information about how to use and manipulate the HTML/CSS and JavaScript code, see the articles listed in Related Topics.

  6. (Highly recommended) Click Preview to preview your changes before you publish.
  7. (Optional) Click Reset to Default if you want to remove all of your customizations and restore the default HTML/CSS and JavaScript code.
  8. When you are finished, click Save and Publish.


Macros contain all of the configuration parameters for certain page elements.


An HTML code snippet that contains JavaScript and CSS tags for bootstrapping the Okta Custom Sign-In Widget.


This macro controls the background image. You can also configure a background image using the Sign-In Configuration option in Settings > Appearance.


OktaUtil defines a global OktaUtil object that contains methods used to complete the Okta log-in flow.

Known Issue

The Early Access version of this feature does not identify specific errors in your custom code.