Setup external authentication with OAuth2.0
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:
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."
Name
A unique name used in only in the modeler for identification.
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
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.
Authorization endpoint
Token endpoint
Scope
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.
Token endpoint
Endpoint used to request a token used to validate the login to the client. The client credentials are used for validation.
Scope
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.
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/
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.
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/
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.
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.
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:
Grant type
Authorization Code
Authorization endpoint
Token endpoint
Scope
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.
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.
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:
Server endpoint used for sign in authentication. This is the start page to login into the provider service. For google this is:
Endpoint used to exchange the authorization code for a access token used to validate the login to the client. For google this is:
The scope is a space-delimited list of permissions in string format, used to limit an application's access to a user's account. For google you can find examples here:
The scope is a space-delimited list of permissions in string format, used to limit an application's access to a user's account. For google you can find examples here:
In this case we want to use a specific google service scope called:
Setup SSO-integration using SAML 2.0
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.
We have added a very extensive guide how to register an App for SAML SSO in Microsoft Entra ID.
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;
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).
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).
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.
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:
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):
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.
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.
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.
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.
The fact that fields Signature Certificate and Require that assertions are signed are so close together, may lead you to think that these 2 fields belong together and should be changed together.
This is NOT the case! Please read on...
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.
So, to summarize: it is very likely that the Owner for your Project, the Identity Provider, wants the optimal security and compels you to at least actively check the Signature the Identity Providers uses to sign the response with.
To do this:
Activate the option Require that the assertions are signed in the Service Provider Settings;
Check the Signature Certificate in the Identity Provider Settings, and use the option Fetch Certificates at Runtime if possible.
The Service Provider Require .assertions. signed setting therefore corresponds to the Signature certificate in the Identity Provider settings - and not to the Signature certificate directly above the setting itself...
This is a CROSSED reference situation... settings on both parts need to be considered!
If the customer/Identity Provider wants even more security and demands that also the Requests from your Application are Signed by the Application, you need to:
Create/upload a Client Certificate with Private Key to be used by the application to sign the requests (mind and manage the expiration date...);
Share the public part of the certificate with the Identity Provider (you can download the public part of the certificate in WEM);
Select this certificate in the Service Provider Settings, at the Signing Certificate;
Switch the option Requires that the request is signed on the Identity Provider Settings.
The Identity Provider Require .request. signed setting therefore corresponds to the Signature certificate in the Service Provider and not to the signature certificate directly below the setting itself or the fetch at runtime situation...
This is a CROSSED reference situation... settings on both parts need to be considered!
WEM supports SAML2.0 and OAuth2.0
Some external blogs about SAML vs OAuth:
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.
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).
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.
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...
This page describes how to create an App Registration in Microsoft Entra ID to be used as a SAML Identity Provider in WEM.
Microsoft does make changes to their approaches, so we can not guarantee that what we describe here will remain exactly the same. But it should help...
Go to https://entra.microsoft.com/ (you need to have admin permissions).
In the sidebar menu, find the Applications and within that option, go to Enterprise Applications.
Click on New Application.
Click on Create your own application.
Add a name, select "Integrate any other application you don't find in the gallery (Non-gallery)" and click Create.
Wait until the app is created.
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.
Back on the overview, click 2. Set up Single Sign On and select the SAML option.
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.
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.
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!
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.
