Guide

Add custom CSS stylesheets

Suggest Edits

Screen Customization


You can use CSS to modify the look and feel of the Hosted Login screens; you do this by creating a supplementary stylesheet of your own (one that uses the same styles called out in Hosted Login’s default stylesheet) and then completing the following process:

  1. Place your new CSS stylesheet on a publicly-available website.

  2. Add the theming.stylesheetURLs setting to your Hosted Login application client. This can be done either by using the Identity Cloud Console or by using the Identity Cloud’s Configuration APIs.

  3. Set the value of theming.stylesheetURLs to the URL of the your default CSS stylesheet followed by the URL of the new stylesheet, separating the URLs by using commas. If you want, you can add even more custom stylesheets; just be sure you separate the stylesheet URLs by using commas.

To better explain the process, let's first take a peek at a stylesheet that updates several of the default styles (in this case, styles used on the sign-in screen):

screen-heading {
 margin-top:0;
 font-size:28px;
 text-align:center;
 width:520px
}

.screen-description {
 margin-top:0;
 font-size: 18px;
 width:520px;
 text-align:center;
 margin-bottom:30px
}

.additional-actions-container {
 text-align:center;
 background-color: peachpuff
}

.sign-in-button {
 background-color:orange;
 border-color:orange;
 color:black;
 font-size:18px
}

.footer-container {
 border-top: none;
 background-color:peachpuff
}

a.aic-control {
 text-decoration:none;
}

.cancel-link {
 display: block;
 text-decoration:none
}

.traditional-signin {
 position:relative;
 margin-top:30px;
 width:520px;
 font-size: 18px
}

.forgot-password-link {
 position: absolute;
 right: 8px;
 bottom:0;
 color:blue;
 font-size:18px;
 text-decoration:none
}

.social-signin {
 width:560px
}

.alternate-credentials {
 font-size:18px;
 margin-bottom:50px;
 text-align:center
}

If this stylesheet is publicly-accessible, and if the stylesheet is loaded after the default Hosted Login stylesheet, then the styles shown above should override the default styles. For example, by default the Sign In button is blue:

However, the custom CSS sets the color of that button to orange:

.sign-in-button {
 background-color:orange;
 border-color:orange;
 color:black;
 font-size:18px
}

So what color will the sign-in button be when the sign-in screen is displayed? We’ll find out in a minute. First, however, we need to talk a little bit about custom stylesheets and Hosted Login.


A few notes about custom stylesheets

As mentioned earlier, it’s important that you include the default stylesheet when configuring the theming.stylesheetURLs setting. As you might expect, the default stylesheet contains style settings for the items that can appear on a Hosted Login screen. Among other things, that means that, if the default stylesheet isn’t specified in the theming.stylesheetURLs, then any items not included in your custom stylesheet won’t have a CSS style. In turn, that means you’ll get some … interesting … results when Hosted Login tries to render your screens:

The point we're trying to make should be obvious from the preceding screenshot: make sure you include the default stylesheet in the theming.stylesheetURLs setting. 


📘

So what is your default stylesheet? That’s a good question, and the answer will vary depending on which version of Hosted Login you’re using. The best way to verify the stylesheets being loaded by Hosted Login is to go to your sign-in screen and then view the page source:


It’s also important that your custom stylesheet be listed after the default stylesheet. For example:

Does it really matter which stylesheet is listed first? As it turns out, yes, it does. When stylesheets are applied In Hosted Login, they’re applied in the order shown in the theming.stylesheetURLs setting. For example, suppose we have a hypothetical stylesheet that sets squares to blue and circles to red:

We then load a custom stylesheet that sets squares to green:

When our screen renders, we’ll see this:

That’s because we had a conflict between the two stylesheets: Stylesheet 1 set squares to blue and Stylesheet 2 set squares to green. Because Stylesheet 2 was the most-recently loaded stylesheet, it wins, and squares are green.


📘

Why are circles red? Because there was no conflict. As a result, circles were initially set to red, then never changed. A second stylesheet adds new styles not defined in the first stylesheet, or replaces conflicting styles. But it doesn’t remove styles defined in Stylesheet 1 that aren’t mentioned in Stylesheet 2.


Now, suppose we switch the load order of the stylesheets. In that case, the green square is applied, but it then gets overridden by the blue square. As a result, we see this:

Which is not what we were hoping to see.

Incidentally, if you manage to get yourself into a situation where nothing is rendering correctly, just remove the theming.stylesheetURLs setting altogether. If this setting can’t be found then Hosted Login reverts to using the default stylesheet. If nothing else, at that point you’ll be able to start over again.

And here’s something else to keep in mind: if a custom font type is specified in one of your stylesheets, that font must also be included in the theming.fontURLs setting. If it isn't, you'll get a CSP (Content Security Policy) error in the browser console and the font won't load.


Use Console to add a custom CSS stylesheet

To use Console to add a custom stylesheet to an application client, complete the following procedure:

  1. In Console, click Manage Properties and then click the name of your application client:

  2. On the Edit page, click Edit Settings:

  3. On the Edit Settings page, click the Add Setting icon:

  4. In the field for the new setting, type theming.stylesheetURLs and then click Create theming.stylesheetURLs:

  5. In the Value field for the theming.stylesheetURLs setting, enter the URL to your default stylesheet. You can then add additional stylesheets, separating the individual sheets by using commas. For example:

    https://v1.api.us.janrain.com/auth-ui/static/base.css,
https://dyzz9obi78pm5.cloudfront.net/app/image/id/5e5937aa8e121c00498350af/n/test.css

    Your new setting should look similar to this:

  6. Click Save Settings to save your changes:


Use the Configuration APIs to add a custom CSS stylesheet

To a custom stylesheet by using the Configuration APIs, start by calling the /config/{appId}/clients/{apiClientId}/settings operation and the GET method to return the current properties and property values of your application client. For example, if your application client has the client ID hrhtj4p8dz9wqhwtpuvg2k8ndet748vs, a Curl command to return the current properties and property values will look similar to this:

curl -L -X GET \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs/settings' \
-H 'Authorization: Basic 6rhfZmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNXNhY6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrpo9uZGo1Ynpxt5U=='

In turn, your API response will look similar to the following (with the obvious caveat that the properties and property values you get back will depend on how your application client is configured):

{
 "user\_entity_type": "GREG\_DEMO",
 "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs/settings",
 "default_flow_version": "HEAD",
 "default_flow_name": "videos",
 "regex_standard_newPassword": ".*",
 "janrainOidcClientId": "70a45721-c6ef-4d7c-91ff-f14e9346b8b6",
 "verify_email_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/verify-account?client\_id=70a45721-c6ef-4d7c-91ff-f14e9346b8b6",
 "site_name": "Test Public Client",
 "password_recover_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/reset-password?client_id=70a45721-c6ef-4d7c-91ff-f14e9346b8b6"
}

After you have the API response:

  1. Copy the entire response.

  2. Create a new API call, one that uses the /config/{appId}/clients/{client_id} operation and the PUT method.

  3. Paste the copied API response (still in JSON format) into the request body of the new API call.

For example, if you’re using Postman your screen will look similar to this:

In the custom property of the request body, add the theming.stylesheetURLs setting, configuring the value of the new property to the URL of the default stylesheet and the URL of the stylesheet being added to Host Login. For example: 

"custom": {"theming.stylesheetURLs": "https://v1.api.us.janrain.com/auth-ui/static/base.css,
https://dyzz9obi78pm5.cloudfront.net/app/image/id/5e5937aa8e121c00498350af/n/test.css"},

📘

If your request body doesn’t have a custom property you’ll need to add one and then configure the theming.stylesheetURLs setting inside the new custom property.


Your request body should look like this:

{
 "user_entity_type": "GREG\_DEMO",
 "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs/settings",
 "default_flow_version": "HEAD",
 "default_flow_name": "videos",
 "custom": {"theming.stylesheetURLs": "https://v1.api.us.janrain.com/auth-ui/static/base.css,https://dyzz9obi78pm5.cloudfront.net/app/image/id/5e5937aa8e121c00498350af/n/test.css"},
 "verify_email_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/verify-account?client_id=70a45721-c6ef-4d7c-91ff-f14e9346b8b6",
 "site_name": "Test Public Client",
 "password_recover_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/reset-password?client_id=70a45721-c6ef-4d7c-91ff-f14e9346b8b6"
}

In turn, your Curl command should look like this:

curl -L -X PUT 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs/settings' \
-H 'Authorization: Basic 6rhfZmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNXNhY6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrpo9uZGo1Ynpxt5U==' \
-H 'Content-Type: application/json' \
--data-raw '{
 "user_entity_type": "GREG\_DEMO",
 "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs/settings",
 "default_flow_version": "HEAD",
 "default_flow_name": "videos",
 "custom": {"theming.stylesheetURLs": "https://v1.api.us.janrain.com/auth-ui/static/base.css**,**https://dyzz9obi78pm5.cloudfront.net/app/image/id/5e5937aa8e121c00498350af/n/test.css"},
 "verify_email_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/verify-account?client_id=70a45721-c6ef-4d7c-91ff-f14e9346b8b6",
 "site_name": "Test Public Client",
 "password_recover_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/reset-password?client_id=70a45721-c6ef-4d7c-91ff-f14e9346b8b6"
}
'

Now make your API call. If all goes well, you’ll get back both a 200 OKHTTP status code and a response that includes the new set of property values assigned to the application client.


📘

Why do you have to copy all the property values and include all those values in your API call? That’s because the PUT method is all-or-nothing: it replaces all the settings currently assigned to the application client with the settings you have explicitly specified in your API call. Suppose your application client includes the default_flow_name and default_flow_version settings, but you forget to include those in your API call. When you make your call, those two settings will be deleted from the application client.


Verify your stylesheet

To verify that Hosted Login is using your custom stylesheet, wait a minute or two for your changes to take effect, then access your Hosted Login sign-in screen. If your new styles are used on the sign-in screen, you should see those new styles in action (for example, note the color of the Sign In button):

If those styles aren’t used on the sign-in screen you’ll have to click around a bit until you come across a screen where those new styles are employed.

Updated almost 2 years ago