Theming


We're Moving ... Again

Yes, the Identity Cloud documentation is once more on the move. And this time we're headed to two different locations:

As for the Education Center, well, the Center itself will disappear on July 23rd. We apologize for any inconvenience, but we look forward to becoming a full-fledged member of the Akamai family.
 

By default, your Hosted Login login screen looks similar to this:

Most likely this isn’t exactly the way you want your login screen to look like; at the very least, you’d probably want to replace the Akamai logo with a logo of your own. For its initial release, Hosted Login is not fully customizable. However, by using a combination of API calls and CSS (cascading style sheets), you can easily create a login screen that looks, say, like this one:

In may not be a work of art, but it’s unlikely people will mistake this login page for the default Hosted Login login page.

In this documentation, we’ll provide tips on customizing your login and registration screens, including information on how to:

  • Change the Logo
  • Change the Favicon
  • Modify Your Hosted Login CSS Settings

Important. Before you begin, you might want to read the article API Clients and API Client Settings. That article provides some very useful information on how to update API client settings, something you’ll need to do as part of the customization process.

Changing the Logo

It probably goes without saying that the logo is the primary way a page lets users know where they are and – perhaps more important– which website they’re about to log on to. For example, in the login dialog below, it’s should be obvious that you’re about to log on to an Akamai website:

Of course, unless you are an Akamai website, you’d probably prefer to display your own logo in the dialog box. Fortunately, you can change the logo by completing the following procedure:

  1. Place the image file for your new logo on a publicly-available website.
  2. Add the theming.logoURL setting to the Hosted Login API client associated with the OIDC client that handles logons and registrations. Set the value of theming.logoURL to the URL of the new logo. This is done by using the /config/{app_id}/clients/{client_id}/settings endpoint.

For example, the following Curl command changes the logo for the API client brg3q7xh8try6yy7clo09te24qaw487h5:


curl -X PUT \
 https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487h5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \ 
  -H 'Content-Type: application/json' \
  -d '{"custom": [
     "theming.logoURL":"https://dyzz9obi78pm5.cloudfront.net/app/image/id/5c9169d16e121c920956f573/n/new-logo.png"}
}
'

Note that, before you run the preceding script and attempt to change the logo, we strongly recommend that you read the article on API Client Settings.

Changing the Favicon

Favicons are tiny icons that, depending on your web browser, are displayed in your browser address bar and/or browser tabs. For example, here’s an Akamai favicon as displayed in a Firefox browser tab:

Similar to logos, favicons can be modified by completing the a simple two-step process:

  1. Place the image file for your new favicon on a publicly-available website.
  2. Add the theming.faviconURL setting to the Hosted Login API client associated with the OIDC client that handles logons and registrations. Set the value of theming.faviconURL to the URL of the new logo. This is done by using the /config/{app_id}/clients/{client_id}/settings endpoint.

For example, the following Curl command changes the favicon for the API client brg3q7xh8try6yy7clo09te24qaw487h5:

curl -X PUT \
 https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487h5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \  
  -H 'Content-Type: application/json' \
  -d '{"custom": {
"theming.faviconURL":"https://dyzz9obi78pm5.cloudfront.net/app/image/id/5c9169d16e121c920956f573/n/new-favicon.png"}
'

Similar to changing the logo, we recommend that you read the article on API Clients and API Client Settings before running the preceding script.

Note. What size should your favicon be? What file format should you use for your favicons? To be honest, those answers depend on the expected use for your favicons as well as the browsers your users are likely to be employing. For more information, see https://www.emergeinteractive.com/insights/detail/the-essentials-of-favicons.

Modifying Your Hosted Login CSS Settings

You can use CSS to modify the look and feel of the Hosted Login screens; this is done by creating your own CSS file (in place of the default stylesheet Style.css) and then completing the following process:

  1. Place your new CSS file on a publicly-available website.
  2. Add the theming.stylesheetURL setting to the Hosted Login API client associated with the OIDC client that handles logons and registrations. Set the value of theming.stylesheetURL to the URL of the new CSS file. This is done by using the /config/{app_id}/clients/{client_id}/settings endpoint.

For example, the following Curl command changes the CSS file for the API client brg3q7xh8try6yy7clo09te24qaw487h5:

curl -X PUT \
 https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487h5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
  "theming.stylesheetURL":"https://dyzz9obi78pm5.cloudfront.net/app/image/id/5c9169d16e121c920956f573/n/new-style.css"
}
'

To create a custom CSS file, it’s highly recommended that you start with (and then modify) Style.css, the default CSS file for the login, registration, and user profile screens (you can download a copy of style.css here). You can then modify the downloaded version of Style.css and use the API call to point to the new stylesheet.

Style.css has nearly 600 lines of code, covering scores of different styles. Some of the more useful (and more noticeable) styles are briefly described (and illustrated) in our CSS Reference documentation.