Your Pega application uses several rules that correspond to each screen accessed by unauthenticated operators (users who have not logged in). Pega Platform™ allows you to customize these screens—including the login screen, authentication screen, logout screen, and other screens—through their source HTML and custom cascading style sheets (CSS).

You might want to edit your application login screen to display a new logo or background image for your application, to maintain design consistency according to your enterprise style guide, or to change the single sign-on button appearance. 

Before you begin

If you have not yet done so, create an authentication service. Your application requires an authentication service for users to securely log in. For more information, see Creating an authentication service.

Configuring a Browser requestor type

After you create an authentication service, you must associate a Browser requestor and Pega application with an unauthenticated Access Group and ruleset to synchronize customizations of your login screens with your application by performing the following tasks:

1. Create a new system (on-premises only). 
2. Associate the system with the Browser requestor (on-premises only).
3. Create an Access Group to associate with the Browser requestor.
4. Create an unauthenticated ruleset.
5. Include the unauthenticated ruleset in your Access Group.
6. Adding the ruleset stack to your application.
7. Update the Browser requestor type.

Creating a new system (on-premises only)

Create a system to later associate with the Browser requestor. The system identifies a single instance of your Pega Platform occurrence for your unauthenticated operators to access.

1. In the navigation header of Dev Studio, click Create > SysAdmin > System.
2. In the Create System rule form, enter a short description and a system name.
3. Note the system name for future use.
4. Click Create and Open.
5. Click Save.

Associating the system with the Browser requestor (on-premises only)

Create a new dynamic system setting that associates the new system with the Browser requestor.

1. In the navigation pane of Dev Studio, click Records > SysAdmin > Dynamic System Settings.
2. In the Setting Purpose column, click the Search icon (▼).
3. In the Search Text field, enter prconfig/identification/systemName/default.
4. Click Apply. 
5. Click the resulting row.
6. In the Value field, associate the requestor with the system that you created by entering the new system name.
7. Restart the application server.

Creating an Access Group to associate with the Browser requestor

Save a copy of the PRPC:Unauthenticated Access Group to maintain its roles for unauthenticated operators.

1. In the navigation pane of Dev Studio, click Records > Security > Access Group.
2. In the Access Group Name column, click the Search icon (▼).
3. In the Search Text field, enter PRPC:Unauthenticated.

4. Click the resulting row.

5. In the rule form header, select the list next to the Save button.

6. Click Save As.

7. In the Save Access Group As form, enter a short description and a name for the Access Group.

8. Click Create and Open.
9. In the Application section of the Access Group rule form, enter the following information:
   1. The name of the application that you want to customize.
   2. The version of the application that you want to customize.
10. In the Available portals section, select the portal for which you want to customize the login screen HTML and CSS. 
11. Click Save.

Creating an unauthenticated ruleset

Create a ruleset for an unauthenticated operator to access the Browser requestor session used by the login screens.

1. In the navigation pane of Dev Studio, click Records > SysAdmin > Ruleset. 
2. In the Create Ruleset Version field, enter the following information:
   1. A ruleset name. Include a hyphen (-) and unauthenticated after the ruleset name, for example: <rulesetname>-unauthenticated
   2. The ruleset version, for example: 01-01-01
   3. A description for the ruleset.
3. Note the unauthenticated ruleset name and version for future use.
4. Click Create, then click Save.

Including the unauthenticated ruleset in your Access Group

Add the unauthenticated ruleset that you created to the unauthenticated Access Group.

1. In the navigation tabs of Dev Studio, select your unauthenticated Access Group.
2. In the Run time configuration setting section, in Production Rulesets, add the ruleset that you created.

Adding the ruleset stack to your current application

Add the unauthenticated ruleset that contains the unauthenticated Access Group and its composite roles to your application.

1. In the navigation header of Dev Studio, select Configure > Application > Structure > Ruleset Stack.
2. Select the application for which you want to edit the web login HTML and CSS.
3. Click Add ruleset.
4. Add the unauthenticated ruleset that you created to associate with the Browser requestor.
5. Click Save.

Updating the Browser requestor type

Update the Browser requestor to use the unauthenticated Access Group:

1. In the navigation header of Dev Studio, select Configure > System > General > Requestors.
2. In the Requestors list, select the Browser requestor that is associated with the system that you created.
3. In the Access Group Name field, enter the Access Group that you created.
4. Click Save.

You associated the Browser requestor with the Pega application and its unauthenticated ruleset, and can now customize the login screens for unauthenticated operators.

Editing the source markup language to customize the login screens

Your Pega application uses several rules that form the source markup HTML and CSS of your login screens. To customize these login screens, you can add your own HTML structure, CSS elements, or background images to the source fields in each of their respective HTML and Text rules.

You can edit the source markup language by completing the following tasks:

• Edit the source HTML of your login screens
• Edit the CSS of your login screens
• Add a new background image to your login screens

HTML rules containing source HTML for login screens

If you want to edit the source HTML of your login screens, open the HTML rules your Pega application uses, then edit the source HTML. HTML rules containing your login screen source HTML include the following items:

Editing the source HTML of your login screen

Customize the HTML of your login screen.

1. In the navigation pane in Dev Studio, open the existing HTML rule by clicking Records > Technical > HTML.
2. In the Stream name column, click the Search icon (▼).
3. In the Search Text field, enter the rule name of the login screen that you want to edit.
4. Click Apply.
5. Click the resulting row.
   Pega Platform displays the HTML rule form.
6. In the Generate For list, select whether your customized login screen uses HTML directives or JavaServer screen (JSP) tags.
7. In the Browser Support list, select whether Modern browsers or Microsoft Internet Explorer only (IE only) support your customized login screen.
8. In the Accessibility list, tag whether your customized login screens meet your requirements when calculating the application Accessibility compliance report.
   For more about Accessibility compliance reports, see Using the Accessibility report.
9. In the HTML source field, enter your customized login screen HTML. 
   1. (Optional) If your customized login references to  clipboard pages, click the Pages and Classes tab.
   2. (Optional) Enter the required clipboard pages and the classes to which they belong.
10. Click Save.
    The customized HTML of your login screen is built into your application instance of Pega-Engine.
11. Click Check-in to add changes to the unauthenticated ruleset you created.
12. In the Actions list, select Preview.

13. Confirm that the login screen reflects your customized HTML.

For more information about HTML rules, see About HTML rules.

Text rules containing source CSS for login screens 

Your Pega application uses the following Text rules to form the login screen.

Editing the CSS of your login screen

Edit these Text rules to customize the CSS of your login screens.

1. In the navigation pane in Dev Studio, open the existing Pega login Text rule by clicking Records > Technical > Text.
2. In the Stream name column, click the search icon (▼).
3. In the Search Text field, enter the rule name of the login screen or IDP button you want to edit.
4. Click Apply.
5. Click the resulting row.
   Pega Platform displays the associated CSS file.
6. In the CSS field, enter your customized login screen CSS, or upload a new CSS file. 
7. Click Save.
   The customized HTML of your login screen is built into your application instance of Pega-Engine.
8. Click Check-in to add changes to the unauthenticated Pega ruleset you created.

9. Confirm that the login screen reflects your customized CSS.

Adding a new background image to your login screen

You can integrate a custom background image into your Pega application login screen HTML through a binary file.

1. In the navigation header of Dev Studio, select Create > Technical > Binary File.
   Pega Platform displays the Binary File Record Configuration form.
2. Complete the configuration form:
   • In the Label field, enter a unique label for the image.
   • In the App Name (Directory) field, enter webwb.
   • In the File Type (extension) field, enter the Windows extension (for example, png, jpeg) for the file you want to upload to the binary file. Do not include a period.
3. In the Context section, select the application that contains your unauthenticated ruleset.
4. In the Add to ruleset list, select the unauthenticated ruleset that you created.
5. Click Create and open to display the Binary File rule form.
6. Click Upload file to open the file browser.
7. Click Save.
   In the Image details section, Pega Platform displays the file that you uploaded and its dimensions.
8. Note the dimensions of the image for future use in the CSS file.
9. In the navigation pane of Dev Studio, select Records > Technical > Text File.
10. In the File Name column, click the Search icon (▼).
11. In the search text field, enter the Text rule that contains the CSS of the login screen you want to customize with the image as a background.
    For more information, see Text login rules.
12. Click Apply.
13. Click the resulting row.
14. Press CTRL + F and enter the following text: body { 
15. In the background-image element, replace the existing values with the image name and extension in the following format: 
    url(image_name.extension);

16. Below the background-image element, enter a background-size element with the dimensions of the image for width and height in pixels (px), for example:
    background-size: widthpx heightpx;

    
    
17. Click Check-in to add changes to the unauthenticated ruleset that you created.
18. Confirm that the background image appears correctly on your background for the selected login screen.