OAuth Theming

1. Theming

We have built Passport Frontend with the intent that you’ll want to customize the the layout colors and style to make it your own. Logging in with Passport should be as seamless as possible with your existing application. This guide will get your on your way to customizing the Passport Frontend.

Once you’ve installed Passport Frontend, you’ll find the default theme in the following location:

Linux or Mac OS X

/usr/local/inversoft/passport-frontend/web/themes/default

Windows

C:\inversoft\passport-frontend\web\themes\default

The following is a typical example of how you’ll go about theming Passport Frontend.

  1. Copy the default directory

  2. Update the configuration to use the new theme

  3. Start theming!

1.1. Copy the default theme

$ cd /usr/local/inversoft/passport-frontend/web/themes
$ cp -Rp ./default vandelay

1.2. Update the configuration to use a different theme

In the Passport configuration file, edit the passport-fronted.theme property as follows, and then restart Passport Frontend.

passport-frontend.theme=vandelay

1.3. Start Theming!

In your newly created theme directory, you’ll find a file structure that contains all of the HTML templates, CSS, JavaScript and translated text.

vandelay
  |
  |- control-templates
  |- css
  |- images
  |- js
  |- messages
  |- templates

You’ll most likely only need to modify the HTML templates and CSS to style the templates to look like your own website. The file structure may not be modified, in other words you may not move or rename files, doing so will cause the Passport Frontend to fail.

The theme mechanism works by re-writing the URI to the resource. For example, in the _macros.ftl template in which we define the HTML body header, you’ll notice the logo graphic is referenced with a path of ${request.contextPath}/images/logo.png. However the location of this image file is not /images/logo.png but /themes/vandelay/images/logo.png. This URI re-write is handled by our theme engine and simply means that if you need to access resources such as CSS, JavaScript or images inside of your templates, you’ll want to assume the root is that of your theme directory.

1.4. Templates

Our templates are written in a template engine called Apache FreeMarker. Except where documented inside of the template, all form fields are necessary for proper operation. You may however modify the layout of the page, add additional HTML elements, etc.

The directory structure provided in the theme should be somewhat self documenting, but if you’re looking to customize a specific page the following table may help you identify what templates need to be updated. Template paths referenced here are relative to the root of the theme directory.

Page Template

Login

/templates/oauth2/authorize.ftl

Two Factor Challenge

/templates/oauth2/two-factor.ftl

Forgot Password

/templates/password/forgot.ftl

Change Password

/templates/password/change.ftl

Password Change Complete

/templates/password/complete.ftl

Password Change / Forgot Email Sent

/templates/password/sent.ftl

1.5. Messages

The message files follow the same file structure layout as the templates. You are free to modify any of the text you find in the message bundles.

You may add text directly to the templates if you’d like, or if you want the possibility of localization of that message, add it to the appropriate message file. The messages are stored as key value pairs.

To add a new message, consider the following two messages.

# Standard message
companyTitle=Vandelay Industries
# Message with replacement text
jobTitle=I am a %s salesman.

Then from a FreeMarker template, you may utilize these new messages using the following syntax.

[@global.message key="companyTitle"/]
   Output: Vandelay Industries
[@global.message key="jobTitle" values=["latex"]/]
   Output: I am a latex salesman.