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 onApp Registrations
and finally onEndpoints
.
- 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 onEndpoints
, go toMetadata
and check the link for theFederation 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 onApp Registrations
en finally onNew application registration
- Fill in the form. Give the application a correct name and make sure you select
Web app / API
asApplication 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 theApp 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
toSHA-256
- Select
Download metada
from de top toolbar
- We are now going to copy all
Reply URL
s you need to add in theAzure Active Directory Application Registration Settings
. Select a portal
if you have more than one, and select the correctRuntime 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. SelectReply URLs
and then addhttps:
+ the URL you just copied. Do not forget to save your changes.
- If you already have set the
Runtime URL
forStaging
andLive
, you will have to repeat the following operation forStaging
andLive
in theRuntime 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 selectAdd Relying Party Trust Wizard
to open theAdd Relying Party Trust Wizard
. Click onStart
:
- Check the
Enter data about the relying party manually
option and then click onNext
:
- Add a Display name (in our case it is
Study Case
) and then click onNext
:
- As you do not need a Certificate for our example, just click
Next
on the next screen - Click also on
Next
in theConfigure 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 theAuthentication provider
in the WEM Modeler. Copy the value of theEntity ID
field and make sure that theSecure hash algorithm
is set toSHA-256
- In the Active Directory UI paste the just copied
Entity ID
value into theRelying party trust identifier
field en click onAdd
- Click on
Next
- As in our example everyone from the
Windows Domain
will be able to use theAuthentication Provider
, just click onNext
in theChoose Access Control Policy
form - Click
Next
in theReady to Add Trust
screen and thenClose
- Your Relying Party Trust is now displayed in the right panel.
- Go back to the
WEM Modeler Authentication Provider
settings page and click onDowload metadata
- Now wee are going to copy all
Reply URL
s you need to add inEndpoints
tab of theRelying Party Trust
we just made. Select a portal
if you have more than one portal, and select the correctRuntime 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 createdRelying Party Trust
- Select the
Endpoints
tab and then click onAdd SAML..
- Select
SAML Assertion Consomer
asEndpoint type
,POST
asBinding
, paste the copied URL value usinghttps:
as prefix and then click onOK
.
- If you already have set the
Runtime URL
forStaging
andLive
, you will have to repeat the operation forStaging
andLive
in theRuntime mode
field. - Click on
Apply
andOK
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.
Next
You may want to read the article on how to use the authentication node to realize single sign-on functionality