SAML

Introduction

The SAML module can be used to give end-users access to your Mendix application based on their identity in your Identity Provider (IdP). A Mendix application that uses the SAML SSO module will delegate user login to your Identity Provider using SAML 2.0.

By configuring the information about all identity providers in this module, you will allow users to sign in using the correct identity provider (IdP). There is no limit on the number of different identity providers you can configure.

Typical Use Cases

The following use cases are supported by both the SAML and OIDC SSO modules:

• Your app is designed for your company’s employees, and you want these employees to sign in to your app using corporate credentials hosted by your identity provider (IdP).
• Authenticating against your Microsoft Active Directory server in a secure manner utilizing the SAML capabilities of Active Directory Federation Services (ADFS) — the SAML protocol allows for the encryption of all information transferred between the two servers, so, VPN connections, LDAP, or Kerberos authentication are no longer needed.

The following use cases are supported by SAML:

• Implementing SSO in your Mendix App through a Shibboleth Identity Provider.

• Identifying the end-users of your Mendix app through SAML-enabled national identity schemes such as eHerkenning, a Dutch eID scheme for B2B or B2G scenarios, or DigiD, which gives Dutch citizens access to (semi) governmental services.

  Some of these identity schemes use optional features of SAML, which are not yet supported in the SAML SSO module — see Limitations for more information.

• Authenticating within a Mendix session — for example, requiring end-users to re-authenticate shortly before they are allowed to do critical transactions in your app, or having a second user authenticate within the context of the first user’s session in your Mendix app.

• Single Logout is supported.

Features

SAML Protocol Adherence

This section is aimed at readers with more knowledge of the SAML protocol. You may skip this section.

1. The SAML SSO module supports the following SAML 2.0 profiles for your Mendix app acting as a Service Provider (SP):

   • Web browser SSO profile using one of the following bindings
     • HTTP redirect
     • HTTP POST bindings
     • Artifact binding for SAML responses (Mendix 8 and above)
   • Single Logout profile

2. For encryption of SAML messages, the following options are supported:

   • No Encryption
   • 1024 or 2048-bit encryption
   • SHA1 or SHA256 algorithms

Usage of SAML Metadata

The Mendix SAML SSO supports the usage of SAML metadata in the following way:

• Daily synchronization of the IdP metadata, so your Mendix app will always have the latest IdP metadata.
  • For daily synchronization of IdP metadata, configure the SE_SynchronizeIdPMetadata scheduled event. For local development, this can be done from Studio Pro. In Mendix Cloud, you can do this on the Environments Details page for your app.
• Downloading the metadata for your Mendix application that acts as an SP in the SAML protocol.

SAML Module Configuration Feature

For easy configuration, the SAML module offers the following:

• From version 4.0.0 of the SAML module, if you want to connect your Mendix application with a single IdP, you can do the necessary configurations at design time (using a microflow) and/or deploy time using Application Constants. This is described in the section Non-default Configuration.

• You can create a custom SAML configuration microflow and share it across all SAML applications in your portfolio, such as using a custom module in your private marketplace. This approach makes SAML configurations both automatable and repeatable.

• Runtime configuration by a local Admin is still available in the following cases:

  • If you want to connect multiple IdPs with your SAML app.
  • If you want to upload a keypair for your app.
  • If errors occur during deploy-time SSO configuration via the Cloud Portal, it may be easier to refine the setup through Admin screens and then adjust deployment constants.

• A SAML administration screen that allows you to configure one or multiple SAML IdPs. IdP discovery is supported by an endpoint that returns a page listing all configured IdPs so the end-user can select the IdP where they have an account.

Other Features

• The SAML module keeps a log/audit trail of login attempts. These can be downloaded.
• The SAML module allows you to have an SSO connection with multiple SAML IdPs. Each IdP can have its own keypair.
• SAML module versions 3.5.0 and above (compatible with Mendix version 9.22.0 and above) support multiple keypairs.
• Starting from version 4.2.0, the SAML module supports multi-instance apps (horizontal scaling).

Limitations

The Mendix SAML SSO module does not support the following:

• SAML1.0
• Enhanced Client/Proxy SSO profile
• HTTP artifact binding for SAML requests

When using SSO connections with multiple IdPs, the SAML EntityID for your app will be shared with all connected IdPs. The SAML module does not allow you to configure different EntityIDs for each of your connected IdPs.

Some SAML services, such as eHerkenning and DigID in the Netherlands, use optional features of SAML which are not yet supported by the Mendix SAML SSO module. These include:

• Signature included as a query string parameter in URL (for HTTP-REDIRECT)
• Restriction of RelayState to 80 characters (SAML SSO may generate RelayState values that exceed 80 characters)
• ProviderName
• Scoping
• RequestedAuthnContext in the SAML requests
• HTTP-SOAP Logout Request

If you need any of these features, contact your Mendix CSM to discuss the inclusion of these features on the Mendix roadmap or the customization of the SAML SSO module.

Versions of the SAML module below 3.5.0 are limited to a single key pair. If you are using one of those older versions and you want to connect your app to multiple SAML IdPs, you cannot use different key pairs and certificates for each of the SSO federations. Instead, you must use a single key pair and certificate for all SAML IdPs. The certificate can be either a self-signed certificate or a certificate issued by a certificate authority (CA). For more details, see the Use a Certificate Issued by a Certificate Authority section of Advanced Configuration for SAML.

If you use both the OIDC SSO module and the SAML module in the same app, each end-user can only authenticate using one IdP.

The URL for downloading the SP metadata of your app is independent of the value of the EntityID that you configure for your app, which is included in the SP metadata. Instead, the metadata URL is based on the alias for the connected IdP where the SP metadata will be used.

Controlling the configuration using constants requires an app restart, and it is only possible when your app is connected to a single IdP.

Custom user provisioning flows created for a SAML V3.x are still supported in V4.x but cannot be configured during design/deploy-time.

Prerequisites

• For apps running outside of Mendix Cloud, make sure you have external file storage configured.

  The SAML module writes configuration data to a file document on the file storage to read it later. Without external file storage, this configuration will be lost when you restart your app. The SAML module will not work correctly without reading the configuration data from the file storage.

• For apps running on a Microsoft Windows environment, add the following rules to the Microsoft Internet Information Services Server Configuration:

  <rule name="sso"> <match  url="^(sso/)(.*)" />
      <action type="Rewrite" url="http://localhost:8080/{R:1}{R:2}" /></rule>
  <rule name="submitloginform">
  <match  url="^(SubmitLoginForm)" />
      <action type="Rewrite" url="http://localhost:8080/SubmitLoginForm">
  </rule>

Dependencies

• Mx Model Reflection module.

• Encryption module – this is needed to encrypt the key store passwords in version 3.5.0 and above of the SAML module.

• User Commons module (for version 4.0.0 and above)

  If you are using Mendix version 10.21.1, use the User Commons module version 2.1.0 or upgrade to version 2.1.2. Version 2.1.1 of the module is a special release intended solely for Mendix version 10.21.0.

Installation

There are different versions of the SAML module, depending on which version of Mendix you are using. To find and install the correct release, follow these steps:

1. In Mendix Marketplace, search for the SAML module.

2. In the Documentation tab, the compatibility guidance section indicates the latest recommended version for your LTS/MTS Mendix release. These guidelines are updated with each release of the SAML module, and you should refer to them to choose the version of the module that is compatible with your app. For additional information, some general considerations are listed below:

   • For Mendix 8, you should use the latest published versions in the 2.x range, unless otherwise indicated in the Documentation tab.

   • For Mendix 9, there are odd- and even-numbered patch releases that contain the same changes and require the same Mendix version, but differ based on the version of Atlas UI that your app uses:

     • The even-numbered releases (for example, 3.6.2) are intended for apps that use the 2.0 version of Atlas UI, that is, apps that were originally built on a version of Mendix below 9.0.0, and then upgraded to Mendix 9.
     • The odd-numbered releases (for example, 3.6.3) are for new apps that are built using Mendix 9 and are using version 3.0 of Atlas UI.

   • For Mendix 10, you should use the latest versions of the module that are compatible with the 3.0 version of Atlas UI (that is, the version for apps newly built on Mendix 9 or newer). These are currently the same as the odd-numbered releases mentioned above for Mendix 9; in future releases of the SAML module, there will be separate versions of the module dedicated to Mendix 10.

     Mendix 10 does not support the 2.0 version of the Atlas UI, so you should never use the even-numbered (Atlas 2.0-compatible) SAML patch releases with your Mendix 10 app.

3. To download the required release, in the Releases tab, find the release that is compatible with your app per the guidelines in the Documentation tab, and then click the Download button by the number of the release.

4. Follow the instructions in How to Use Marketplace Content to import the SAML module into your app.

Post-installation Configuration Steps

By default, the SAML module will be installed as the SAML20 module in your app’s Marketplace modules. You can find all microflows and other configuration elements in this module.

1. Configure the Startup microflow in the SAML module (SAML20.Startup) to run as (part of) the After startup microflow. This microflow will initialize the custom request handler /SSO/ (please note the importance of using the final / for all instances of /SSO/), validate all IdP configurations, and prepare the configuration entities required during the configuration.

2. If you have set up path-based access restrictions in your cloud (for example, Path-Based Access Restrictions in Mendix Cloud), ensure that access to /SSO/ is allowed.

3. Add the OpenConfiguration microflow to the navigation, and then allow the administrator to access this microflow.

4. Review and configure all the constants:

   • DefaultLoginPage – You can specify a different login page when the login process fails. When the end-user cannot be authenticated in the external IdP, a button will appear, and by clicking this button, they will be redirected to the specified login page. If this is left blank, an unauthenticated user will be redirected to /login.html.

   • DefaultLogoutPage – Removing the sign-out button is recommended, but if you keep it, the end user will be redirected to a page. You can choose where the end-user is redirected to (for example, back to /SSO/ or your login.html page). Every user signed in via SAML is redirected to this location when logged out.

   • SSOLandingPage – Set this if you redirect the index.html to log into your app automatically. See Using SSOLandingPage for further information about this.

   • HybridAppLoginTimeOutInMinutes –

     • If you use the default login handler in your hybrid mobile app, you must change the com.mendix.webui.HybridAppLoginTimeOut custom runtime setting to change the validity of the authentication token used by the hybrid mobile app.

     • If you use the SAML module in your hybrid app, you must change the SAML20.HybridAppLoginTimeOutInMinutes constant to change the validity of the authentication token used by the hybrid mobile app.

     • If you use both the default login handler and the SAML module in your hybrid app, you must change both so that they match. This is because, when you use the SAML module for SSO in your Mendix app, the authentication token is not created by the Mendix runtime, which uses the custom runtime setting. Instead, the authentication token is created by the Java code in the SAML module. This Java code does not have access to the custom runtime setting value and thus requires the constant value to be set.

       Only use this setting if you are using SAML on a hybrid mobile app. Note that this functionality also requires mobile authentication tokens to be enabled in your IdP Configuration as well as changes to the hybrid app package as described in How to Implement SSO on a Hybrid App with Mendix and SAML.

     Hybrid mobile apps are not available in Mendix 10.

5. Sign in to the application and configure the SAML module as described in the Configuration SAML Module section.

Using SSOLandingPage

You can use single sign-on (SSO) to automatically sign users into your app by redirecting every user accessing index.html to the Mendix /SSO/ endpoint. To do this, you need to add <meta http-equiv="refresh" content="0;URL=/SSO/" /> to the index.html file.

If you use this method, do not forget to set the SSOLandingPage constant to a value different than index.html. Otherwise, the app will come back to index.html, which will be redirected again to single sign-on, resulting in an endless loop. SSOLandingPage specifies a different landing page so the end-user does not end up on index.html again after a login attempt. Mendix recommends changing this constant to /index3.html and creating an index3.html page in your /theme folder and copying the contents of the original index.html (without the added redirect) into it. The authenticated end-user will then land on index3.html, which will display the content of the app. If the user authentication fails, the user will be directed to the DefaultLoginPage instead.

Upgrading from SAML 3.X to 4.X

The table below introduces you to several key updates when you upgrade the SAML module from V3.x to V4.x.

Configuring SAML Module

Configuring the SAML module is crucial for setting up secure authentication within your application. It involves reviewing and updating the Service Provider (SP) settings and creating or updating the Identity Provider (IdP) configuration.

In versions below 3.6.9 of the SAML module, configuration can be done using the app pages – see the Using SSO Landing pages section above. However, in version 4.0.0 and above, you have the option to use constants or custom microflows to configure your app at deploy time.

This section explains three different ways to complete the deploy-time configuration of the SAML module. The Easy Flow configuration offers a default and straightforward setup, while the Non-default configuration enables customization of the IdP configuration by implementing custom microflows. Alternatively, in the Runtime Configuration Flow, you can deploy your app first and then complete the configuration within the app interface.

Easy Default Flow

This configuration offers simple and default settings. It is the ideal configuration for quickly implementing the SAML module, particularly for users aiming to kickstart their SSO application. With this approach, users can create an SSO app in the IdP without complete dependency on SP metadata. The following sub-sections guide you through the detailed configuration steps:

Creating SP Manually at Your IdP

To enable the single sign-on (SSO) method as SAML 2.0, you need to manually create an application on the IdP server.

Creating SP Manually at Okta

To kickstart the SAML module with Okta, refer to the images below. Ensure to log in with Okta Developer credentials. In the new application, configure the following fields and get the IdP metadata URL:

• Single Sign-On URL: This should be your application URL.
• Audience URI (SP Entity ID): By default, this is set to the application URL.
• Other Requestable SSO URLs (Callback URLs): This should be set to <Application URL>/SSO/assertion.
• Index: The default value is zero. Ensure it matches the value you set for the Assertion Consumer Service Index.

After creating an application, you will receive an IdP metadata URL. This URL is used in the IdP configuration to Read IdP metadata from URL.

The setup described above offers default configurations to start the SAML module. Any changes made to the configuration will require adjustments to other configuration details accordingly.

Creating SP Manually at Entra ID

To connect Azure with SAML, refer to the image below.

For the IdP configuration, the default value for the Assertion consumer service index is 0. Set the corresponding value to 0 for the Index.

Setting up Eight Mandatory Constants

To configure the Service Provider (SP) and Identity Provider (IdP) metadata, you need to set up eight mandatory constants. In the App Explorer of your Mendix app, you can find the following six constants within the SPConfiguration > USE_ME folder. These constants are used to configure the SP Metadata.

• Org_Name: This constant represents Name.
• Org_DisplayName: This constant represents Display Name.
• Org_OrganizationURL: This constant represents the Organization URL.
• Org_GivenName: This constant represents the Given Name.
• Org_Surname: This constant represents Surname.
• Org_Emailaddress: This constant represents the Email address.

The following constants in the IdP Configuration > USE_ME folder help configure IdP metadata.

1. IdPAlias
2. IdPMetaDataURL

If you provide values for the above constants, the SAML module will automatically generate the required/default additional configurations with the help of the Default_CreateIDPConfiguration microflow.

SP_Entity is an optional constant in the SP Metadata that represents the SP Entity.

Deploy the Application and Login with SSO

After configuring the eight constants, you need to deploy the application. For details, see the Deploying the App section in the Deploying an App to Mendix Cloud. Once deployed, you can now log in to your application using SSO.

Non-default Configuration

The Easy Default Flow section above gives you an overview of the default settings. If you have requirements to deviate from these defaults, for example, to enable Force Authentication, change encryption settings from the default, or support multiple Identity Providers (IdPs), Non-default configuration setup offers advanced options for your SAML integration needs. With these features, you can customize the SAML configuration to meet your specific requirements.

In this configuration, you have several options to customize the Identity Provider (IdP) settings. Firstly, you can configure the IdP using constants. Additionally, the SAML module supports further customization of the IdP configuration. From version 4.2.0 onward, you can define your custom microflow name in the IdPConfiguration_MicroflowName constant. The custom microflow must return a list of configured IdPs (Dep_IdPConfiguration.return), which the SAML module then uses to generate the necessary SSO configurations for multiple IdPs. The default value of the IdPConfiguration_MicroflowName constant is SAML.Default_CreateIDPConfiguration.

In versions earlier than 4.2.0, IdP customization was supported through the implementation of a custom microflow called Custom_Create_IdPConfiguration. However, this microflow has been deprecated as of version 4.2.0.

In this configuration, users have the flexibility to introduce their own constants by creating custom IdP configurations. To enable this configuration, you need the IdP metadata obtained by creating an SSO app in the IdP without complete dependency on SP metadata.

Follow the steps mentioned in the Easy Default Flow with an additional custom configuration in Studio Pro. After setting the eight mandatory constants, proceed with the custom configuration.

Creating Custom Configuration

This module uses non-persistence entity names starting with Dep_.

The following entities are used to create IdP configurations:

• Dep_IdPConfiguration: IdP details
• Dep_SPAttribute: List of Attribute Consuming Service requested attribute
• Dep_SAMLAuthnContext: List of SAMLAuthnContext
• Dep_IdpAttributeEntityAttributeMapping: List of Attribute Mapping

The table below shows you the different attributes and their values for quick reference. You can see the details of these attributes of the above entities in the Reference Guide for SAML IdP Configuration document.

Deploy the application and log in with the SSO. For more information, see the Deploy the Application and Login with SSO section above.

Runtime Configuration Flow

This process involves configuring both the Identity Provider (IdP) and the Service Provider (SP) metadata to establish secure authentication for the user. In some IdPs, SSO app creation is not allowed without having SP metadata. This configuration method is ideal for such scenarios. The following subsections provide you with detailed instructions on integrating your application with SSO:

Deploy Your Application and Login with Application Admin

Deploy your application and log in with the application Admin account. Click SAML; currently, no configurations are available.

Configuring Steps

1. Navigate to the Model Reflection, select the required module from the left navigation pane, and select Click to refresh to synchronize entities and microflows. In version 4.x, refreshing the module is no longer required.

2. In the SP Configuration tab, provide the necessary values and click Save. Complete this step before proceeding with IdP Configuration.

3. In the IdP Configuration tab, click New and provide the necessary details. For more information on IdP configuration tabs, see the Reference Guide for SAML IdP Configuration document.

   The SAML20.DefaultEntity constant is used at runtime to prefill the default user provisioning entity when creating a new SAML IdP configuration, with Administration.Account set as the default value.

4. From version 4.0.0 of the SAML module, you have the option to download the SP Metadata from the Encryption Settings tab, Identity Provider Metadata tab, and at the end of the configuration process.

Downloading and Uploading SP Metadata Manually

After completing the IdP configuration, download the SP metadata. Upload the SP metadata details to the IdP provider, either via URL or by downloading the SP metadata XML file provided. This typically involves transferring the file to the IdP provider responsible for configuring authentication on the IdP server.

Downloading and Uploading IdP Metadata Manually

Once you configure and upload the SP metadata, on the Identity Provider Metadata tab of the application, you can upload the IdP metadata. This can be done by either using the IdP metadata URL or uploading an XML file.

With the completion of these steps, your application is now configured for SSO.

Configuring IdP-Specific Settings

Before configuring any IdP, you need to configure the Service Provider (SP), which is your current application. The SP configuration allows you to configure some basic information for the SP metadata file. This information will be available to the IdP administrator for reference.

Each IdP should have its own configuration set. Every IdP can be configured and enabled separately. All changes made in the configuration are immediately applied when you save the configuration.

If you have multiple IdPs, please make sure each IdP has a unique Entity descriptor. If you add multiple IdPs with the same entity descriptor, you might experience unexpected behavior where a different SSO configuration is selected than the alias provided.

When creating a new IdP configuration, you are guided through a workflow to help you configure everything required for the IdP configuration. Each option in the workflow is explained below and can be changed by editing an existing IdP Configuration.

Use Previous to go back to the previous dialog or Cancel to abandon your changes. Click Save on the last step to save the configuration.

Downloading SP Metadata

Upon completing the IdP configuration steps above, you only need to send the SP metadata file to the IdP and have them configure the authentication on their end. The SAML module generates separate SP metadata for every connected SAML IdP (see Configuring the IdP-Specific Settings). The SP metadata for your app can be obtained by clicking Download SP Metadata on the final configuration step (or in the Identity Configuration, Encryption Settings, or Identity Provider Metadata tab) to download the XML file or by opening http://<Application Root URL>/SSO/metadata/<IDP-Alias> for your app’s URL.

Additional Settings

The following settings apply to the IdP configuration:

• Alias – The alias for your IdP can be used in the URL of the application to indicate the IdP configuration that should be used during login. The alias must be unique, but you should also make sure that this alias is compatible with usage in a URL (meaning, no /, &, ?, or any special character that could get lost in the communication).

• Log SAML Requests – Determines whether all requests and login attempts should be logged and stored in an entity.

When you add a new configuration or change an existing one, you should restart your app. This ensures that the correct configuration is used.

User Provisioning

The SAML module provides you with so-called Just-In-Time (JIT) user provisioning. To read more, refer to Just-In-Time User Provisioning via SAML.

URLs

The following diagram gives an overview of all endpoints that the SAML SSO module exposes and consumes:

End-users can access your app through the following endpoints when using the SAML SSO module:

• /SSO/discovery – If there are multiple active IdP configurations and discovery is enabled, this page can give a list of all the IdP configurations. It also allows the user to click the correct URL to sign in.
• /SSO/login/[IdP Alias] or /SSO/login?_idp_id=[IdP_Alias]&action=verify&on={contextname} – For logging using a specific IdP, you have to open either of these two URLs and pass the IdP alias as a parameter in the URL. The (optional) parameters for this endpoint are as follows:
  • idp_id – this indicates which idp will be used to sign the end-user in if you connect your app using multiple SAML IdPs
  • action=verify – indicates that in-session authentication is being requested (see In-session Authentication for more information)
  • on={contextname} – this gives context to the initiation of in-session authentication, (see In-session Authentication for more information)
• /SSO/login or /SSO/login?action=verify&on={contextname} – If you have only one active IdP, opening these URLs will automatically try to log you in using the active IdP. In the case of multiple active IdPs and discovery enabled the user will be redirected to the discovery page. If discovery is not allowed, the user will receive an error message. The optional parameters work as described above.

Your SAML IdP can consume the following endpoints at your app. Typically the SP-metadata is used to communicate the URLs to your SAML IdP. As a Low-Code Developer, you don’t have to consider these endpoints. This information is included here for completeness and as a reference when questions arise around integration with your SAML IdP.

• /SSO/metadata/[IDP-Alias] – This provides a point for the IdP to automatically download the metadata from this SP
• /SSO/assertion – This is the endpoint where the IdP submits the SAML assertion to the so-called ‘Assertion Consumer Service’
• /SSO/logout – This URL will trigger a single logout

Read More

• Academy lecture SSO Using SAML

  You must log into the Mendix Platform to see the lecture above.

• Just-In-Time User Provisioning via SAML

• Advanced configuration for SAML

• Reference Guide for SAML IdP Configuration

• OIDC SSO