This documentation is for WSO2 Identity Server 5.0.0. View documentation for the latest release.
Customizing Login Pages - Identity Server 5.0.0 - WSO2 Documentation
Skip to end of metadata
Go to start of metadata

Custom pages for logging into the server are available for SAML2 SSO, OAuth and OpenID. This section guides you through this customization. 

The login pages and other pages like error and notification screens of SAML SSO, OAuth, OpenID and Passive STS are located in the authenticationendpoint webapp file found at <PRODUCT_HOME>/repository/deployment/server/webapps.

You can easily customize these pages within this web application by changing the respective JSPs, JavaScript and CSS. If you want to point to a different web application, you can do so by redirecting or forwarding from authenticationendpoint to your webapp. In the case of SAML SSO, the 'issuer' id of the service provider is also sent to this webapp. Therefore, different login pages can be given to different service providers by looking at the 'issuer' request parameter.

The following is a sample of how to customize the login page for SAML2 SSO.

Customizing the login page for SAML SSO service providers

Usually WSO2 Identity Server displays a default login page for all the SAML SSO service providers that send authentication requests to it. The following steps indicate how to change the default login page into a customized one.

Configuring two service providers

  1. Copy the and files to your application server (Tomcat 7 was used for this sample scenario).
  2. Start the application server and access following URLs to make sure both apps are running.

Registering the two service providers in the Identity Server

  1. Download WSO2 Identity Server and extract it.
  2.  Run the server by executing wso2is-5.0.0/bin/ for Unix-based systems, or /bin/wso2server.bat for Windows.
  3.  On the management console, click Add under Service Providers in the Main menu. 
  4. Enter "" as the Service Provider Name in the form that appears and click Register.
  5. In the page that appears next, expand the Inbound Authentication Configuration section and the SAML2 Web SSO Configuration section. 
  6. Click Configure. The Register New Service Provider page appears.
  7. Configure the following details for and repeat steps 1 to 6 and configure details for
  8. When attempting to "login with SAML from WSO2 Identity Server" in and, you can see the following default page. 

Configuring the login page

The default login seen earlier is located at <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/login.jsp. 

Understanding the authenticationendpoint web application

The login page that is displayed during SAML2 SSO, OAuth, OpenID and Passive-STS flows is located inside the webapp named authenticationendpoint. The reasons for storing this in a webapp are:

  • To easily customize the page according to user requirements.
  • If needed, you can place that whole web application in an external application server.

The location of this web application is specified in the <IS_HOME>/repository/conf/security/application-authentication.xml configuration file. This is referenced in the following property. 


By default it points to a location inside the Identity Server itself; therefore, the relative path is given. If it is necessary to point to an external application, the full path should be given instead.

If this webapp is moved outside the Identity Server, ensure that no one can access the login credentials that are passed between this application and the Identity Server. This means that the external location should ideally be either inside a secured intranet or the transport should be HTTPS. Other similar precautions may be necessary to secure the communication.

The following is the structure of this web app.

In the default web application, when a request comes to the login page, it is first served by the AuthenticationEndpoint servlet. After checking that this is a SAML2 SSO request, it is forwarded to the SAMLSSOLogin servlet, which finally forwards the request the login.jsp file. You can see how this is mapped on the web.xml file. Everything here is customizable, including the servlets and pages. You can get the source code for the authenticationendpoint webapp from here.

The only restriction involved is that the content already sent back by the pages inside the default web app must be submitted to the Identity Server. Additionally, you must point to the correct location via the <IS_HOME>/repository/conf/security/application-authentication.xml file.

Customizing the login page

There can be many ways to do this as you might have discerned from the overview of authenticationendpoint web app. The following are two such methods, the first one; easy and quick, the second one; not so easy and involves some code compiling, but is much neater.

When a request comes to the default login page, if you check the address bar, you would notice several parameters being passed. Out of them, for this customization we are going to focus on the following two:

  • sessionDataKey: This is an identifier used by the Identity Server to maintain state information related to this particular request by the service provider.
  • relyingParty: This is the value we gave for the "Issuer" field when we registered the SAML2 SSO service provider (e.g., This value is used to display different login pages to different service providers.

Also, make sure the following are applied when customizing the pages.

  1. Form submissions should happen to the "commonauth" servlet as a POST.

    <form id="form" name="form" action="../../commonauth" method="POST"> 
  2. Make sure to send back the "sessionDataKey" with the form submission, by using a hidden input field.

    Note: The CharacterEncoder class used below is available on IS 5.0.0 only after installing Service Pack 1. If your installation does not include the Service Pack 1, you need to use an appropriate encoding mechanism for request parameters to prevent any potential cross-site scripting vulnerability that could occur through parameter injection.

    <%@ page import="org.wso2.carbon.identity.application.authentication.endpoint.util.CharacterEncoder"%>
    <input type="hidden" name="sessionDataKey" value="<%=CharacterEncoder.getSafeText(request.getParameter("sessionDataKey"))%>"/>

Method 1: Using a JSP for redirecting to SP relevant pages

  1. Rename the existing 'login.jsp' to 'default_login.jsp'
  2. Create a new file with the name 'login.jsp' including the following code.

    String relyingParty = request.getParameter("relyingParty");
    if (relyingParty.equals("")) {
     RequestDispatcher dispatcher = request.getRequestDispatcher("travelocity_login.jsp");
     dispatcher.forward(request, response);
    } else {
     RequestDispatcher dispatcher = request.getRequestDispatcher("default_login.jsp");
     dispatcher.forward(request, response);

    What this code basically does is to forward the request to a different login page by checking the value of relyingParty parameter.

  3. Get the 'travelocity_login.jsp' from here and place it at the same level as 'login.jsp'. Also, download the contents of the 'css' and 'images' folders from that same link and put them inside the respective folders in the authenticationendpoint.
  4. Log in to the web app again. You are presented with a different page.
    If you access, it still displays the default login page.

Method 2: Using a Servlet for redirecting to SP relevant pages

  1. Check out the source code of the authenticationendpoint web app from the SVN location.
  2. Modify the existing located at src/main/java/org/wso2/carbon/identity/application/authentication/endpoint/samlsso/ as indicated below.

    public class SAMLSSOLogin extends HttpServlet {
        protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException,
                IOException {
             String relyingParty = request.getParameter("relyingParty");
             if (relyingParty != null && !relyingParty.isEmpty()) {
              String rpPage = getServletConfig().getInitParameter(relyingParty);
              if (rpPage != null) {
               request.getRequestDispatcher(rpPage).forward(request, response);
                request.getRequestDispatcher("login.jsp").forward(request, response);
            } else if (request.getRequestURI().contains("/")){
                request.getRequestDispatcher("samlsso_redirect.jsp").forward(request, response);
            }  else if (request.getRequestURI().contains("/")){
                request.getRequestDispatcher("samlsso_notification.jsp").forward(request, response);
  3. Build the source and replace the existing <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint.war file with the new war file. Also, delete the existing expanded authenticationendpoint folder at the same location.

  4. Start the server.

  5. Add init parameters to the "SAML2SSO" servlet in the web.xml file located in the expanded web app.


    You can add any new service provider page this way. You just need to provide the issuer value as the "param-name" and the customized page location as the "param-value".

  6. Get the 'travelocity_login.jsp' from here and place it at the same level as 'login.jsp'. Also, download the contents of the 'css' and 'images' folders from that same link and put them inside the respective folders in the authenticationendpoint.
  7. Log in to the web app again. You are presented with a different page as with Method 1.
  • No labels