User Authentication

Most of the times an application requires users to log onto the system. That means the application needs user management and users need to authenticate themselves and need to be authorized to access the application. To do this you have two 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);
Use an external authentication provider. In this case the WEM application relies on an external authentication provider to authenticate users.

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. This is called “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), 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 specified first. That is the focus of this article.

Adding an Authentication Provider

To add an authentication provider, go to the authentication provider node in the project tree and click on the Add authentication provider button in the toolbar.
First, you select the protocol your authentication provider uses. You can choose between Saml 2.0 and OAuth2. Give your identity provider a name that will be used throughout the WEM Modeler.
Next, you’ll see the authentication provider settings screen. This is where you need to enter all the details to make the authentication work.

Using Saml 2.0

To best explain what to do here, we will use a Microsoft Azure Active Directory and Microsoft Active Directory as authentication providers. If you need another provider, it works very similar.

Getting Federation metadata to import into WEM

The easiest and safest way to get these settings right, is to start with metadata from the 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. WEM can read and import this xml information and convert it into the settings for the Authentication Provider.

So, before we continue in WEM, we need to get the Federation Metadata document to be imported.

Scenario 1: Authentication against Microsoft Azure Active Directory

Log-in to your Azure Active Directory portal. You have to be Administrator to do this.
Next, click on Azure Active Directory, then on App Registrations and finally on Endpoints.

You now get a list of URLs that can be used to integrate your application with Microsoft Azure Active Directory.

Copy the Federation Metadata Document link, open it in your browser, and click on Ctrl-S] to save the document as XML file.

Scenario 2: Authentication against Microsoft Active Directory

Open the Active Directory Federation Service UI
Next, expand Service, click on Endpoints, go to Metadata and check the link for the Federation Metadata

Copy the Federation Metadata Document link, open it in your browser with the ADFS hostname as the prefix, and click on Ctrl-S to save the document as an XML file.

Importing the metadata

In the WEM Modeler, expand Authentication providers in the project tree and click on the recently added provider. In our case, we named it Study Case. You now get back to the settings:

In the toolbar, click on Configure from Metadata and select the metadata XML file you just saved. Click on Ok to import the metadata.
You will now see that the WEM Modeler has imported all the settings for the Identity Provider section.

In case of Scenario 1 (Authentication against Microsoft Azure Active Directory) you must also check the checkbox Fetch keys at runtime and then past the federationmetadata URL you copied from Azure AD

Registering the application with the provider

Scenario 1: Authentication against Azure Active Directory

Log-in to you Azure Active Directory portal. You have to be Administrator to do this.
Next, click on Azure Active Directory, then on App Registrations en finally on New application registration

Fill in the form. Give the application a correct name and make sure you select Web app / API as Application type and add an Sign-on URL which can be changed later. This URL is a URL you will be able to use from the Microsoft Portal to sign-on your application.

Click on Create.
Once created, select Settings, Properties and Copy the value of the App ID URI value. Be sure to keep this value somewhere as you will need it in the next step.

Go back to the WEM Modeler. Make sure you don’t close the browser where you just created the application.
In the Authentication provider settings page, paste in the Entity ID field the value you just copied from the Azure Active Directory.
Be sure to change Secure hash algorithm to SHA-256
Select Download metada from de top toolbar

We are now going to copy all Reply URLs you need to add in the Azure Active Directory Application Registration Settings.
Select a portal if you have more than one, and select the correct Runtime mode.
Click on Download the service provider metadata to download the metadata.

Once downloaded, open the XML document and copy the URL next to the attribute location:

Return to the browser with the Azure Active Directory Application Registration settings. Select Reply URLs and then add https: + the URL you just copied. Do not forget to save your changes.

If you already have set the Runtime URL for Staging and Live, you will have to repeat the following operation for Staging and Live in the Runtime mode field.

You have now setup the authentication provider for Azure Active Directory so it can be used in your application.

Scenario 2: Authentication against Microsoft Active Directory

Open the Active Directory Federation Service UI
Right-click on Relying Party Trusts and select Add Relying Party Trust Wizard to open the Add Relying Party Trust Wizard. Click on Start:

Check the Enter data about the relying party manually option and then click on Next:

Add a Display name (in our case it is Study Case) and then click on Next:

As you do not need a Certificate for our example, just click Next on the next screen
Click also on Next in the Configure URL windows as we will do it later on after having downloaded the application metadata.
To be able to fill in the Replying party trust identifier, you will need to go back to the settings page of the Authentication provider in the WEM Modeler. Copy the value of the Entity ID field and make sure that the Secure hash algorithm is set to SHA-256

In the Active Directory UI paste the just copied Entity ID value into the Relying party trust identifierfield en click on Add

Click on Next

As in our example everyone from the Windows Domain will be able to use the Authentication Provider, just click on Next in the Choose Access Control Policy form
Click Next in the Ready to Add Trust screen and then Close
Your Relying Party Trust is now displayed in the right panel.

Go back to the WEM Modeler Authentication Provider settings page and click on Dowload metadata

Now wee are going to copy all Reply URLs you need to add in Endpoints tab of the Relying Party Trust we just made.
Select a portal if you have more than one portal, and select the correct Runtime mode.
Click on Download the service provider metadata.

Once downloaded, open the XML document and copy the URL next to the attribute location

Go back to the Active Directory Federation Service UI and double-click the just created Relying Party Trust
Select the Endpoints tab and then click on Add SAML..

Eindpoints 01

Select SAML Assertion Consomer as Endpoint type, POST as Binding, paste the copied URL value using https: as prefix and then click on OK.

If you already have set the Runtime URL for Staging and Live, you will have to repeat the operation for Staging and Live in the Runtime mode field.
Click on Apply and OK once finished.

You have now setup the authentication provider for Microsoft Active Directory so it can be used in your application.

Attributes and response handlers

Managing attributes

It is possible to add attributes that the WEM authentication provider can pass on to the flowcharts. This way it is possible to e.g. get the display name or the email address of the user that signs in. These attributes depend on what the actual authentication provider can provide. To add and manage attributes, click on Manage attributes.
You now get to the form where you can add and manage attributes:

If you correctly loaded the XML with the provider settings you see a list of attributes that are pushed by the provider. You can delete or add attributes when needed. Please refer to the documentation of your SAML provider to get the correct information to add attributes (specifically the name of the attribute).
To use the attributes, you need to open an attribute and specify a datafield that is defined in the WEM Modeler. This datafield will be populated with the correct data whenever the provider is called to check whether a user is signed in or to sign in a user.

Note: the list of attributes that you see when you click on Manage attributes is dependent on the authentication provider. Some push all possible attributes, some just a few. Always check the provider’s documentation to find out which attributes may be available, even if they are not in the pushed list of attributes,

Managing Response Handlers

When you look at the provider settings, there is a column called Response Handlers. This is the right column.
Here you can map response handlers for the ‘Subject name’and ‘Response message’ to data fields in your application. This works very similar to the attributes the provider pushes. This information is always provided bu the authentication providers.

The ‘Subject Name’ is basically the user that is trying to sign in.
The ‘Response message’ can be used for debugging purposes.
To map these handlers to a WEM data field: simply click on the button on the right-hand side of the field and select the appropriate field.

You may want to read the article on how to use the authentication node to realize single sign-on functionality