SAML 2.0
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.
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 we do not describe that here in much detail. Point is, there needs to be an App Registration 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:
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.
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.
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...
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.
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!
Last updated
