diff --git a/content/en/docs/marketplace/platform-supported-content/modules/SAML/advanced-configuration.md b/content/en/docs/marketplace/platform-supported-content/modules/SAML/advanced-configuration.md new file mode 100644 index 00000000000..a3cdfa203e9 --- /dev/null +++ b/content/en/docs/marketplace/platform-supported-content/modules/SAML/advanced-configuration.md @@ -0,0 +1,158 @@ +--- +title: "Advanced SAML Configuration and Troubleshooting" +url: /appstore/modules/saml/advanced-configuration +linktitle: "Advanced Configuration and Troubleshooting" +weight: 20 +description: "Describes the advanced configuration and troubleshooting for the SAML module." +--- + +## Introduction + +This document explores advanced configurations and troubleshooting strategies for the SAML module, including multitenant setup, certificate management, login page customization, and deep link integration. + +## Advanced Configuration + +In this section, you can learn about advanced configurations for the SAML module. For basic configuration and usage, refer to the [SAML](/appstore/modules/saml/) documentation. + +### Multitenant Behavior + +The resource folder contains a file called *SAMLConfig.properties*. In this file, you can optionally override advanced settings from the SAML module. Usage of this file is optional. When the file does not exist, or you do not specify a setting, the module will use its default behavior. +This file contains the documented properties, and example lines show the default values of these options. +With these settings, you can configure the behavior of this module and improve the multitenant behavior of your application. For plain SAML authentication, it is best to leave this file unchanged. + +If you are using a custom URL, see [How Do I Get my SAML Metadata or CommunityCommons.GetApplicationUrl to Use the Custom URL?](/developerportal/deploy/custom-domains/#use-custom-url) in the *Custom Domains* documentation. + +### Use a Certificate Issued by a Certificate Authority {#use-ca} + +By default, the SAML SSO module will use self-signed certificates. It is, however, also possible to use certificates issued by a certificate authority (CA). + +SAML SSO supports 2 file formats: + +* a PKCS 12 file, which typically has an extension .pfx or .p12. +* a jks file. + +To use a CA certificate, upload it as your key store file as described in [Managing the Keys and Key Store](/appstore/modules/saml/idp-attributes/#keystore). +Remember to do the following: + +* Set the certificate password in the `KeystorePassword` constant of your app to be able to read the contents of the uploaded key store. +* Use an alias for the certificate — this must be the name parameter that is provided when creating the certificate you are uploading. If the values do not match, the SAML module will fall back to using a self-signed certificate instead. +* The value of the configured SP EntityID must match the alias that is included in the uploaded key store. + +### Customizing the Login Page + +The Mendix runtime/system module comes with a default login page. When using SAML with a single IdP, this page is not required. +You need to customize this login page when end-users have different ways of login: + +1. If you want to use both Mendix (local) login and SSO login: + + 1. Go to the **App** > **Show App Directory in Explorer** > **theme/web** folder (for Mendix versions below 9.0.0, this is the **theme** folder). + 2. Rename `login.html` to `login-without-sso.html`. + 3. Rename `login-with-mendixsso-button.html` to `login.html`. + 4. Open login.html, update the **href** to `/SSO`, and give a button name. + + Your app is now configured to use Mendix SSO login. +2. If you want to connect your app with multiple IdPs, and the end-user of your app needs to select the IdP to use for login. + Follow the steps below: + + 1. Go to the **App** > **Show App Directory in Explorer** > **\implementation\DiscoveryHandler.java** + 2. Find the template **saml2-discovery-binding.vm** and add your customization. + +### Custom Settings + +The resources folder contains the *SAMLConfig.properties* file, and through this file, advanced settings can be configured for the module. This file contains the settings along with documentation on the settings. Through this file, it is possible to alter the URLs used as well as how the application behaves in a multitenant environment. The file also specifies all the default values and behavior in more detail. + +If you are using a custom URL, see [How Do I Get my SAML Metadata or CommunityCommons.GetApplicationUrl to Use the Custom URL?](/developerportal/deploy/custom-domains/#use-custom-url) in the *Custom Domains* documentation. + +### Using Deep Links + +{{% alert color="info" %}} +The Deep Link module has been deprecated from Studio Pro 10.6.0 and replaced by [page URLs](/refguide/page-properties/#url) and [microflow URLs](/refguide/microflow/#url). For instructions on migrating to page and microflow URLs, see the [Using Page and Microflow URLs with SAML](#page-microflow-url-saml) section below. +{{% /alert %}} + +If end-users who use the deep link do not yet have a session in your app, the deep link can trigger the SSO process. If successful, the end-user will be automatically redirected back to the deep link. + +For more information on using the Deep Link module (with Mendix 8 and 9), see the [Using Deep Link Module](#using-deeplink) section below. + +#### Using Page and Microflow URLs with SAML{#page-microflow-url-saml} + +Page URLs and Microflow URLs are supported with SAML for Mendix version 10.6 and above. To do this, follow the steps below: + +1. In the **Runtime** tab of the **App Settings**, configure the page **URL prefix** to **link** instead of the default **P** to maintain compatibility with existing URLs. +2. Ensure to remove the Deep Link module from your app to start the app successfully. For more information, see the [Migrating to Page and Microflow URLs](/appstore/modules/deep-link/#migrate-page-micro) section of the *Deep Link*. + +##### Steps for SAML Versions above v3.6.17 and v4.0.1 + +1. To use the Page URL functionality, replace the content of *login.html* with the content of *login-with-mendixsso-automatically.html* (located in the **resources** > **mendixsso** > **templates** folder) without changing the file name. +2. To implement the SSO redirection, replace the code in the `