Configuration of web embed

Discussion

Eliseo Olla

Member since 2013

4 posts

PEGA

Posted: 1 day 21 hours ago

Last activity: 1 day 20 hours ago

Posted: 28 Nov 2024 10:11 EST
Last activity: 28 Nov 2024 11:12 EST

Configuration of web embed

Note: The article is part of the Constellation 101 series that provide practical insights in using Constellation features.

Why

Web embed is the functionality in Constellation that let customers expose Pega through their web sites or portals. It is possible to create a case, open an assignment, or open a landing page by using Web embed functionality. Technically, Web Embed is a HTML fragment generated in App Studio on Channels landing page, which is later injected into target client website. The fragment generated by App Studio is the a standard template that can be later modified by client, as and when needed.

While the configuration of the web embed snippet is straightforward, authentication and styling are the topics which can be more complex.

Second important topic is styling. Web embed has many styling options that let you personalize the Pega screens styled through themes defined in Pega App Studio or do more advanced configuration of the JSON schema using Pega Dev Studio.

Business use cases

Web embed can be particularly useful in scenarios where seamless integration and interaction between systems are required. Here there are some few examples:

Customer Service Portals: Integrate Pega's case management capabilities into existing customer service portals.
Self-Service Applications: Embed Pega processes within customer-facing web applications.
Financial Services: Embed loan processing or account management workflows into banking websites.
Healthcare Systems: Integrate patient management or appointment scheduling features within healthcare portals.
Insurance Claims Processing: Embed claim submission and processing workflows within insurance company websites.
Internal Corporate Applications: Integrate Pega's task management or HR processes into internal corporate portals

Benefits

Using web embed, customers can access the Pega business processes in their site(s).
Low code way of integration Pega inside customer portals without the need for expensive development
The Pega App Studio theme feature is available to define the style of your web embed. If required, thanks to the theme attribute it is possible to style your case in accordance with the brand guidelines of the customer web site.
Web embed resolves one of the problems of Mashups as it does not use IFrames, which creates problems related to use of popups to authenticate, popup blockers and third-party cookie blockage.

Authentication patterns supported

Authentication patterns in web embed are configured through the grantType attribute which identify the authentication flow (see grant type field options available in the web embed configuration screen). The authentication flows follows the OAuth 2.0 specification where the /authorize and /token endpoints are used to get access token to access the Pega applications through web embed.

The authorization code grant flow is the most used OAuth 2.0 authentication method and it is used mostly by the back-office applications. The custom bearer grant flow is used by Internet facing applications and banking institutions that do not want to deal with issues of redirects through screens popups, pop up blockers, or third-party cookie blockage. The custom authentication grant flow is managed by a custom authentication service and grant type attribute is set to none. While in the authorization code grant flow (where an authentication service of type OIDC or SAML is specified via the authService attribute) security is delegated to the IdP in custom bearer and custom authentication grant flows security must be enforced in the authentication activity.

The following authentication patterns are supported via defining the grantType attribute in web embed.

Authorization code grant low – grantType = authCode (client-initiated grant flow) supports following use cases:
- OIDC authentication using an external identity provider configured by Authentication Service of type OIDC
- SAML v2 authentication using an external identity provider configured by Authentication Service of type SAML 2.0
- Authentication using existing OOTB WebLDAP authentication service
- Authentication using pega authentication service
Custom bearer grant flow – grantType = customBearer (client-initiated grant flow) supports following use case:
- Fully custom authentication based on a specified Activity with ability to post custom params from client as part of such an access_token acquisition request
Custom authentication – grantType = none and authHeader specified
- Authentication token acquired from the Pega server by a 3rd party server-initiated OAuth 2.0 confidential grant flow (typically JWT Bearer)
- Algorithmically derived authentication header correlating to the non-OAuth 2.0 authentication type configured for the “Application” service package (Basic or Custom)

Authentication patterns not supported

Anonymous authentication is not supported in Constellation design system.

How to implement

Please refer to web embed in Constellation to learn how to configure web embed.

Here are the key configuration points.

Step1. Configuration of the web embed channel

The web embed configuration is described in Creating a web embed. Here there the most important high-level steps.

From the list of channels in App Studio, create a new web embed and provide a name.
Define authentication service to use depending on the authorization grant flow (authentication code, custom bearer or custom).
Check the URL of your Pega instance to use when login through the external web site.
Select the action you can perform: opening a case or open a portal page
Select the case type web embed must open.
Select if to display a Case, an Assignment or Get next work
Click Generate the web embed to generate the Java Script snipped code.
Additionally, you can customize the autogenerated markup and add JavaScript code to invoke supported methods and event handlers to adapt the web embed to your needs

Web embed configuration screen

Note: As you save the web embed, Pega will generate a new OAuth 2.0 client registration rule whose name is WebEmbed_ApplicationName.

Step2. Select the authentication pattern

Configure authentication based on OAuth 2.0 framework as this is the protocol being used by web embed to communicate with Constellation design system through DX-API v2.

Depending on customer’s use case, select one of authentication patterns (discussed in section “Authentication patterns supported:”)

Note: the most important attribute that you configure in web embed, depending on the authentication pattern used:

grantType attribute to select the desired grant flow.
clientId attribute to specify the clientId generated in the OAuth 2.0 client registration rule. This is not required if using custom authentication (grantType=none).
If using “Authorization code” grant flow, select an already configured/enabled Pega authentication service. Enabled custom authentication services do not currently appear in the web embed authentication service dropdown (see picture above) but may be explicitly entered editing the authService attribute (which by default is set to default “pega” authentication service).

Step3. Configuration of the authentication rules

To setup authentication the following rules can be applied (depending on authentication pattern selected)

Definition of the OAuth 2.0 client registration rule

The OAuth 2.0 client registration rule has been automatically generated when the web embed channel has been created with registration type Public. It is not possible to change a saved Public registration to one of type Confidential or vice versa. The default configuration for Single Page Applications is a Public registration. It is possible to edit the registration to adjust the token validity intervals or to enable custom bearer as an additional grant flow (in which case you must also configure a custom bearer activity).

Depending on the type of authentication grant type, you might want to change one of the following configurations.

Being registration type Public it is recommended to configure Proof Key for Code Exchange (PKCE) to prevents malicious attacks.
Use Set refresh token expiry from IDP session expiry to set refresh token when IdP session expires (available only if using authorization code grant)
Configure the authorization grant type that can be authorization code or custom bearer.
Configure the expiration settings of the token and authorization code. If set by the IdP you can get the refresh expiry token in response on the /token endpoint.
Configure the Operator’s user claims to be mapped from the IdP authentication response as output to the /userinfo endpoint. If /userinfo is not invoked the user information can be obtained from the id_token HTTP field returned by the /token endpoint, in particular the {sub} attribute is used to identify the user.

Note: By default an OOTB JSON web token profile pyDefaultUserInfoMapping is selected. If you need to change or add other claims, you can extend pyDefaultUserInfoMapping or create a new custom JSON web token.

Configuration of the Authentication Service

The configuration of the Authentication Service changes respect to the authentication pattern used. See Creating an authentication service how to configure authentication services.

Step 4. Configuration of the theme

The web embed styles that you reference with theme attribute are named Design Tokens (see Design.pega.com/theme for more details). They are styling properties that you configure in App Studio through the Theme landing page if you do basic styling. Switch to Dev Studio to do more advanced styling and analyze the JSON representation in class Rule-UI-Theme. Copy in theme attribute the components or base properties that you need for styling that will render the web embed inside the customer web site. Copying the properties in the theme attribute override the values of the styling properties defined in the default App Studio theme. With the new themeID attribute (from Pega Infinity 24.2) it is possible to switch between the themes defined in App Studio, without copying the JSON schema into the web embed theme attribute.

The following use cases show the different approaches customers have taken to style the web embed.

Manage the web embed theme in the customer web site: theme attribute is used to style the web embed. Web developers, that do not have Pega skills, maintain and evolve web embed theme in the web page.
Manage web embed theme in Pega App Studio (Limited Theming) or in Pega Dev Studio (Advanced Theming): the customer edits the theme in Pega App Studio or does more advanced theming in Pega Dev Studio modifying the JSON schema.

The first approach is not recommended because is completely under customer responsibility, does not guarantee backward compatibility as you might change or add properties for Design Tokens not documented or not supported in future releases (for example if you modify Components properties – see disclaimer in Design.pega.com/theme).

The second, that manage themes in Pega, is the recommended approach with alternatives described below. See Best practices section for more details.

Limited Theming (recommended): web embed styling option is managed directly from Pega App Studio that follows the Low code approach (suitable for Citizen developers).
Advanced Theming: to personalize further the customer branding the web embed style is modified in the JSON schema in Pega Dev Studio.

Best practices

Authentication best practices

The recommended approach is the authentication code grant flow as it is easy to implement and rely on the external IdP.
Perform the validation of the information coming from the HTTP request like Security Token, and other HTTP headers, for example Authentication Header (set in authHeader attribute of web embed). This is especially true with custom bearer and custom authentication grant types.
Configure the CORS settings for OAuth 2 Rest Service API: x-constellation-app, Access-Control=Allow-Origin
Testing: Thoroughly test your silent authentication implementation to ensure it works as expected in different scenarios.
Monitoring: Monitor token usage and expiration to identify potential security issues

Web embed styling best practices

List of best practices for themes managed in Pega.

Styling via Themes: is the recommended approach where the theme is managed directly in Pega App Studio. The level of customization is limited by the theme authoring options available in Pega App Studio in the Theme landing page.
- Is Low code and is suitable for Citizen developers.
- Depending on the web embed attribute used you can manage themes in one location (Pega - using themeID) or multiple locations (web page and Pega - using theme)
Advanced Styling (Use with Caution): This is the least recommended option where you can edit the JSON schema directly in Pega Dev Studio.
- It involves entering a complex theme object directly in the web embed code (if you use the theme attribute)
- Not ideal for low-code development: It requires manual coding and knowledge of the Design tokens.
- Backward compatibility issues: Pega doesn't guarantee continued support for new Design tokens added to the JSON schema, but only the ones defined in Design.pega.com/theme. They might break after upgrades.
- Limited documentation: Only a subset of tokens is documented. Manual adjustments can lead to unexpected behavior.
Styling with CSS in target portal:
- Is not recommended as it can cause issues after platform upgrade
If you have complex styling requirements:
- It is important to note that Web Embed use Constellation Design system
- If you have strict branding requirements, consider using the SDK instead of the Web embed. SDKs offer more flexibility for custom branding.

Points to consider

Authentication considerations:

Web embed inherits all the authentication patterns defined in your application.
During authorization code flow that requires redirects in IFrames, when the /authorize endpoint response (containing the authorization code) comes back to the client, check the following configurations:
- Existing Pega CSP settings that does not permit loading content in IFrames to prevent clickjacking (as CSP can have the X-Frame-Option response header with value Same Origin or None).
- The browser does not block popups.
- Blockage by Third-party cookies.As they can block the authorization code redirects. Pega RULES cookie stores the authenticated session and is returned in the session_id HTTP header when the /authorize endpoint is invoked. As of Pega Platform release 24.2, 24.1.1, and 23.1.3, web embed no longer uses the Pega-RULES cookie to authenticate.
- Use of hidden IFrames or silent authentication for authenticated users help IdP not show challenge screens.
- Mitigates the stalled redirect configuring the timeout when silent authentication terminates (as the authentication code can come after several redirects). Use silentTimeout attribute in web embed to wait for the silent authentication to complete. After that, the elapsed time will show a popup window or an IFrame. iframeLoginUI (true/false) governs whether to just make the iFrame visible after the silentTimeout interval.

Definition of the theme and themeID attributes to be used for styling the web embed.

Use theme attribute (for Pega Infinity 24.1 and below): Copy the JSON schema (or part of it) in the theme attribute.
- Duplicate management: the theme is maintained in two places (the web embed and in Pega).
Use themeID (for Pega Infinity 24.2 and above): eliminates the need to copy a complex theme JSON schema in the theme as it references the theme system rule name
- Centralized theme management: You can maintain the theme in a single location within the App Studio.
- Multiple themes support: If you need a more specific theme, create it in the App Studio and reference it in the web embed using its themeID. Some values might be ('pzCosmosDefault', 'pzDark', 'pzAries', 'pzAriesDark', etc.).
When theme and themeID are defined together themeID takes precedence over theme (from Pega Infinity v.24.2).