Implementing web embed interfaces

The web embed can be built by using either:

1. the Create a case action, or
2. the Display a page action.

Option 1: Use the Create a case action (Recommended)

The Create a case action provides all the necessary case management features, including pre-processing, post-processing, and validation, which are all available in the case configuration. Additionally, data can be persisted across multiple data objects with transaction consistency.

Option 2: Use the Display page action

Display page actions present information only. Data collected for vendors or business partners spans multiple data objects, such as address and contact details. The default DX APIs allow data entry only for top-level data objects. The default landing page layout displays multiple records in a table, which can expose other users’ registration details and create a data security risk. Business partner registrations require approval from an executive manager.

To create a case for web embed, you first download the MDCSample.zip file from the Rule-File-Binary, as shown in the following figure:

Extract MDCSample.zip to the opt/tomcat/webapps directory of VM system, and then launch the Pega WebEmbed with <cite>http://<host>:<port>/MDCSample/</cite>. 

The HTML files in the unzipped MDCSample directory can be opened directly. The index.html file is opened first when accessed by a web server such as Tomcat. You can also click BusinessPartner.html and TruckVendor.html directly.

You use the WebEmbed Channel interface configuration in Dev Studio or App Studio to generate the WebEmbed code for Partner and Vendor Enrolment Case Types. Embed the generated code in the BusinessPartner.html and TruckVendor.html files. Business Partner Registration launches the Business Partner registration case. Truck Vendor Registration launches the Truck Vendor Registration case. The cases can be launched by clicking MENU in the upper-right corner of the workspace.

Web embed authentication

Authentication ensures that only users and systems with a verified identity can use the WebEmbed, and that all permitted manipulations of the data occur under the current user identity.

In earlier versions of Pega Platform, for mashups the Anonymous Authentication Service (AAS) was used to establish authentication. However, this is not supported in Constellation-based web embeds.

Configuring authentication for web embeds

For Web Embeds there are three types of Authentication mechanisms available:  

1. Authorization code 

When using the Authorization code grant flow, OAuth is utilized, and the Alias of a Custom Authentication Service must be specified. In this scenario, the OAuth authorization code grant flow still occurs, but custom activity governs which operator is eventually mapped to. The custom activity code needs to have logic to dynamically create external operators. Note that when generating web embed channels, such custom authentication services do not appear in the drop-down menu. The custom authentication service rule should include an activity that takes inputs to the request, such as cookies, and maps them to a specific dynamic operator, or rejects the request. The activity should interact with Pega OAuth 2.0 grant flow or interact with external identity access providers to authenticate the user. 

2. Custom bearer  

Uses OAuth and the new Custom Bearer public grant flow, which also uses custom activity logic to determine the operator (so that there are no redirects). 

3. None (Custom) 

Does not use an OAuth grant flow, but instead specifies the explicit authHeader to use (grantType="none"). 

Authentication of the WebEmbed is handled using OAuth2.0. For more information, see Authentication in web embed.

The steps for custom bearer configuration are as follows:

Step 1: Create the dynamic system settings (DSS)

Once the grant type is configured, create a DSS named CustomAuthForPegaEmbed in the Pega-Engine Ruleset and enter True in the Value field. This enables custom bearer authentication for the web embed.

Step 2: Configure authentication on the Web embed

The Constellation web embed only supports OAuth 2.0. To configure authentication on the web embed, in App Studio, click Channels > Web Embed to configure a new web embed, or click Current Channel Interfaces to view existing web embeds.

When the web embed configuration opens, the Grant Type drop-down list is displayed. Because there is no identity provider system in place, we use the custom bearer option in the Grant Type.

After clicking Generate Web Embed Code, the code includes a ClientID field that is unique to each web embed.

Step 3: Update the Client to accept the Custom bearer

After saving the web embed configuration, an OAuth client registration is generated. Switch to Dev Studio and open the client registration for the web embed from the Records Explorer. When the client registration Rule opens, under Supported Grant Type, ensure that the Custom Bearer checkbox is selected. 

Step 4: Update the client registration with utility to identify the operator

After selecting the Custom Bearer checkbox, an activity needs to be created to set the operator details. Based on the client ID, a specific operator must be mapped. The client ID can be mapped from the postBodyContent parameter. Once the client ID is parsed from the parameter, a decision table can be used to fetch the operator profile. The operator instance must be copied to the pyOperPage page, which is then passed as a parameter and processed by the authentication engine. See the pyPegaOAuthAccessTokenAuthenticationActivity activity for more information.

Step 5: Update the oAuth2.0 service package to point to the application-specific access group

By default, the OAuth Service package points to the Pega Platform application. The service access group must be updated to point to our application. Access to the application is controlled through the access group and the AROs.