Customizing Public Pages#
Public pages include:
- All included sign-in pages
- Password Recovery
- Error Pages
- Logout pages
Before changing any default files, we recommend creating backups!
The Gluu Server's public facing pages are XHTML files. Each Gluu Server component is deployed as a separate archive in WAR format. When any component's service is started, its archive is unpacked ("exploded") to Jetty's temporary file directory located under
/opt/jetty-<VERSION>/temp/ before it can start serving requests for associated functionality.
To add customizations, the appropriate file needs to be changed either at that temporary location, or inside the corresponding archive itself. Changes made directly to unpacked files under
/opt/jetty-<VERSION>/temp/ will not be persisted--each time a component's service is restarted its WAR archive will be re-exploded, overwritting the existing content on the disk.
A typical example is customizing the default oxAuth login page. There are two ways to achieve this:
Un-pack the needed files from
/opt/gluu/jetty/oxauth/webapps/oxauth.warwith a tool like
jar, update them and add them back to the archive with all required dependencies (not recommended);
Add the changed files under
/opt/gluu/jetty/oxauth/custom/directory, so they can be used instead of the standard files in
oxauth.war. (Note: the same approach will work for oxTrust if files are placed under
The benefit of using the second approach is that customizations will not be disrupted when changes are made to the WAR files, for example, if the instance is patched or updated, and a WAR archive is overwritten. More on this method below.
Directory structure and mappings#
Directory trees are included inside the Gluu Server
chroot to make page customizations easier. Each tree is placed in the configuration directory of the corresponding Gluu component (only customization of oxAuth and oxTrust pages is supported at the moment by this feature).
The directory structure can be illustrated as follows (only directories related to this feature are shown for clarity):
/opt/gluu/jetty/oxauth/ |-- custom | |-- i18n | |-- libs | |-- pages | `-- static
/opt/gluu/jetty/identity/ |-- custom | |-- i18n | |-- libs | |-- pages | `-- static
i18n should be placed in the following directories:
custom/pages have a special purpose. They enable overriding exploded
xhtml pages from the unpacked WAR archive. The path to exploded war conforms to following scheme:
So, for example, the path to an exploded oxAuth's WAR archive directory may look like this (and may be changed the next time the corresponding service is restarted):
Thus, a modified
login.xhtml page put under
custom/pages/ will be used instead of
webapp/login.xhtml from the exploded archive. You can use files unpacked there as a base for your own customized files.
Jetty included in earlier Gluu 3.x packages is known to create duplicated directories under
/opt/jetty-<VERSION>/temp/ for each of its components. In case you encounter this issue, it's recommended to stop the corresponding service and remove all related subdirectories from the
temp/ directory. After re-starting the service, its WAR archive will be unpacked again.
libs for oxAuth should be placed in the following directories:
Custom CSS or images should be placed under
custom/static directory. To avoid collisions with static resources from WAR files, Gluu maps this folder to URL's path like this:
So, for example, CSS file placed at this path:
...will be externally available at a URL similar to this:
...and should be referenced from inside of source codes of customized files by path like this:
All images should be placed under:
Add your logo here to be displayed on every public facing page. Place your image in
/static/img and name it
And all CSS are inside:
Location of key webpage source files#
Default Gluu's public-facing pages can be a good base for your organization's customized ones. Aside from extracting them directly from a corresponding WAR file, they can be found at Jetty's temp directory to which they are unpacked each time a corresponding service starts.
oxAuth is the core Gluu CE component, handling all authentication in the framework and implementing OpenID Connect and UMA flows. Most of the web UI pages displayed to end users belong to oxAuth (login/logout/authorization flows).
- Default login page:
- Authorization page:
- Logout page:
- Error page:
- Custom authentication scripts; XHTML files under:
oxTrust is responsible for displaying the Gluu Server's default registration page, as well as the administrator web UI's pages.
- Registration page:
The oxAuth and oxTrust services need to be restarted for customizations to be applied. The next commands will restart corresponding Jetty's JVMs inside container:
# service oxauth stop # service oxauth start # service identity stop # service identity start
There is a 10 second delay on page modification reload.
An Example: Changing Primary Key name for Login#
Your organzation might use "Email Address" as the primary key for users instead of "Username". In this example, we will change the field on the login page from "Username" to "Email Address".
Log into the Gluu container:
# service gluu-server-3.1.6 login
cp /opt/jetty-9.4/temp/jetty-localhost-8081-oxauth.war-_oxauth-any-13153919175814468.dir/webapp/login.xhtml /opt/gluu/jetty/oxauth/custom/pages/
Modify attribute value to 'Email Address' under the
.... .... <h:inputHidden id="platform"/> <h:panelGroup> <div class="form-group"> <h:outputLabel styleClass="col-sm-4 control-label" for="username" value="Email Address" /> <div class="col-sm-8"> .... ....
Restart oxAuth's service inside the container to display the changes:
service oxauth stop && service oxauth start
Don't forget to apply appropriate file system permissions if needed.