To best explain what to do here, we will use a Microsoft Azure Active Directory as authentication provider. If you need to integrate with another provider, it should work similar.

Setup SAML Authentication

Summary:

• Register app (WEM Portal) in the Identity Provider (like MS Azure AD);

• Get settings from Identity Provider;

• Setup registration in WEM following 4-step wizard;

  • Name of Authentication Provider as it will be used in WEM flows/nodes

  • Identity Provider settings;

  • WEM Application settings (Service Provider settings);

  • Map fields;

Register App with Identity Provider

First step is to set up an Application Registration or Business Application in Azure Active Directory (or your Identity Provider). Microsoft has changed the routes and ways to set up App Registrations (or Business Apps) in the past, so our guide may be slightly different. Point is, there needs to be an App Registration (Enterprise Application it is called now in Entra ID) in the Identity Provider holding the details of your WEM Application, and link the users/groups to this application that are allowed to login there. The App Registration will get a specific EntityID in a form of https:// or urn:// (and then a globally unique value that could be like a hostname and/or could contain a guid).

Identity Provider Settings in WEM

The easiest and safest way to get these settings right, is to start with metadata from the Identity Provider. Most providers will have the option to display or export the Metadata as xml, containing the necessary information to set up the provider in WEM for the Registered App. WEM can read and import this xml information and convert it into the settings for the Authentication Provider.

The Application Registration in AzureAD provides several links to be used in different places. Most important (or easy to use) would be the Federation Metadata link. Using this link will allow you to import most settings into WEM Modeler, including correct ID's, login urls to AzureAD and certificates.

If there is no metadata link or file to import, the option to configure manually can be selected. Following screenshots will show at least some recognizable fields that you can fill with the information as provided by the Identity Provider in the Application Registration.

The Entity ID in this page, is the Entity ID which identifies the Identity Provider (with MS AzureAD it would contain the Tenant ID).

The NameID Format is important: this defines in which form the Name ID (the subject, the user-identifier) is returned by the Identity Provider. The Identity Provider should properly defined this, or you can see the result in the SAML Response (see Map data below). Start with Unspecified if you are not sure and check the SAMP Response for the correct definition if you can not find it in the information as provided by the Identity Provider.

The Authentication fields should be copied from the Identity Provider settings (unles imported from the Metadata - then this information should not be altered manually).

Security settings: With Microsoft Azure AD, we know they renew certificates often and to support that integration without disruption, WEM provides the feature to "Fetch certificates at runtime". So, if you are also using MS AzureAD, you should really activate this option. If you use another Identity Provider, you should check if it also supports this option.

If the Identity Provider is not MS AzureAD or does not support fetching certificates at runtime, keep the Fetch-at-runtime switch turned off and add the certificates manually and keep them updated if necessary. If setup is done with the Metadata Import, the certificates should have been provided and automatically put here. If not, you should add the certificates as they are provided by the Identity Provider in the Trusted Server folder in the Certificates section. If certificates have to be renewed, the project also needs to be published to get the updated certificates in the Runtime (or - if certificates are managed in the WEM DevOps Dashboard, you should change them there and then there is no need to publish).

WEM Application Settings (as Service Provider)

Following the SAML naming conventions, the application that is using the Identity Provider to authenticate users, is called the Service Provider. Don't let this confuse you - the Identity Provider is the environment where the Identities are managed and the credentials are kept and checked. The "Service Provider" is any application that wants to use the Identity Provider to authenticate users (providing services to end-users).

The most important field here, is the Entity ID - the ID of the application as it will be used in the App Registration in the Identity Provider (using either urn:// or https:// and then some globally unique code or hostname - the Identity Provider will have some guidelines or rules on how to name this App Registration). It may also be something like Relying Party Trust Identifier in the Identity Provider management.

Initially, you should consider to keep these fields as shown in the screenshot: no certificates, no requirement to sign.

In the screenshot, you can see the label "Default". This refers to the Portal in this WEM Project. As you may know, any WEM Project can have multiple portals, with different designs and hostnames. For each WEM Portal you can set up a specific SAML configuration (they will all be visible on the SAML Service Provider settings overlay). Portals may connect to other App Registrations in the Identity Provider (while the Identity Provider is still the same, so the same specific Tenant). This can be useful if you want to allow different sets of users to be able to use/access each Portal. The Identity Provider can set this up as different App Registrations.

Portal Metadata

In the Service Provider settings page you can see the button [Get metadata]. Clicking this button will provide the option to get information (metadata) for each Runtime of the portal. You should NOT use the Preview option (we will remove this in a future update) - as Preview will not be able to work with SAML integration. So only use the Staging and Live options, and if the Identity Provider supports importing service provider metadata, you can choose to download the metadata file.

If the Identity Provider does not support importing Service Provider metadata, you can choose to copy the metadata to clipboard, paste it into a text editor (or mail to send to IP-administrator).

The most important part of this bit, is to provide the URLs for the App Registration for the Location of the Consumer Service. The pasted information will show you something like:

<AssertionConsumerService 
    Location="https://{postal-hostname}/auth/saml/{SAML name}" 
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
    index="1" isDefault="true">

It is the Location Value that you need to share with the Identity Provider admin. WEM Portals will generate URLs (SAML endpoints) in the following form (where the portal hostname and the SAML Name are the variables defined in your project):

https:// {portal-hostname} /auth/saml/ {SAML Name}

This is the information that needs to be entered into the Identity Provider app registration, probably in fields named something like Assertion Consumer, Reply Url, or Relying Party Trust.

A great thing of these Reply Urls (at least in Azure AD) is that you can enter multiple urls so you need only 1 App Registration that can service your Portal(s) for both Staging (test) and Live (production) situations, and multiple portals/hostnames - as long as the situation allows the same set of users for all occurrences of these urls. You should NOT need to create separate App Registrations in any Identity Provider to service each Portal in Staging or Live separately. The systems are smart enough to accept requests from staging and return the authentication result to staging - or based on the hostname another portal or runtime.

Map data

The final step is to map the results from the SAML message to the appropriate fields in your WEM project.

The Response from the Identity Provider via SAML is in XML form, which you can map to a Text Field (so you can see/display the total response in testing). The NameID field is the specific field that identifies the user according to the NameID Format in the Identity Provider Settings.

SAML has a lot of standard "Attributes" - fields in Azure that hold information about user-accounts. The Identity Provider will expose some of those fields, and the WEM SAML Attributes part shows most standard Attributes which you can map to fields in your Project. Again, while setting up the application and testing the connection, use the full Response XML information to check what fields and values are provided by the Identity Provider, so you can find which fields to map.

The Identity Provider can also introduce custom attributes, so WEM provides the option to add these using the New Attribute button so you can map this info to your Project fields. Again - check the Response XML.

After you've finished these steps and clicked [Create], the SAML Authentication settings are available via context menu in the project tree:

Double-clicking the SAML Provider will open the Data Mapping overlay, so if you need to access, check or change the Service Provider settings or the Identity Provider settings at a later stage, use the context menu.

SAML Signing and Security

Now that you've seen all the parts for a SAML Authentication, and understand that there are 2 main players in this situation (Identity Provider and your WEM Project as Service Provider), we can address a more advanced part - regarding the Signing and Security and the correct usage of fields/settings related to this subject.

Service Provider Settings (the WEM Application)

• Encryption Certificate: this setting is provided because it is part of the SAML Standard, but we have not yet seen the need to explicitly set this and use it. So, unless you are absolutely sure that you are required to use a custom Encryption Certificate, you can provide it here - otherwise leave empty. If used, it is a Client Certificate with Private Key of which the public part should be shared with the Identity Provider.

• Signature Certificate: Adding a Signature Certificate here, means that the WEM Application itself will sign the Requests towards the Identity Provider. You will need a Certificate with a Private Key within the Client Certificates collection (if accepted by the Identity Provider, it can be a Self-Signed Certificate that you can quickly create in WEM Modeler). The Public Certificate part of this Client Certificate should then be sent to the Identity Provider so the Identity Provider can verify that the Requests are properly signed by your Application. Because this certificate can not be "fetched at runtime", it is always a manual process - creating the certificate (with an expiration date), linking it to the SAML configuration, providing the Public Certificate to the Identity Provider, who has to install and link the certificate to the proper application configuration, and when this certificate reaches the expiration date, it usually causes the application to fail and will take some time before people realize it is caused by the expired certificate, so yes it is a hassle that should not be taken lightly: if this bit of additional signing is required, make sure the management of the certificate exchange is clearly addressed with reminders and notifications to handle the expiration in time. Also - when this Signature Certificate is used at the Service Provider side, you may need to switch the option at the Identity Provider Settings side - see below, to indicate that the Identity Provider Requires that the request is signed.

• Hash Algorithm: if the Identity Provider explicitly claims that Signatures must be provided with SHA256 hashing, you can set that here - otherwise leave it at the SAML 2.0 standard SHA-1.

• Setting Require that the assertions are signed: This means that WEM only accepts a SAML Response that has a signature from the Identity Provider. The Identity Provider must share the public certificate that you can add to the Trusted Server Certificates OR, and even better, if the Identity Provider supports the fetching of certificates at runtime (like MS Azure AD), you only have to switch the option Fetch Certificates At Runtime to ON and provide the link to the certificate location (to be provided by the Identity Provider). With MS AzureAD it is usually the federation metatada link and an id - but this should be clearly indicated in the Azure AD App Registration pages. This is a standard way to at least secure the application ensuring that the incoming SAML response is indeed from the Identity Provider so you should use this if possible.

Identity Provider Settings

• Requires that the request is signed: This indicates whether the Identity Provider only accepts Requests that are Signed by the application. For this to work, the WEM Application needs to use a Signature Certificate (as described under the Service Provider Settings * Signature certificate). The Public part of the application's signature certificate needs to be shared with the Identity Provider. This option is requires a partly manual process to create and renew the certificate (there is always an expiration date on this kind of certificate) and exchange the public part with the Identity Provider. It is an option that can be used, but do not use this lightly (because of the problems to be expected when expiration dates have passed).

• Fetch certificates at runtime: Microsoft Azure AD changes and renews certificates dynamically so WEM decided to implement the easy option to fetch certificates at runtime and use the certificate information in the Response. Other Identity Providers may or may not support this option, but if you are using Microsoft Azure AD as Identity Provider, you'd best activate this option (if you leave this option deactivated, you may experience login-failures when certificates have been renewed). The fields for the certificates will then be hidden - no longer needed. If you are working with another type of Identity Provider - please check with them if they also support this option (would be very nice and easy for all parties involved). If not, leave this option deactivated and make sure the appropriate Certificates are selected. When the Identity Provider information is loaded/imported using a (Federation) XML (read metadata from URL, XML File or XML Text), the public certificate will be recognized and added to the Trusted Servers certificate collection in your project. If you are going to configure manually, you will need to retrieve the certificates and import them to the Trusted Servers collection yourself, and then select them in this configuration part. Which certificate and for what purpose should be indicated by the Identity Provider.

The Realtime messages functionality is used to allow an application to send messages. That means there is always a sender and a receiver/listener. These are created using Realtime Messages flowchart nodes. A sender sends a messages through a particular message chanel, and the listener listens on a chanel for messages to arrive. And when a message arrives a specific action will be taken. Example: a helpdesk system uses realtime messages to send a message to an escalation chanel when a high priority problem occurs. The listener then takes appropriate action (e.g. send a text message to an escalation officer) when a message arrives.

Almost all the functionality is available through the realtime messaging nodes. However, before you can use the functionality you need to define what a message looks like.

Defining messages

To define a message, go to the webservice and comet tab in the WEM Modeler resource pane.

Open the context menu of the folder Comet messages and select New message to create a new message definition. You have to give the message a Name and optionally a Technical name. Next you add the list(s) and/or fields that should be part of your message. In other words: you can create a model of all the data that you want to be part of your message. You can not create a database list because none of the data is stored in the database: it is only used when a message is sent directly over a connection to all listeners.

When you have defined the data model of the message, you can start sending and receiving messages using the Comet Message node. As part of the flow executing the message process you can assign values to the fields created in the message definition before you trigger the send message comet node, and all active listeners will receive these values - and you can present them or work with them in the On Message Received action (for example, using a Flowchart to show the message in an overlay).

OData (Open Data protocol)

"Open Data Protocol (OData) is an open protocol which allows the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way." The WEM Modeler uses OData to access the database of an external system. And in order to do that, you need to specify where that database resides and what data can be accessed. Once WEM has this information, you can directly access the data from e.g. an interaction node. We call a system that is accessed through Data a Remote data source.

Defining (consuming) a new Remote data source

Setting up a new Remote data source is very simple. Follow these steps:

• Go to the Remote data source node in the Project tree. Click on Add data service.

• Give the service a name, this is the name that WEM will use for this particular data service.

• You can now add a URL, and if needed, fill in the Username and Password for the source.

• Based on these credentials the remote data source gives access to the database, including the specific rights this user has (insert, update, delete rights).

Updating the data service

If the metadata or data model changes the service needs the current information. To update the service itself, click on the update odata service definition button and WEM will update the data service. This can be found by right clicking the service you want to change or opening the context menu with the 3 dots when you have the intended service selected.

Alternatively, manually update the OData source by selecting 'Edit Settings' from the same context menu. This opens a window where you can update the name, service URL, settings for File URL's and batch optimization, the credentials for preview staging and live and service root URL's.

Using the remote data source

Once the remote data source is specified, it can be accessed via the WEM Modeler. Everywhere in WEM where you can access data, you can access this remote data source. E.g. if you are working an interaction node, the list(s) that represent the remote data can be found in the webservice tab of the resource pane under the specified datasource. Or when you create an expression using the expression editor, you can access the same remote data source lists and fields.

Exposing your WEM application using OData

It is possible to expose your WEM application's data using the OData protocol. When you do this, external systems can access the data of your application using OData. Exposing OData is very straightforward:

1. Create user credentials that will be used by external systems to access the data of your application. The credentials can be found in the settings tab under the security settings on the right. Here you you can manage and add access to the OData lists and user access settings.

2. After you have created the user credentials you specify which list(s) in your data model are exposed to that user (and therefore to the external system);

3. Here you can also specify for each list which operations are available to that user (and therefore to the external system).

Once the steps above have been executed, your application is accessible via OData. Note: exposing your application via OData is always done per portal. In other words, you need to specify access per portal.

The next sections describe each step in more detail.

Manage OData Users

Managing OData users is done via the security settings found on the project setting page. When you go to the project settings and click on OData logins, you will see the following window open:

Here you can manage, add and see all active OData logins and control their access level. In the first column you can see the username used to log in to the service and the Portal column is where you specify either one or all portal used by the service for each user.

Management of the data list that is available for each user is managed by clicking the blue access link in the third column. This will open a new window called access control for 'username', here you select the access level and which specific lists are available through Odata. First you choose between giving full access and a restricted access, with the restricted setting allowing you to choose specific lists like the image below. More about this at the end.

This is the first page to add a new OData login user to your project. Here you set up the name/username, password and the portal(s) you want to provide access to. When this is filled in correctly you can go to the next page for the access level settings. This is the same screen as managing existing users access level. When you are done you save the user with the create button.

Deleting users can be done from the OData logins screen from earlier. In this screen the context menu for each user can be opened with the three dots on the right of the window. From here you can also change the access control, change usernames, change passwords and delete the users and its access to the data.

Specifying Access Control rules

Once an OData user has been created, this user can be given access to your application's data. To do this, select the user you want to manage and select Access control rules. This will bring up the following screen:

There are two main options:

1. 1.Allow full access to all data - this is the default selection.This option means that the user can access all lists of your application and has the right to insert data, update data or delete data for all the lists in your application. In other words, the user has full control over your application's data;

2. 2.Specify access rules This option makes it possible to have very granular control over providing access to your application's data. When this option is selected, you can specify which lists the user has access to and which actions can be performed on this list.

When the first option is selected the individual lists will be greyed out, but when the restricted access is selected you can start allowing to read on specific lists. The other options are available when the read is already selected, users will always need to be able to read the lists before they can get additional rights. Besides being able to read the data in the list you also have the following options:

• Allow insert - the user (external system) can insert new rows to the selected list;

• Allow update - the user (external system) can update data in the selected list;

• Allow delete - the user (external system) can delete rows in the selected list.

By selecting one or more options, it is possible to control exactly what the user (and therefor the external system) can do with the selected list.

You can repeat the steps above to select all lists of your application that need to be exposed.

How to setup an App Registration for SAML

1. Go to https://entra.microsoft.com/ (you need to have admin permissions).

2. In the sidebar menu, find the Applications and within that option, go to Enterprise Applications.

3. Click on New Application.

4. Click on Create your own application.

5. Add a name, select "Integrate any other application you don't find in the gallery (Non-gallery)" and click Create.

6. Wait until the app is created.

Enterprise Application Overview

Assign users

In the Enterprise Application, you assign users and groups that are allowed to login using this specific Application (SSO in your WEM portal). Depending on your Active Directory / Entra ID Plan, you can only use specific users (the basic plans). To assign groups, you need the more expensive plans (and users with appropriate licenses). The Business Standard license plan allows you to add users only.

So, select users (and groups if possible) and click the Assign button at the bottom, so when you return to the overview of Users and Groups, you see the users and groups.

Set up Single Sign On with SAML

Back on the overview, click 2. Set up Single Sign On and select the SAML option.

1. Basic SAML Configuration

At 1. Basic Saml Configuration, click edit. Here you need to enter the Identifier (Entity ID) to identify your application to Entra ID, and this will also be part of the settings in WEM. Microsoft Entra ID supports the urn:// structure as in the example, and we offten use a guid with a domain - for example, you can use the Application ID from the overview and add your domain:

urn://{Application-Id}.wem.io

The second required item is the Reply URL. This will hold the URL(s) from your WEM portal that will receive the authentication token.

To be able to correctly fill this Reply URL, you should already have created the SAML provider element in your WEM Project - or you can enter the values here now and make sure that you use the same name in WEM - the Reply Url for any WEM portal is in the following format:

https://{portal-hostname}/auth/saml/{saml-name you set in WEM}

You should already have a staging hostname and perhaps a live hostname. You can enter both in the same App Registration here, so both staging and live portals use the same App Registration and thus cater for the same set of users/groups. If you want to have different sets of users/groups for staging and for live, you must create 2 different App Registrations!

Hit the save button and close the panel.

2. Attributes and Claims

In this part, Attributes and Claims, you provide the fields that hold the values for a specific Identity that will be provided to your WEM application. By default you have the Unique User Identifier (usually the user principal name), email address and name-attributes. Here you can add other fields as well or change the existing claims to use other fields from the Identity.

3. SAML Certificates

This is where you make the settings for the Token Signing and Verification Certificates. You do not need to change anything here.

The default setting for Verification is not required - if this is changed, you also need to change the corresponding setting in your WEM SAML settings.

The important part in this section, is the App Federation Metadata Url. It looks something like https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml?appid={app-id}

You should copy this url, because with this url you can quickly set up the SAML element in your WEM Project, AND this url is required for the option to "Fetch certificates at Runtime" - which is a necessary option when using Microsoft Entra ID or Azure AD!

4. Setup {your app SSO}

In this part, you will see the Login Url, Microsoft Entra Identifier and Logout Url that you can use in your SAML Element settings - BUT, if you use the App Federation Metadata Url to setup your SAML element, that will automatically set these items correctly.

This should provide all you need to know to set up the SAML within Microsoft Entry ID, or at least provide insight into the necessary actions and settings.

SAML 2.0 and OAuth 2.0

The blog from StrongDM provides quite some clear information about the differences and when to use SAML or OAuth.

But, in short: SAML is a more secure way for user identification and authentication (login, single sign-on) and could well be used in WEM to let users login to your WEM application from your existing Identity Management environment (like Microsoft Azure AD or Entra ID).

And OAuth can very well be used to let users access their resources (or your company's shared resources) and external apps from within your WEM Application, using the OAuth authorization mechanism. Example: use Microsoft Graph via OAuth to access files and resources in a secure way.

Typically, SAML is for Authentication (who are you, what is your identity) and OAuth is for Authorization (what are you allowed to do or see, what are your permissions and privileges). Both can be used side-by-side in WEM. SAML is a bit like a house key. It grants you access to the facility. OAuth is a bit like the rules of the house that dictate what the person can and can't do once inside.

User Authentication

An application may require users to log onto the system (authentication). That means the application needs some kind of user management and users need to authenticate themselves and need to be authorized to access the application. To do this you have several options:

• Create all user management functionality as part of your application (there is a great example available in My WEM that you can use as a base - look for Basic Authentication project in Quick Starters or the App Store);

• Use an external authentication provider. In this case the WEM application relies on an external authentication provider to authenticate users. You may still need to link them to an application-specific list of users for additional details or specific in-app authorizations.

Using an external authentication provider means that users usually need to log onto their company network only once and don’t need to log into an application (like your WEM application) that relies on the authentication provider, such as e.g. Microsoft’s Active Directory or Entra ID. This is also known as “Single Sign-On” (or SSO).

Support for external Authentication Providers

The two most widely used protocols by authentication providers are SAML and OAuth2.

• SAML is used for authentication and authorization and is mostly used in corporate/enterprise environments. Microsoft (Active Directory / EntraID), Google (G Suite), Oracle and Salesforce are just a few companies that have SAML based authentication and authorization products.

• OAuth2 is mostly used as an authorization protocol and is widely used by social platforms like Facebook, LinkedIn, Twitter, etc. A lot of mobile apps use Oauth2 to authorize users to use the app (“Log in with your Facebook account”).

WEM supports both protocols. In the flowchart documentation about the authentication nodes you can find how to use these in your application. But before you can use them, the authentication providers need to be configured. That is the focus of this article.

Adding an Authentication Provider

First, choose which type (SAML or OAuth) you want to setup. Then go to the appropriate folder (SAML 2.0 authentication or OAuth 2.0 authorization) in the project tree and click on the Add authentication provider option in the context menu [...]. Give your identity provider a name that will be used throughout the WEM Modeler.

Next, continue with either SAML or OAuth settings...

Add a certificate

You can manage your certificates in the project resource bar under the tab Webservices and comet. In this pane, you see the folders to set up web services, authentication protocols and a certificates folder on the bottom. You have 4 types of certificates you can add, namely Client certificates, Server certificates, Trusted clients and Trusted servers. When you select a folder with the right mouse button you get an option window like this:

When you want to upload a certificate a new window appears with the option to drag and drop a certificate file, or you select one from your system by clicking the empty box. The different certificate types accept different filetypes.

• Client and server certificates: .pem, .pfx or .p12

• Trusted server and Trusted Client: .crt, .cer, .cert, .pem or .der

You can also create your own self signed client and server certificates. Selecting this option opens a new window with a form, here you can fill in the details of the certificates and create it.

Certificate details

Certificates that are added to the modeler can be viewed and downloaded. You can do this by using right-mouse-button or the [...] three-dot button. This opens the context menu, where you can select to open the certificate details or download the certificate. You can also download the certificate from the details screen. These are the details a certificate provides:

Private certificates

You can also download your private key. When you do this, you are prompted with a window giving you the possibility to include the private key. A private key is protected by a password you need to create before you can download your certificate.

You can find more detailed information about Certificates in WEM in the Security Section of the Project Settings: #certificates.

SOAP

WEM applications can use SOAP to integrate with external systems. SOAP “Simple Object Access Protocol” is a highly standardized and self-documenting messaging framework, where everything you can do is strictly defined in a WSDL “Web Service Description/Definition Language” document. SOAP is a very rigid integration standard, which makes it especially easy to use for novice or non-technical users, because both systems integrating with each other have a pre-defined way of communicating. When using SOAP, the data exchanged is always in the XML format, but you’ll never know, as WEM does all the translation from and to XML into the familiar WEM datamodels. WEM can both expose from (let others integrate with your WEM Project) and consume (integrate with other systems) SOAP web services with a minimum of technical skills.Before you can use SOAP services in your flowcharts, you need to configure the webservices that you want to be available. The same is true if you want to expose your application to external systems: you need to define the service that external systems can access.

Consuming webservices

In order to consume external SOAP services you need to specify those services in the WEM Modeler. To do this, you need to take the following steps:

In the project resources, click on Web services and comet to get the following screen where you manage the webservices:

Click on the three dots next to Add web service or use a right-click. When you select import webservice a window opens where you can give it a Service name and choose to import From web or From file. Select what applies. You pick From web if you have a URL from which you can load the service's WSDL (Web Services Description Language) file. This file contains the description of the web service you want to use. If the URL points towards a .asmx or .svc file, WEM will assume this refers to a .Net webservice and WEM then knows how to access the wsdl file. If you pick From file you either have to specify a wsdl file to upload or a zipfile in case you need multiple wsdl files (plus the xsd file) to specify the webservice.

When the webservice has been successfully defined, you can see the service being added to the resource pane on the left hand side.

The webservice is now ready to be used in the workflows of the application.

Changing endpoint configurations

In order to use the webservice, WEM needs to know the web service URL. By defaults this URL is the same for preview, staging and live environments. But if you want, you can change that. In the webservice overview simply open the context menu of the webservice, select service configuration and change the URL that needs to be changed. Changes in the configuration screen are automatically saved.

External webservices might require some kind of authentication in order to access them. These authentication requirements have to be defined in the WSDL. WEM supports Basic Authentication (username/password) and Client Certificate authentication. When consuming the WSDL in WEM, it should automatically recognize these requirements. In the service configuration window you can enter the required information (client certificate or username/password).

***If WEM does not seem to recognize the requirements (this can happen because of custom non-standard definitions that WEM does not yet recognize), you won't see the authentication fields in tab endpoint configuration. If you are sure there should be authentication, create a ticket and provide the WSDL as URL or file attachment so we can investigate how WEM should interpret this specific definition.

Details in the Project Resource pane

In the Project resource pane, the newly added webservice is visible:

Here you can also find the service operation, but you can drill down into the details. For every service operation you find:

• Input: if you click on this/open the node, you can see which fields are needed as input for the service operation to be executed successfully

• Output: these are the fields that contain the result of the webservice operation

• Faults: The fields that are available in case there are any errors

Using the webservice is done in flowcharts, where the same information is available, since that is where you work with the actual data.

Using

Exposing webservices

When you want your application to expose data to other systems, you can set up a webservice that other systems can access. To expose your application, you need to take the following steps:

1. Create the webservice that other systems can use to access your application by opening the context menu (three dots, right click) and select new webservice.

2. Create the operation(s) that other systems can use to access data and/or functionality that you want to expose to the outside world with the context menu and add new operation;

3. For every operation you need to specify the input and output fields that are needed. When you added a operation, you can find a input and output where you can add a field with the context menu;

4. For every operation you create a flowchart that takes care of processing input data as well as generating the output data is created. In this flowchart you add a bit of logic to handle the requests.

5. Document the webservice and operations, to provide all necessary information to the people that use your webservice. This option is available for the webservice and the different operations by using the context menu.

All these steps are explained in a bit more detail in the next sections

Creating a webservice

When you want your application to expose data to other systems, you can set up a webservice that other systems can access. To do this, you go to Web services and comet in the project resource pane and select Webservice (expose). You are now able to create a web service, by opening the context menu and clicking on New web service. You are then presented with the following form:

You only need to enter a name to create a webservices. This will create the webservice under the chosen name and a default URL (http(s)://{portal-hostname}/webservices/expose) with portal-hostname as placeholder. The form also has a lot of other options to customize the webservice. You can change the following settings:

• Enable WEM 2.7 compatibility mode Legacy option to make it make the service compatible with WEM 2.7. Only use this for this compatibility issues with old projects.

• Enable JSON fields renaming

• Publishing specific settings(covered in later sections):

  • Metadata exposure

  • Encryption method

  • Authentication method

You have can now find the created webservice in the resource pane under Web service (expose). With the context lets you can add operations, change the settings or edit the documentation and get the service working.

• Operations Now that you have created a webservice, you can start to create one or more operations. These operations define what data or functionality is being shared with external systems. To create a new operation, simply click on New Operation in the context menu. You have to specify the operation name (you cannot use any spaces or special charatars). and you can add documentation.

• Edit Settings When you click on this button the edit Web Service Window opens giving you the options to change the same settings as when you created the webservice.

• Edit Documentation Allows you to add specific documentation that is shown when the public URL of the web service is entered in a browser.

A operation shown in the project tree:

The next step to take is to define which information is needed as input for the webservice, and which information will be returned to the external system using the webservice.

Specify input, output & fault details

Every operation can define which input is needed, which output will be returned and what fault information is available. The input detail is input information that the operation needs in order to successfully execute the operation. All output that is returned is stored in the output details. And in case something goes wrong during the execution of the operation, fault information is available through the fault details. In order to define all the necessary information, every new operation creates an action flowchart and three empty folders in the operation tree:

When all data is specified, the final step is needed: create the flowchart that processes the request and make sure the correct data is returned.

Create operation flowcharts

To process the input for the exposed webservice and return the correct data, you need to create a flowchart for every operation that is available in the webservice. First you have to define the input and output (and fault) fields, as explained above. Next you create the logic for the processing in the created action flowchart. This flowchart was already created when the new operation was defined, so you can immediately start to work with this flowchart.

• Click on the operation in the Project tree. You are now in the webservice details overview where you will find all defined operations.

• Double-click on the operation to open the flowchart. When the flowchart is opened it initially only shows two nodes: a Start and a End: Succes node.

• Complete the flowchart where you use the input fields in your flowchart. The flowchart also assigns values to the output fields, to make sure the webservice can return the requested data. In case you run into an error situation, the flowchart can also assign data to the defined fault fields.

Document webservice and operations

The exposed webservice will be used by developers (or WEM Modelers) that want their systems to communicate/integrate with your application. In order to make that as easy as possible you can document your webservice and every individual operation. This documentation can be used to describe the webservice in general, to explain what an operation does, what input is needed, what output can be expected, etc. You can document whatever you want.

Documenting your webservice is done using the Edit documentation button that is in the context menu of your webservice and on every operation you defined. When you click on this option, you will get a documentation form:

Just hit the Save button to save the documentation.

To document an operation, simply click on the Edit documentation button in the operation overview screen. You get a similar documentation window as the service documentation:​

This documentation is available from the Edit webservice menu when you opened from the context menu of a webservice. When you open this window, and the Metadata exposure has been set to Public URL there is a link called Open public URL in new window link, next to the Metadata exposure field. This is the URL to the webservice documentation page, which will look like this:​

You will find the following information here:

• At the top is the service documentation, as you have specified it;

• A Resources section with links to information that is valuable for developers:

  • a link to the Full WEM WSDL best for WEM consumers (so developers can use that WSDL file to set up communication from their system to your WEM application);

  • a link to the Basic WSDL for non-WEM consumers

  • a link to a JavaScript file that can be used as the client JavaScript proxy;

  • a link to a Typescript definition file for a client proxy;

• An Operations section with a link to:

  • a page that contains Request and Response examples for

    • SOAP 1.1 & SOAP 1.2

    • JavaScript

    • JSON

    • These example show how based on one of the mentioned protocols your webservice can be used

  • At the bottom is the specific Operation documentation, as you have specified it.

You are now ready to expose this webservice to external systems: publish and share the endpoint links.

Webservice configuration

When you are ready building your webservice, you need to publish the project to make it available for consumers. Your webservice will be available at 3 different endpoints for preview, staging and live:

http(s)://{portal-hostname}/webservice/[webservicename]

You can find the correct links in the Edit Webservice window for each separate environment. There are two ways to find the links: Double selecting the webservice you want to see the details of or with the context menu and selecting edit settings. You will get de webservice details, including links to the correct endpoint URLs.​

The second way to exposing a webservice is through the Metadata exposure setting. You can change this by selecting the Public URL link. This setting offers two options to deal with the webservice metadata:

• Public URL: This will expose all metadata information that is available through the Go to documentation page link that will appear next to the dropdown box. This links to a page that is described in the previous section.

• By WSDL file: Only WSDL metadata is exposed. When this is selected, the user can click on the link on WSDL link that appears beneath the dropdown box. This will open an new browser window with a link to the webservice WSDL file;

Encryption

It is possible to specify how the communication with the webservice is encrypted. There are three possible methods:

• None: there will be no encryption;

• Transport: the communication will be encrypted. When this option is selected, you need to specify the authentication method:

  • None No authentication

  • Client certificate The SOAP procotol validates certificates

  • Username/password (build-in) The SOAP protocol validates client credentials

  • Username/password (flowchart) Check the client credentials in the flowchart of a web service operation

• Message: use this when the actual message itself (the content) needs to be encrypted. When this option is selected, you must:

  • Choose /upload a client certificate;

  • Specify the authentication method:

    • None No authentication

    • Client certificate The SOAP procotol validates certificates

    • Username/password (build-in) The SOAP protocol validates client credentials

    • Username/password (flowchart) Check the client credentials in the flowchart of a web service operation

You can specify the encryption method for each of the three environments: preview, staging and live. And each environment can have a different encryption approach.

Definition changed? Update consumer!

If you change your exposed webservice and publish it to staging/live environments, the consumers need to be updated. If your consumer is another WEM-project, just go to the webservices (consume) in the resource pane, open the webservice context menu and hit Update web service. This is necessary when:

• Input fields change;

• Output fields change;

• Faults change;

• Security settings changed;

• Operations change;

• Concepts in the Ontology change, which are used in any of the input/output single/multi-select fields (ontology-concepts are made part of the webservice definition)

Any of these changes results in a change of the contract, the definition of the webservice.

OAuth (short for "Open Authorization") is an open standard for access delegation, commonly used as a way for internet users to grant websites or applications access to their information on other websites without requiring the provision of passwords, as defined by Wikipedia. This article will outline the necessary configurations to integrate an OAuth authorization service, focusing on its implementation using Google as the service provider.

Before integrating an authorization service, it's important to set up the authorization provider. The setup procedure varies depending on the chosen provider. For the purposes of this article, Google will serve as the example provider; however, most OAuth service providers can be used (some notable providers).

Below is a visual representation of the OAuth process when used to get information from a google docs server:

Add Service

Once a provider is chosen and configured, the next step involves navigating to the "webservice & comet" tab located in the resource pane of the modeler project. Within this tab, the OAuth 2.0 authorization folder is accessible, serving as the designated area for configuring the client-side Authorization Service utilized by the authentication node within the flowcharts. To add a service, access the context menu of the OAuth folder through either right-clicking or selecting the three dots and choosing "add."

OAuth definition

Basic Settings

Server Details

The details needed for the server depend on the Grant type chosen, this type of authentication and communication used by the API. WEM supports the following grant types:

• Authorization Code

• Client Credentials

• JSON Web Token

Authorization Code

With the authorization code grant a code is exchanged for an access token where the user gets a chance to see what information access is requested. The user sees the authorization prompt and approves the app's request. The user is redirected back to the application with an authorization code in the query string, the application then exchanges the authorization code for an access token that unlocks the client application.

Client Credentials

In the case of the Client Credentials grant, the application requests an access token to access its own data or functionalities outside of the context of a user. This grant type is typically used by clients to access information or functionalities pertaining to the application itself, rather than those associated with a specific user.

JSON Web Token (JWT)

JWTs can be used as OAuth 2.0 Bearer Tokens to encode all relevant parts of an access token into the access token itself instead of having to store them in a database. The JWT Type enables creating a custom JWT claims.

When configuring the JWT definition, the initial step involves setting the token endpoint, which denotes the URL to which the JWT is dispatched. Following this, the subsequent step entails establishing the JWT Claims. A claim manifests as a name and value pair, wherein the name consistently assumes a string format, while the value may encompass any JSON value or expression. Two distinct types of claims exist:

• Registered: standard claims registered with the Internet Assigned Numbers Authority (IANA) and defined by the JWT specification to ensure interoperability with third-party, or external, applications. OIDC standard claims are reserved claims like:

  • iss (issuer): Issuer of the JWT

  • sub (subject): Subject of the JWT (the user)

  • aud (audience): Recipient for which the JWT is intended

  • exp (expiration time): Time after which the JWT expires

  • nbf (not before time): Time before which the JWT must not be accepted for processing

  • iat (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT

  • jti (JWT ID): Unique identifier; can be used to prevent the JWT from being replayed (allows a token to be used only once)

• Custom: consists of non-registered public or private claims. Public claims are collision-resistant while private claims are subject to possible collisions.

Client Details

Within the client details, inclusion of the Client ID and secret are imperative for secure communication with the client. This setup is configured on a per-portal basis, enabling the utilization of different IDs and Secrets as required. In this section, you can specify the redirect URLs for different portals and runtimes of the application. These URLs typically adhere to the following syntax:

• Preview: https://preview.wem.io/*projectID*/auth/oauth2/

• Staging: http://*projectName*.staging.wem.io/auth/oauth2/

• Live: http://*projectName*.live.wem.io/auth/oauth2/

Map Output

When utilizing an OAuth service for login, an access token is automatically generated and exchanged between the authorization server and resource server. This access or bearer token can be mapped to a field for use in custom webservices or when using JWT grant with custom headers.

The complete response of the authorization to the Oauth2 service can be mapped to a text field, this will contain the entire response returned from the service. This can be useful for debugging issues.

Set up the (Google) Authorization

Initially, an OAuth client ID Credentials must be established in the (Google) Cloud Console, along with the setup or selection of an API. Once the API is obtained, proceed to the credentials section, where you can navigate to OAuth 2.0 Client IDs. Alternatively, you can create a new one using the "create credentials" option, specifying "OAuth client ID" as the type, and choosing a name for identification purposes.

The next step is setting up the JavaScript origins and the Authorized redirect URIs. The JavaScript origins is the hostnames of the WEM project in preview, staging and live:

Preview: https://preview.wem.io Staging: http://wemdocumentation.staging.wem.io/ Live: http://wemdocumentation.live.wem.io/

The authorized redirect URIs is where you are redirected after the authentication by google. The path will be appended with the authorization code for access and can’t contain URL fragments, relative paths, or wildcards, and can’t be a public IP address. In the testcase this will be:

Preview: https://preview.wem.io/49367/auth/oauth2/oauth-2.0-playground Staging: http://wemdocumentation.staging.wem.io/ Live: http://wemdocumentation.live.wem.io/auth/oauth2/oauth-2-playground/

Back to the modeler

When the client, the provider and Oauth definition is set up the Oauth service can be used in the modeler. There are two main ways to use the Oauth implementation in a project; with a authentication node or with a http request node using the Oauth as authentication provider.

Authentication node

The authentication node can be used to authorize the application access to a API or to allow the project to perform actions on the resource provider or to check if a user has access to certain information. In the image below is an implementation where the Auth node is used to give the application access to certain actions on the provider service.

Getting access from google

In the following example the Oauth authorization is used to set up a GET request for a list of files in a google docs account. We set up the definition with the google examples talked about earlier:

Server settings:

The next step is setting up the authorization service in google docs, for this you can use the talked about method earlier, there you find the client details and add them to the Oauth definition in the modeler.

Preparing the datamodel

If the token field has not been created yet that would be the next step as this is where the Access token is mapped. The service also needs a response field to store the response and use it further in the application. For this specific example we also create a list to store the information received from google docs. In this case that is a FileType, MimeType, and Name field.

The flowchart and its interactions

This section involves creating the flowchart and setting up the necessary nodes for our service. The final result will resemble the following:

First, we set up a landing page from which the request is initiated, and its results are displayed upon completion. This corresponds to the OAuth node shown in the image above.

On this page we want have a button to start send the request and a datafield to show the results when we return.

The next node is the HTTP request node that handles the request to google docs and handles the OAuth authentication.

For the url we put the scope and endpoint of the google drive API service, in this case "https://www.googleapis.com/drive/v3/file" this lets the webservice know where to start. The request is a GET request and the default timeout is good enough. The Follow redirect should be toggled on as this is needed for the authentication, which is set to OAuth 2 with the Oauth definition made earlier as the provider. The only property left is the response body that can be written to the response field made earlier.

Next step is connecting the exits to the next node, for this solution a failed and a success node is created. These nodes just have to show the the response body to be able to see if it was successful and can be removed after set up is done.

The import node Datasource is the response body from the step before. Now we run the project and webservice, if this is set up correctly the response body can be used to create the import node mapping.

Now connect up the import node back to the original Oauth node with the data-grid and run the service. When everything is setup correctly he result can look like this: