ERROR PAGES CUSTOMIZATION — WSO2 IDENTITY SERVER 5.11.0
WSO2 Identity Server 5.11.0 has several default error pages in authentication flows (OAuth2 / OpenID Connect and SAML authentication). But there can be some requirements that we need to change the look of these error pages. This article will show you how to do the customizations to the identity server default error pages in authentication flow.
First, we need to download the latest WSO2 Identity Server (Current 5.11.0) from here and click “TRY IT NOW” and choose a suitable option from the list of platforms.
As I have Ubuntu 20.04 running on my laptop I choose ubuntu installer deb. After the installation, you can find the installed wso2 identity server in “usr/libs/wso2/wso2is/5.11.0/”.
In the authentication flow identity server has four error pages that we can customize(error pages and the places they located in may depend on the identity server version). These error pages are located in <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/.
Please note that this error pages related to OAuth2 / OpenID Connect and SAML authentication flows.
1. retry.jsp.
2. generic-exception-response.jsp
3. oauth2-error.jsp
4.samlsso-notification.jsp
If all the error pages follow the same template, as best practice we can create separate CSS file(s) to add common CSS styles.
You can create CSS file in <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/css/ directory. Then we need to link the CSS file with above mentioned JSP error pages. All you need to do is add the below code snippet to the head tag in JSP pages.
<head>
<link href="css/errorPageStyles.css" rel="stylesheet" type="text/css">
...
</head>If you need to know more about authentication flows check out these.
If you curious about finding error pages your own, you can follow the below steps to find out what are the responsible error pages.
- checkout the error URL from the browser that you need to customize when displaying the error. ( Eg: error.do is a one URL pattern you can find while error displays)
- Then you can check the web.xml file located in <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/ .
There are few HTML pages that located in <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/errors directory. You can change the styles for them as well.
The other best way to research error URLs is to deploy a sample web application and connect to the identity server. Then you can intentionally do mistakes on each authentication flows (Eg: changing call back URL, change client id, client secret) and check what are the errors getting, and extract the URL patterns. Then you can find the respective mapped pages.
We discussed what are the error pages in authenticationendpoint webapp. If you are in mind to change all the error page styles in <IS_HOME>/repository/deployment/server/webapps/ directory there are few other webapps that we need to change the styles. They are,
- accountrecoveryendpoint webapp
- emailotpauthenticationendpoint webapp
- smsotpauthenticationendpoint webapp
- totpauthenticationendpoint webapp
- x509certificateauthenticationendpoint webapp.
Following are the error pages that you need to change styles in above mentioned webapps.
1). accountrecoveryendpoint
•error.jsp
• html pages => accountrecoveryendpoint/errors2). emailotpauthenticationendpoint
• emailotpError.jsp3). smsotpauthenticationendpoint
• smsotpError.jsp4). totpauthenticationendpoint
• totpError.jsp5). x509certificateauthenticationendpoint
• x509CertificateError.jsp
You can have the same approach as I mentioned earlier to have a common CSS file in each webapp’s CSS directory and link it to the particular JSP/HTML file.
Hope you got an idea about what are the error pages in the WSO2 identity server and how to change the theme.
Thank you for reading this article…
