Theming for Subscribers

Introduction

CILogon supports theming for subscribers at the Essential and Full Service levels. Theming is available for both the CILogon Authorization site (i.e., how users select and log on to their federated Identity Provider) and the CILogon Registry (i.e., how administrators manage authorization groups and OIDC clients).

Theming of the CILogon Authorization site is achieved through the use of "skins". Skins can change both the look (e.g., CSS) and behavior (e.g., custom list of Identity Providers) of the CILogon site.

Theming of the CILogon Registry is achieved by specifying custom CSS and optional JavaScript snippets. See Theming COmanage Registry for details.

The remainder of this page focuses on developing and using "skins" for the CILogon Authorization site.

Applying a Theme

A custom theme (a.k.a., "skin") can be applied in one of the following ways:

Pass a query parameter "?skin=<skinname>" or "?vo=<skinname>" ("vo" is short for "virtual organization"). Since this is a client-side parameter, subscribers can easily set the skin from their home portals. However, a savvy user could remove or alter the query parameter of the URL and change the theme to something unexpected. This can be prevented by using the next option.
Apply the skin for a specific OAuth2/OIDC client_id, admin_id, or redirect_uri. CILogon administrators can configure a server-side setting which forces the skin to be applied during an OAuth2/OIDC transaction. This allows the skin to be applied automatically for subscriber portals, and also prevents users from bypassing the configured skin. Currently, this configuration is not self-service. There is a feature request to make this an option which can be set by subscribers without CILogon staff intervention.

Changing the Appearance

CILogon "skins" allow for the inclusion of custom CSS to change the appearance of the various webpages. Here are a few examples of custom CSS used by CILogon subscribers.

https://cilogon.org/default - The default CILogon interface. Use this URL to reset your skin back to the default.
https://cilogon.org/?skin=illinois - This skin provides an customized interface for the University of Illinois.
https://cilogon.org?skin=ooi - This skin provides a customized interface for Ocean Observatories Initiative users.
https://cilogon.org?skin=osg - This skin provides a customized interface for Open Science Grid users.
https://cilogon.org?skin=access - This skin provides a customized interface for ACCESS CI users.
https://cilogon.org?skin=esnet - This skin provides a customized interface for Energy Sciences Network users

When theming the CILogon site, please ensure that CSS applies to the following pages:

https://cilogon.org/ - The "discovery" interface where users choose their Identity Provider (IdP)
https://cilogon.org/authorize/ - The OAuth2/OIDC "authorization" page where users consent to attribute release
https://cilogon.org/me/ - The "attribute" page which shows the user's current browser and session cookies
https://cilogon.org/device/ - The "device flow" page used when client devices are input-constrained (i.e., no browser)
https://cilogon.org/logout/ - The "logout" page which clears CILogon session cookies

CILogon uses Bootstrap 4.6.x for CSS and Bootstrap Select 1.13.x for the "Select an Identity Provider" selection list. A skin's CSS is stored in the database and output to a <style> block in the <head> of the HTML.

Note: A skin's CSS might include references to external images. We would prefer that those images be served from local infrastructure. With a subscriber GitHub repository (see "Requesting a Skin" below), images can be provisioned from GitHub to the local file system. These images can then be referenced by the skin's CSS.

Changing the Behavior

CILogon has several customization options which change the behavior and/or content of the CILogon website. The full list of options can be found in config-example.xml . (You may need to use your browser's "View Page Source" function to see the contents of the XML file.) Here are a few common configuration options used by subscribers.

Change the list of available Identity Providers (IdPs) - By default, the list shown in the "Select an Identity Provider" selection list consists of several thousand SAML-based IdPs (e.g., universities) and several OAuth2-based "social" IdPs (i.e., ORCID, Google, Microsoft, and GitHub). This list can be curated by including only a subset of IdPs or by excluding a subset of IdPs. IdPs can be configured individually or by Registration Authority.
Set the IdP selected for new users - By default, ORCID is the first IdP shown to new users. Subscribers can change this to their home organization for easy selection by their university users, for example.
Change links on the CILogon IdP Selection page - Subscribers can change links of several elements such as the favicon, header images, and footer text.
Add HTML to the top and bottom of the page - By adding HTML to the top and/or bottom of the page, Javascript can be used to insert a navigation bar at the top of the page, for example. Javascript can also be used to dynamically change the DOM for more advanced customization scenarios.

Bypassing CILogon

It's possible that no amount of theming the CILogon website will be sufficient for a subscriber's use case. If so, a subscriber could run their own "discovery" page and use CILogon only for the delegation of IdP attributes. The CILogon Authorization page can be "bypassed" by one of two methods.

Always bypass - In this scenario, a subscriber portal needs exactly one IdP to be used for logging on.
Allow to bypass - In this scenario, a subscriber portal specifies one of several IdPs to be used for logging on.

In either case, it is assumed that the subscriber portal displays a "consent to release attributes" notice to the end user letting them know that certain attributes (e.g., name, email address, and/or other user identifiers) will be released by CILogon to the subscriber portal.

Requesting a Skin

When a subscriber requests a skin to be applied for their portals, CILogon staff will first create a GitHub repository named something like "<subscriber>-policies". Read-only access for this repo will be granted to subscriber staff. The repo is to be used for documenting access policies as well as skin configuration. Subscriber developers will design CSS for their CILogon skin(s). Skin configuration files (i.e., skin.css and/or config.xml) live in the "main" branch in a skins subdirectory, while images (e.g., subscriber-logo.png) live in the dev, test, and prod branches in an images subdirectory (to allow for different images for testing and production).

Currently, skins must be loaded on to CILogon servers by CILogon staff. Subscribers make pull request to their <subscriber>-policies respository, and CILogon staff apply the changes to the CILogon servers. There is a feature request to make skins configurable by subscribers without CILogon staff intervention, but for now, skin configuration is a collaborative process.

For more information, please contact help@cilogon.org .

Report abuse