Customize the Okta-hosted error pages

This guide explains how to customize error pages that can appear as part of a custom domain Okta-hosted sign-in flow.

Learning outcomes

Customize error pages as part of the sign-in flow.

What you need

Okta Developer Edition organization (opens new window)
Custom domain, unless you're using the Brands API

Sample code

About error page customization

When using an Okta-hosted flow, you can create a unique sign-in experience by providing a custom domain and creating a Widget style that matches your application's look and feel.

However, if an error occurs during sign-in, Okta may need to display an error page to the user. To provide a seamless user experience, you can also customize the error page by using the code editor.

Note: A custom error page only appears when an app connects to Okta by using your custom domain. Otherwise, the default Okta error page appears when a critical error occurs or an application is misconfigured. See Okta deployment models — redirect vs. embedded for more information on Okta-hosted (redirect) functionality.

Use the Brands API

The Brands API (opens new window) allows you to set icons, images, and colors across your Okta-hosted Sign-In Widget, error pages, email templates, and Okta End-User Dashboard all at once. You don't need to set a customized Okta URL domain.

Edit the error page

Use the code editor to modify any HTML, CSS, or JavaScript on the error page. See Customization examples for snippets that you can update and use.

In the Admin Console, go to Customizations > Brands, and then select the brand you want.
On the Pages tab in the Error Pages section, click Configure.
To open the code editor, turn on the toggle next to Code editor.

Note: You can only enable the code editor if you configure a custom domain.
Make changes directly in the editor. If you enter {, (, or . you see a list of available variables that you can use. See Use variables.
- Click Preview to see your changes in a new browser window before you publish.
- Select Compare with published version to see the difference between your edited version and the published version. You can choose between a split view and a unified view.
Note: The console restores the previous published version of the code. To revert to the 0-state/default, toggle the code editor off.
Click Publish to commit your changes.

Use variables

The Okta error page template is written using Mustache (opens new window) and uses predefined variables to insert relevant values into the error page. To see the variables in a code sample, refer to the error page default code in the code editor. See Edit the error page.

Variables with double curly braces ({{) return escaped HTML by default. Escaping allows you to show "special" characters in HTML. For example, hello displays as a paragraph element and the  tags don't render. For the  tags to render, escape or replace the  tags by using  hello . In this example,  escapes < and  escapes >.

Triple curly braces ({{{) are only used for the errorDescription variable to return unescaped HTML.

Variable	Contains
`{{orgName}}`	The org name title
`{{errorSummary}}`	The error title text
`{{bgImageUrl}}`	The URL to the background image configured for your application. You can change this image by using the Sign-in Configuration (opens new window) option, but this changes the background image in all instances where the variable is used, including your custom sign-in page. If you want to change only the background image for your custom error pages, include the URL to the image instead of the variable.
`{{orgLogo}}`	The logo image that has been configured for your application. You can change this logo by using the Sign-in Configuration (opens new window) option, but this changes the org logo in all instances where the variable is used, including your custom sign-in page. If you want to change only the logo image for your custom error pages, include the URL to the image instead of the variable.
`{{{errorDescription}}}`	A detailed description of the error
`{{back}}`	The text "Go to Homepage". When the user clicks the button, they are returned to the sign-in page.
`{{technicalDetails}}`	Any additional messaging, if the error code has any. Here are sample technical details for an error code: "If you are using custom expressions like `\{0}`, make sure that the field `customField` is present in the user profile. Please review your attribute list and make the appropriate change." See Okta Error Codes.
`{{buttonText}}`	Inserts the button text based on the page context. When the user selects the button, they are directed to the `buttonHref` URL. The `{{back}}` variable is also supported for the same purpose.
`{{buttonHref}}`	The hyperlink for the button
`{{themedStylesUrl}}`	The URL for the themed style sheet
`{{faviconUrl}}`	The URL for the favicon

Customization examples

Use the following customization examples to help you personalize your error page by extending the look and feel of the page with your own stylesheet (CSS).

Add a stylesheet

You can add your own stylesheet to extend the look of your error page.

In the code editor, add a link to your stylesheet in the <head> section, below the <link rel="stylesheet" type="text/css" href="/assets/css/sections/errors-v2.css"> line.

Example:

<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="robots" content="none" />

    <title>{{orgName}} - {{errorSummary}}</title>

    <link rel="stylesheet" type="text/css" href="/assets/css/sections/errors-v2.css">
    <link rel="stylesheet" type="text/css" href="/assets/css/sections/yourstylesheet.css">
</head>

Add styles inline

Alternatively, you can add styles inline for elements of your error page.