For some strategic considerations on whether you want to use this component at all as well as a step by step guide with gifs, please refer to this medium article.
What is included in this forge component?
Getting it all set up:What follows is the quick set-up guide for your first widget. For a more detailed set of instructions for more custom or specific implementations scroll down further.
Building a Widget with this component is relatively simple.
2. Create your screen and start building the widget just like you normally would.
3. Your use case might require custom events. If you want to capture custom events open the “ListenerEvent” action, and include an if-statement that checks if the message that comes in is related to your event.
4. Publish
5. Share the URL of your widget with the portal team
So what is the portal team supposed to do?
On the portal side you need to take the following steps to embed the widget:
function myListener(event) {if(event.data.Event === ‘Navigate’){history.pushState(null, ‘’, ‘Screen3?OS=’ + event.data.Content);}}window.Apps = new OSApps(myListener);window.Apps.initApp(‘div.OS’, ‘widgetid’, “https://”+ $parameters.environmentDomain +”/WidgetAccelerator_Demo/AnonymousScreen?OS=”+ $parameters.ExtraURL,{hideBorder: true, autoResize: true})
function myListener(event) {
if(event.data.Event === ‘Navigate’){history.pushState(null, ‘’, ‘Screen3?OS=’ + event.data.Content);}}window.Apps = new OSApps(myListener);window.Apps.initApp(‘div.OS’, ‘widgetid’, “https://”+ $parameters.environmentDomain +”/WidgetAccelerator_Demo/AnonymousScreen?OS=”+ $parameters.ExtraURL,
{hideBorder: true, autoResize: true})
How to set it up, the more detailed guide:
This Forge component provides you with the assets (and example implementation) of the three most important elements for a widget strategy:
Everything you need to make the OutSystems Widgets
Everything you need to embed the Widgets in your portal
Everything you need to enable underwater authentication towards an IDP
How to build your OutSystems widget:
Section 1: security headers.
Your OutSystems environment might have security headers that prevent other technologies from embedding your pages. In order to avoid running into issues, please check your security settings in lifetime, both the headers environment as a whole and for the app you want to build out in specific.
Make sure that, if the content security policy is turned on, the url for your OutSystems environment is added to the Frame-ancestors property.
You can use a * in your url, for example *-myCompany.outsystemscloud.com, to allow all of your OS environments instead of just the dev, for example. A * can be used by itself to allow any external site to include your screens. This opens access to sources you don’t control as well, so use this option with caution.
You might also need to allow cross origin policies. If so, you need to install Factory Configuration to add the required allow control origin configuration, as described here.
Section 2: Develop the widget
On the Widget side you will need the following preparations to facilitate a good interaction with the Portal:
Add the event listener, you can do this by using the LayoutBlank from the component, or by starting based on the included ExposeWidget screen template.The event listener listens to events inside the Widget and sends them to the portal.The event listener also listens to events sent by the portal and responds to some of them automatically (like resizing).
It is possible to agree on custom events with the portal owner, in which case you can capture incoming events from the portal in the event handler you have to make when you add the layout. (Or in the ListenerEvent, in the screen template.)
If you want to send a custom event to the portal you can use the SendMessage action, which takes two inputs: Event and Content.Agree together with the portal owner what the name of your Event is, and use this in the Event input.The Content input allows you to share for example variable information. It is important to realize that this method shares the information through the client-side now, and this can be tempered with. So this should be treated in the same way that client-side actions and variables are treated in Reactive.If you need to share information in a safe way, I recommend sending an event without content that triggers the portal to call on a secure API in the backend, instead.
How to include the Widget inside the portal
Section 1: security headers
Your portal might have security headers that prevent other technologies from embedding your pages. To prevent running into issues please check your content security policies, make sure that the Child-src includes the domain of your OutSystems environment that hosts the widget.
Section 2: Embedding the widget in the portal
Create an empty div, with a style class. You are going to use this style class to identify the div, it does not need any actual styling assigned to it. In our example we’ll give it the styling class ‘OS’.
Include the OSApps script. (Use the OSapps.js file included in the component.)
Create a javascript action that runs onReady, which runs something along the lines the following javascript snippet:function myListener(event) {
if(event.data.Event === 'Navigate'){history.pushState(null, '', 'Screen3?OS=' + event.data.Content); }
}
window.Apps = new OSApps(myListener);
window.Apps.initApp('div.OS', 'widgetid', "https://"+ $parameters.environmentDomain +"/WidgetAccelerator_Demo/AnonymousScreen?OS="+ $parameters.ExtraURL,
{hideBorder: true, autoResize: true});
Optional: if you want to allow the widget to manipulate the URL, you might need to add some additional customization. In this case we are adding items to the input parameter, so you need to define an input parameter for us to manipulate with the name “OS”
FAQ
How to share the authentication token when the same site cookies cannot be turned off?
We can also share information explicitly by sending a PostMessage, this is how we can share the token explicitly to the widget after log-in.
If the portal already has a signed in session, it is also possible to add an input parameter on the widget screen in OS and initiate the screen with the authentication token as an input parameter. This will in general provide a better performance and would be recommended if the widget is only available in already authenticated contexts.
How to enable navigating back to a certain page in a widget/ with a certain pre-filled parameter?
In some cases (for example when providing an user with a wizard through a widget) one might want to allow the user to navigate to different screens or reflect some entered information in the url.The main use case for this would be to allow the user to return to a specific screen or pre-filled information through navigating to the url. An example of this has been implemented on the component.The implementation requires the following elements:
All screens that are navigated to as a widget need to also be implemented as a widget
The widget screen that is loaded as default will need to have:
An input parameter through which the input parameters are passed to the widget
An onInitialize action that redirects to the right screen based on the input parameter.(In situations where there are many screens to redirect to, it is better for performance to create a separate empty widget to use as the entry widget, which handles the redirection.)
The portal will need to pass the information received from the URL to the widget
Which specific UI exposure use cases does this component aim to tackle?
Widget strategy:If you are looking for a way to embed OutSystems into your portals/websites, this component helps you cover two scenarios:
Scenario 1: A full-page OS widget on a portal page;
Scenario 2: Multiple (OS) widgets on a page;
Underlying non-functional requirements:
Responsiveness of the widget (dynamic width & height, no scroll bars, resizing, allowing other items to display over it when required, etc.,)
Sharing context and information, for example when
navigating inside the widget updating URL on browser
logging in on the portal sharing the session context so that the child can independently verify authentication
Possibility for analytics and tracing IAM and SSO;
Technical implementation:
There are two technical components:
OutSystems widget
The portal in which the widget is embedded
The interaction between these elements is extremely important to enable the Non Functional Requirements described above. JavaScript event listeners will forward events in the widget to the host (and vice versa) and pass any input parameters necessary back and forth. In logged-in scenario’s both portal and widget will identify the user with the SSO, the widget will be authenticated in the background through utilizing the authentication token that exists in the secure cookie in the browser.
Please note that both scenarios can be implemented with this approach. However, for scenario 2 the implementation might require the portal to act as a coordinator across the various widgets, meaning that there would be more events (and information) passed between portal and widget. This can be a significantly more complicated scenario, as the portal would have to distribute available screen real-estate, determine which widget is/isn’t allowed to adjust URLs etc. The multi-widget scenario should therefore not be taken lightly.
A convenient and consistent widget implementation requires standardized reusable components, the basis for which are being shared in this forge component.
Known limitations:
Chrome incognito mode issuesThe widgets do not work on Chrome in incognito mode if 3rd party cookies are blocked. Outsystems apps require access to the LocalStorage and they will not render if they are blocked.
Users can enable the widgets by changing the settings in incognito mode. By default the incognito windows open with this setting active like below:
If the user chooses to allow the third party cookies, they will be able to utilize the widgets. Alternatively, if they use browsers like Firefox or Edge the third party-cookies will not be blocked and the problem will be avoided.
postMessage targetOrigin
This component uses postMessage where the targetOrigin is set to “*” . This might not be in line with the security policies that you have at your company, if so it is possible to change these to more specific targetOrigins.
For some strategic considerations on whether you want to use this component at all as well as a step by step guide with gifs, please refer to: my medium article.
To build a Wiget please utilize the new screentemplate (widgettoexpose), which should give you a blank slate upon which to build your template.
The reason to utilize this template rather than a blank screen is that it comes equipped with all the javascript necessary to expose the screen (such as the event handling).
Please review the documentation under the first version of this component for a complete understanding of how to implement this component.
The changes made in this version mostly concern quality, but it is also important to note that I've split out the demo module from the component.
See the documentation under 0.1.1 for how to use this component. For IDP some additional documentation:
If you want to configure external authentication you need to set the sitepropery "hasExternalAuthentication" to True
Also set the correct OktaClientId, OktaURL and RedirectUrl
1.OktaClientID is a string that can be found in your application configuration in Okta
2.OktaURL looks like oktadomain + "/oauth2/v1/authorize?client_id="
3.And redirecturl should look like OutSystems domain +" /WidgetAccelerator_Demo"
Additionally, make sure to correctly configure your Okta application, here we are using a Single Page Application, but you can also use the SAML option
1. Add the url of your parent app to the redirect uris.
2. Under Security -> API -> Trusted Origins (in the left menu) add at least the child's url there.
How to set it up:
Include the OSApps script. (Download it here.)
How to enable shared third party authentication between portal and widget
Section 0: setting up the demo version with Okta
If you’d like to configure the demo application to give you a working identification example using Okta, set up an OIDC Single-Page application on Okta.
In the OKTA OIDC application make sure to add the redirect url of the demo application in your parent/portal application as a redirect URI.Then navigate to Security -> API -> Trusted Origins (in the left menu) and add at least the child's url there. (with CORS and Redirect).On the demo application:
Set the site property RedirectUrl to <the URL of your environment>"/WidgetAccelerator_Demo".
Set the site property OktaUrl to <the url of your Okta environment>.
Set the site property OktaClientId to <the client id of your OKTA OIDC application>.
For the third party authentication we need to connect both the portal and the Widget to the third party authentication. So the first thing to check is if we are not blocking that in our Content Security Policy, by checking whether the Connect-src properties on both the widget and portal allows loading resources from your idp provider.
The second thing to worry about is whether the widget will be allowed to access and utilize the secure cookies stored by the Portal while interacting with the idp. To do this we need to make sure that the widget side does not require ‘same site cookies’, by changing the SameSite property in lifetime to ‘none’. (If set to ‘browser-default’, certain browsers will not share the cookies to any app from a different origin.)
If it is not possible to turn off the same site cookies, for example because it is a required feature of your security policy, you’ll need to share the token explicitly using PostMessage. (See FAQ)
Section 2:Setting up the authentication mechanism on portal side
On the portal side set up the authentication mechanism using the third party authentication token. . You can achieve this in many different ways, and all are fine, as long as you manage to achieve the following two things:
You’ve authenticated against the third party technology that is shared with the widget.
You’ve saved the authentication token in a secure cookie in the browser. (If you encrypt the token here, make sure you implement the decryption of the token in the widget.)
The component contains an example of this implementation in OutSystems authenticating against Okta. Clearly the real version will need to be built on the actual portal technology with the authentication mechanism of your choice, the included example implementation is just an illustration. If you’d like the example implementation, this is how it works:
The Login page calls Okta with the username and password to get an authentication token, it takes the response and stores it in the client variable “Token”.
Using the token, the client id of the Okta authentication application and the urls for both the okta application and the portal, we can now dynamically generate the redirect URL which the login will redirect to. This redirect URL is an Okta url for the Okta application we created for the authentication, and it includes in the URL the URL to which to send the end-user back in the portal.
After we get redirected to the portal again, the OnApplicationReady event gets triggered, which checks if there is an active session, and if so logs the user in the portal itself as well.
Section 3:Setting up the authentication mechanism on Widget side
Your widget will not automatically know that there is an authenticated session, so it is important for us to set up a mechanism to help the widget figure that out.
In your common UI flow you will find an OnException handler.
We need to include the logic to check, in case of a ‘SecurityException’ , whether we already have a session active with the third party identity provider. If we have a session, we also need to get the username from the idp. In the component you will find the checkUserSession javascript in the OnApplicationReady, which does this for Okta. You might need to adjust the logic for your idp of choice.
Once we have verified the active session and gotten the information of the user, we need to log the user in on the OutSystems widget. The component provides the HandleLogin action to do this for you. It also grants an example user Role to show how to do that.
Now you simply need to ensure that you will trigger the SecurityException in any context where a person needs to be logged in. The most straightforward approach is just to remove the ‘anonymous’ toggle from the page on which your Widget resides.