Customize Login Pages¶

You can customize the layout and branding of user interfaces like the login page, register page, username and password recovery pages, and single sign-on pages.

All UIs are available in the authenticationendpoint, accountrecoveryendpoint, and x509certificateauthenticationendpoint apps located in the <IS_HOME>/repository/deployment/server/webapps folder.

General components of the UI¶

All pages of WSO2 Identity Server are separated into three general components as shown below. You can reference these components when you write the custom layout using a special notation.

• Login page

• Register page

Layout syntaxes¶

This section includes details about the special syntax that can be used when writing a custom layout code.

• Condition block

  

  This is similar to an IF block. This condition block will activate or deactivate according to the value of the isPolicyPage variable.

  • If the value of isPolicyPage is true or any non-empty string, then the content inside the block will be executed.
  • For all other values including null and undefined, the content of the block will not be executed.

• Not Condition Block

  

  This is similar to an IF block with a NOT condition.

  • If the value of isPolicyPage is false, an empty string, null or undefined, the content inside the block will be executed.
  • For all other values, the content of the block will not be executed.

• Component Syntax

  

  This syntax will be used to indicate the position of the general component in the custom layout code. The component syntaxes will be replaced with actual content at runtime.

• Data Syntax

  

  This syntax can be used to add data to the layout code. The value stored in the containerSize variable will be converted to a string and placed in the corresponding location at runtime. All data syntax values will be sanitized before adding to the layout code.

Add a custom layout for the authentication/recovery pages¶

To customize these pages, follow the steps below.

Step 1: Create the extensions folder¶

Navigate to webapps/authenticationendpoint and create a new folder named extensions.

Step 2: Create the basic custom layout resources¶

To create the basic custom layout resources:

1. In the authenticationendpoint folder, navigate to the created extensions folder and create the layouts and custom folders recursively.

   └── extensions
       └── layouts
           └── custom

2. Navigate to the webapps/authenticationendpoint/includes/layouts/default folder, copy the body.html file, and add it to the created custom folder.

3. Create the following files and folder inside the custom folder:

   • styles.css file
   • script.js file
   • assets folder

Step 3: Add a custom layout design¶

To add a custom layout to the login page:

1. Navigate to webapps/authenticationendpoint/extensions/layouts/custom/ and follow the instructions provided below:

   1. Copy the code snippet from the html file into the body.html file.

   2. Copy the code snippet from the css file into the styles.css file.

   3. Copy the code snippet from the javascript file into the script.js file.

   4. Copy the illustration.svg file into the assets folder.

2. Navigate to the webapps/authenticationendpoint/includes folder and copy the product-title.jsp and product-footer.jsp files to the webapps/authenticationendpoint/extensions folder as follows:

   1. Copy content from the jsp file containing the project title to the webapps/authenticationendpoint/extensions/product-title.jsp file of the app.

   2. Copy content from the jsp file containing the project footer to the webapps/authenticationendpoint/extensions/product-footer.jsp file of the app.

   Note

   Repeat the above steps for accountrecoveryendpoint and x509certificateauthenticationendpoint as well. You will be copying the following files:

   • Project title.

   • Project footer

3. Build the source code.

   1. Copy the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/extensions/layouts/custom directory and place it into the <IDENTITY-APPS-HOME>/components/login-portal-layouts/layoutsdirectory.

   2. Navigate to <IDENTITY-APPS-HOME>/components/login-portal-layouts directory and build the source code using mvn clean install command (Build should be succeeded for further steps).

   3. Copy <IDENTITY-APPS-HOME>/apps/authentication-portal/src/main/webapp/extensions/layouts/custom folder (Compiled version of the layout source code) and paste it into the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/extensions/layouts directory.

4. Refresh the browser and check out the added custom layout.

   Tip

   In certain cases, the server might stop working after adding changes. In such cases, restart the server to check the changes.

The custom layout will be moved to the corresponding locations of authenticationendpoint, accountrecoveryendpoint, and x509certificateauthenticationendpoint apps.

Best Practices¶

Use the following best practices when creating a custom layout:

• Add a prefix for the new CSS classes so that the newly added classes will not conflict with existing classes.

• Set cache="false" when developing a custom layout. Be sure to remove the cache="false" in production code.