Skip to content

Re-branding WSO2 Identity Server UIs

From WSO2 Identity Server 5.9.0 onwards, a new UI extension has been introduced to easily re-brand basic user interfaces like the login page, username and password recovery pages, and single sign-on pages.

All these UIs are available in the authenticationendpoint and accountrecoveryendpoint web apps that are located in the <IS_HOME>/repository/deployment/server/webapps folder. To customize these pages, follow the steps below.


To modify the endpoints, apply the 0003 WUM update for WSO2 Identity Server 5.10.0 using the WSO2 Update Manager (WUM). To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Updating WSO2 Products

Step 1: Create the extensions folder

  1. Navigate to the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint folder and create a new folder called extensions.


    You will be adding the modified JSP files along with the modified CSS files into this new extensions folder.

  2. Similarly, navigate to the <IS_HOME>/repository/deployment/server/webapps/accountrecoveryendpoint folder and create an extensions folder.

To re-brand the header and footer content of the web applications, first copy them over to the newly created extensions folders.

  1. To copy the header and footer content of the authenticationendpoint web application:

    1. Navigate to the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/includes folder.

    2. Copy the header.jsp and product-footer.jsp files into the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/extensions folder.


      The header.jsp and product-footer.jsp files have the capability to override the corresponding files in the includes folder.

  2. Similarly, copy the header and footer content of the accountrecoveryendpoint web application.

Step 3: Create styling

Create the basic CSS styles that are required to override the existing UI styling.

    html, body {
        height: 100%;

    body {
        flex-direction: column;
        display: flex;
        background: #1e1e2f;
        color: #ffffff;

    main {
        flex-shrink: 0;
    } {
        margin: auto;
        display: flex;
        align-items: center;
    } > .ui.container.medium {
        max-width: 450px !important;
    } > .ui.container.large {
        max-width: 700px !important;
    } > .ui.container > .ui.segment {
        padding: 3rem;
        background: #424061;
        box-shadow: 3px 2px 7px #1c1818;
        border-radius: 10px;
    } > .ui.container > .ui.segment .segment-form .buttons {
        margin-top: 1em;
    } > .ui.container > .ui.segment .segment-form .buttons.align-right button, > .ui.container > .ui.segment .segment-form .buttons.align-right input {
        margin: 0 0 0 0.25em;
    } > .ui.container > .ui.segment .segment-form .column .buttons.align-left, > .ui.container > .ui.segment .segment-form .column .buttons.align-left {
        padding: .78571429em 1.5em .78571429em 0;
    } > .ui.container > .ui.segment .segment-form {
        text-align: left;
    } > .ui.container > .ui.segment .segment-form .align-center {
        text-align: center;
    } > .ui.container > .ui.segment .segment-form .align-right {
        text-align: right;

    .cookie-policy-message {
        font-size: 14px;

    footer {
        padding: 2rem 0;

    body .product-title .product-title-text {
        margin: 0;

    body .center-segment .product-title .product-title-text {
        margin-top: 2em;
        margin-bottom: 1em;

    .ui.header {
        color: #ffffff;
        font-weight: 600;
    } .product-logo {
        padding-left: 0;

    .ui.form .field .ui.input input {
        background: #6b688d;

    .ui.checkbox label {
        color: #ffffff;

    /* Table of content styling */

    main #toc {
        position: sticky;
        top: 93px;

    main .ui.segment.toc {
        padding: 20px;

    main .ui.segment.toc ul.ui.list.nav > li.sub {
        margin-left: 20px;

    main .ui.segment.toc ul.ui.list.nav > li > a {
        color: rgba(0,0,0,.87);
        text-decoration: none;

    main .ui.segment.toc ul.ui.list.nav > li:before {
        content: "\2219";
        font-weight: bold;
        font-size: 1.6em;
        line-height: 0.5em;
        display: inline-block;
        width: 1em;
        margin-left: -0.7em;

    main .ui.segment.toc ul.ui.list.nav > li.sub:before {
        content: "\2192";
        margin-left: -1em;

    main .ui.segment.toc ul.ui.list.nav > li:hover a {
        color: #ff5000;
        text-decoration: none;

    main .ui.segment.toc ul.ui.list.nav > li:hover:before {
        color: #ff5000;

Add the product-footer.jsp and header.jsp files to the extensions folder as follows:

  1. To edit the header content of the authenticationendpoint web application:

    1. Open the header.jsp file in the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/extensions folder.

    2. Add the following includes.

    <%@include file="../includes/localize.jsp" %>
    <%@include file="../includes/init-url.jsp" %>
    1. Replace the contents of the <style> tag, with the styles you created in Step 3 inside the header tag.
  2. To edit the footer content of the authenticationendpoint web application:

    1. Open the product-footer.jsp file in the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/extensions folder.

    2. For example, to add the company name, you can replace the content of the <footer> tag with the following code.

          <footer class="footer">
              <div class="container-fluid">
                  <p>XYZ Company | &copy;
                      <script>document.write(new Date().getFullYear());</script>
                      <a href="<%=AuthenticationEndpointUtil.i18n(resourceBundle, "business.homepage")%>"
                         <i class="icon fw fw-wso2"></i>
                         <%=AuthenticationEndpointUtil.i18n(resourceBundle, "Inc")%>
                      . <%=AuthenticationEndpointUtil.i18n(resourceBundle, "All.rights.reserved")%>

  3. Similarly, you can re-brand the accountrecovery web application header and footer.

    1. Open the product-footer.jsp file in the <IS_HOME>/repository/deployment/server/webapps/accountrecoveryendpoint/extensions folder.

    2. To add the company name, replace the content of <footer> tag with the following.

          <footer class="footer">
              <div class="container-fluid">
                  <p>XYZ Company | &copy;
                      <script>document.write(new Date().getFullYear());</script>
                      <a href="<%=IdentityManagementEndpointUtil.i18n(recoveryResourceBundle, "business.homepage")%>"
                         <i class="icon fw fw-wso2"></i>
                         <%=IdentityManagementEndpointUtil.i18n(recoveryResourceBundle, "Inc")%>
                      . <%=IdentityManagementEndpointUtil.i18n(recoveryResourceBundle, "All.rights.reserved")%>


    Make sure to add the following include to the top, when editing the header.jsp file of the accountrecovery web application.

    <%@include file="../localize.jsp" %>
  4. Refresh the browser and check out the modified header and footer content.


Restarting the server is NOT required to reflect the changes—browser refresh will display the changes.

image Customized Login Page

image Customized Recover Username page

image Customized Recover Password page

image Customized Self signup page


One advantage of this approach is that WUM updates will not affect your UI changes and you need not worry about manually adding your changes.