By default, Constellation SDKs use the OAuth 2.0 authentication type with the Public authorization code grant flow. This authentication type supports both modes of application implementations, embedded application and portal application.

You might need to configure authentication based on the implementation and your own platform’s configuration. This article discusses how authentication and authorization is implemented in Constellation SDKs. For more information on how authentication and authorization is implemented in the Pega Platform, see:

• For Pega Infinity^TM 8.7: Authentication and Authorization.
• For Pega Infinity^TM 8.8: Authentication and Authorization.

Authentication and authorization based on application mode

The Pega application experience is either implemented to consume the entire page or a portion of the page. This impacts the authorization and authentication experience. 

Portal mode

In Portal applications, if the full page relies on Pega authentication, then the initial authorization code redirects might occur within the main window and precede the display of the main content. After the authorization, the handoff (redirect URI) is back to the primary homepage URL to display the desired portal. 

Embedded mode

If the experience is an embedding experience, the SDK expects that some other interactions on the screen may have preceded the display of the Pega embedding-specific case experience. Hence, any Authorization Code redirects should not occur on the main window (as this would cause any prior state within the window to be lost), but rather must occur within a separate external (popup) window or an embedded iframe window. At the completion of the redirects the handoff is to a page that takes the authorization code from location.href and passes it back to the main parent window. Once the main window receives the authorization code, it either closes the popup window it had previously opened or removes the iframe window it had previously created, and then invokes the token endpoint to exchange the received authorization code for an access_token. You can use popups or iframes based on your application. Their usage within an embedded experience is described in sections that follow.

Hence, the SDK sample application has a pair of redirect URIs specified within the included OAuth 2.0 Client Registration record: one to redisplay the desired portal homepage (for portal scenarios) and the other to a page with the necessary JS code to communicate the authorization code to the main window (for embedding scenarios). The Web Embed channels create OAuth 2.0 configuration records with only one redirect URI, the one needed for embeddings. 

Using popups

Embedded applications typically use popup windows to facilitate authentication. This typically runs into the following issues:

• The browser's popup blocker preventing the authentication popup from opening.
• Popup windows opening and closing without requiring any user input. Happens when the silent authentication does not complete within a hidden iframe and a visible window needs to be opened to complete the authorization redirects.
• The login window might drift behind the main application window.

To manage popup blockers, the user then needs to adjust browser settings to permit popups from the requesting site and then repeat the operation to get the window to open. 

In the scenario where the identity provider site does not need to display any visible authentication challenge as it is able to detect that the user has an existing authentication session by some other means, the code is immediately returned and the popup closes. This can confuse users as they will experience a quickly opening and closing browser window and might not understand why this just happened. 

Using iframes

Iframes provide an alternate means of invoking the authorize endpoint and receiving an authorization code. In some identity provider configurations this works very well provides a much smooth experience of seamlessly being able to leverage an already established single sign-on without the issues encountered with popup windows. 

In some configurations, iframes run into key Cross Origin related issues and restrictions. HTTP provides websites or pages with the ability to prevent themselves from loading within an iframe. This can be done by returning a X-Frame-Options response header, with the value DENY or SAMEORIGIN. DENY prevents the page from loading within any iframe, and SAMEORIGIN restricts the page from loading when the top-level page is also from the same origin. This restriction can also be implemented via the Content-Security-Policy response header, via the frame-ancestors policy setting. 

Response headers are used to protect a website from a security vulnerability known as clickjacking. Constellation SDKs protect against clickjacking by using the sandbox attribute for the iframe to prevent content from taking over the main window. However, this results in the redirects stalling out. 

Even when an Identity Provider’s login page offers clickjacking protection, the redirect responses to return the auth code in scenarios where the user is already authenticated with the Identity provider do not run into the same headers. Typically, such headers are only returned on 200 responses which include the HTML markup to display some challenge user experience. This makes the use of a hidden iframe an improved experience over the flashing window in already authenticated SSO scenarios. We refer to the technique of using such a hidden iframe as silent authentication. 

Using custom authentication

Bootstrap the Constellation JS Engine with either full Pega OAuth 2.0 information or with just a specific authorization header to use for Constellation SDKs. Using just a specific authorization header is referred to as Custom Authentication and in this path the specified authorization headers are passed during API invocations and a customReauth event is generated if a 401 HTTP response is received. 

Pega OAuth 2.0 uses access_token or refresh_token pairs with full information about the OAuth 2.0 client registration document and endpoints. When the full Pega OAuth 2.0 information is provided, the engine leverages any passed-in refresh token to seamlessly acquire new access tokens and notifies the Constellation JS Engine consumer via an event with the info about the updated token information. 

Pega Embed provides an authHeader attribute to facilitate setting such a “custom” authentication header (in which case NONE of the OAuth related attributes, including clientId, are specified), and the Constellation SDKs support an sdkSetAuthHeader API to pass in an explicit authorization header. This authHeaderattribute can also be used when a Pega access_token has been acquired from a server to server “Confidential” OAuth 2.0 registration and some such grant flow such as “JWT bearer”, which would facilitate swapping an external IdP token for a Pega access_token. 

If the custom header is a bearer token acquired from a server-to-server confidential OAuth 2.0 registration, then the application service package uses the OAuth 2.0 authentication type setting. However, if the header being utilized is Basic authentication, or some other custom scheme, or a JWT token acquired directly from an external identity provider, the Application service package changes to Basic or Custom. Changing the application service package impacts Constellation web access to the application and might not function properly. One means to allow, or if the only way to get Custom to work without breaking Constellation app is to support making a copy of the application service package and naming it something different (like applicationcopy). However, there is no mechanism currently to have the Constellation JS Engine utilize a renamed service package and endpoint.