FME Flow Troubleshooting: SAML

FME Flow 2022.0+ has incorporated SAML authentication as a security login. Our documentation will give you information on what's required from FME Flow. We also have detailed steps to configure Auth0 ,Okta, OneLogin and AzureAD SAML but any other identity provider (IdP) that uses SAML 2.0 should ideally work with FME Flow and the setup should be similar to the above examples-

• Creating an app on the IdP with SAML 2.0 as the protocol
• Providing the app with the two URLs that we have on FME Flow Web UI- Entity ID (Audience URI) and Single Sign On URL (ACS URL)
• All other IdP settings can be per organization policy. 
• Make sure that the users/groups on IdP that you would like to import are assigned to this app
• Upload the metadata file from the IdP side to the FME SAML settings webpage.

Are you encountering issues configuring SAML in FME Flow? Please read below for some common troubleshooting tips and issues.

Expected Login Behaviour

FME Flow is the service provider (SP) and SAML application [eg. Okta, Azure AD SAML] is the identity provider (IdP). Currently, for our SAML implementation, we only support SP-initiated login, which means that users must go to the FME Flow Web UI and choose to “Log in with SAML”. The user is then taken to the IdP login page where they can input their IdP credentials and successfully log into Flow. 

This is unlike the LDAP/AD SSO where FME will automatically pull the credentials if you are logged into the client machine as the LDAP user and not prompt for the user password.   

For IDP-initiated SAML login [which is not supported yet], users already logged in, for, e.g. to their corporate Google/Okta/Azure account, would be able to skip the FME Flow login step because they would already be trusted.

User Creation

With SAML integration, users do not exist on FME Flow prior to the first log-in. Any user approved by the SAML IdP [the user will need to be assigned to the app created on the IdP side] will be able to log in to FME Flow. The first time they log in, the user will be created within FME [also called just-in-time “JIT” provisioning]. The user will be assigned to the role that was selected during the SAML configuration using the Attribute mapping or the “New User Default Role” setting. FME SuperUser can add/remove roles from the SAML user post import as well. 

Initial Troubleshooting Steps

• HTTPS configuration on FME Flow will be a prerequisite for SAML. 
• Ensure that you have enabled Just-in-Time provisioning/Automatic user provisioning on Azure AD SAML, as this is a required setting for user creation. 
• Ensure you create a new app on your IdP for each FME Flow instance [or any other software using SAML integration on your organization] as the Entity and SSO URIs are not customizable.  
• Try the SAML login in the incognito/private tab in different browsers.
• Check SAML logs fmesaml.log and restV4.log under “services” logs for any errors.
• If private /public IP addresses have been configured for Windows FME Flow hosts, please ensure that the host file has entries that map the private and public IP with the FQDN [hostname used during Flow installation and Web UI access]
• SAML Tracer Chrome extension is a great tool to view request-response between service [FME Flow] and IdP. You can export and send over the JSON trace file of a SAML login attempt, which can then be imported and viewed on the SAML Tracer tool. For more information about the tool, please see SAML-Tracer to Collect Logs for Troubleshooting | Okta Support 
• You can use Base64 Encode and Decode Online Tool | SAMLTool.com to decode the request and response payload. Copy the encrypted SAML Request payload under the Network tab of the Chrome developer tools [Network>Payload>view URL- encoded]and decode from “XML to Base64”. The example below is with Okta.

• Check the sign-in logs on the IdP for more information about the login attempt.
• For Azure AD SAML Only - 
  • Azure AD SAML has the option to “Test single sign-on with …….” on the app’s webpage. Ensure that the test is successful to confirm that the configuration on the Azure side is correct.  

Common Issues

“The logged session is not persisting and UI prompts the user to input SAML credentials repeatedly.”

The SAML configuration has some advanced settings that can be found in the application.properties text file located under <Resources>/Utilities/tomcat/webapps/fmesaml/WEB-INF/classes. Change the parameter “fmeserver.saml.authentication.force” from true to false. FME Flow Web Services will need to be restarted after the change. 

In the fmesaml.log file, we see this value would be true. By default, true, this will always force the prompting for user credentials when SAML login is initiated. If false, depending on the SAML login state (if sessions are cached in the Browser), the user may automatically login.

“Azure AD SAML Authentication is implemented & access is working, but initial ID/field mapping is not populated as expected/desired” 

This is specific to Azure AD SAML. Under the section “Enter attribute names from your Identity Provider to map to FME Flow User attributes for newly created users.”, specify the attribute names, including namespace as shown below-

Values for  First Name (optional) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

Last Name (optional) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Username (optional) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameID

Email (optional) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

“Login prompt keeps looping. A login request is followed by a redirection to the IdP URL login page. It then redirects back to the FME Flow Login page.” 

Please make sure to provide the IdP with the exact Entity ID (Audience URI) and Single Sign On URL (ACS URL) from the FME Flow Web UI. 

“When the FME Flow web UI is accessed via FQDN, SAML login attempt [after typing in the IDP credentials and submitting] loops to the IDP login prompt webpage. SAML works well after replacing the flow host FQDN with IP address.”

This is a known issue FMEFLOW-21670. The resolution is to reference the flow/server host with IP address instead of the FQDN [i.e. FME_SERVER _WEB_URL field in fmeServerConfig.txt and fmeServerWeb ApplicationConfig.txt]. Also, setup the SAML configuration with the URLS that contain the IP address instead of the FQDN. Please note that once this change has been made, the Web UI URL with IP address should be used to access the UI and login via SAML. 

“Hostname that contains the string “fmeserver” creates incorrect SAML Identity Provider URLs under Authentication Services> SAML Configurations.”

You will see the full server name missing, string “/fmeserver” twice and a missing forward slash[/] in “http:/”.

This is a known issue FMEFLOW-20430. Correct the hostname in the Entity ID and Single Sign On URL and remove the following “/fmeserver” [i.e. the first “/fmeserver”] string from the URL. These correct URLs must then be provided to your SAML provider for configuration. 

“Login failing with FME Flow behind reverse Proxy or a Load balancer in Fault-tolerant setup and HTTPS is configured over the reverse proxy/LB and FME Flow is on HTTP.” 

Please confirm that the following changes to the server.xml have been made [This file is located in <FMEFlowDir>\Utilities\tomcat\conf.]

Update the proxyPort directive to 443:

proxyPort="443"

Update the scheme directive to https:

scheme="https"

When HTTPS is configured on the reverse proxy rather than the Apache Tomcat web application server, this is a required configuration. This entire process is also mentioned in the documentation- Configuring for HTTPS under the Linux section. 

Also, please see this document SAML Authentication Failure to set the fully-qualified hostname of your reverse proxy to the fmeserver.saml.custom.baseurl= line in the SAML application.properties file

“Migrating to SAML from Azure AD. Both IdP are connected to the same Azure AD tenant. Is it possible to change the user's IdP to SAML from Azure AD, instead of creating new users and manually shifting ownership of existing FME Flow objects?”

You would have to import the same users again via the SAML connection. If it causes duplicates and you would like to retain the SAML username, then you will have to delete the Azure AD user before importing the SAML user. But if SAML usernames can be specified to be different than the already existing Azure AD users, you can import the SAML users with a different username. You can then transfer the ownership and delete the Azure AD user from FME. In this case, you have information about which Azure AD user owns which FME object and can use it to transfer ownership manually to the corresponding SAML user.   

If users were imported as a group and the users are still a part of that group on the FME- side, then we could create a new role for the SAML users and load the template from another role. We can choose the Azure group as a template and the item permission would be replicated from Azure AD to SAML. 

Then, you can specify this new user role that you would like to assign to the newly imported SAML user and they will all inherit the associated permissions. 

“In the case of a configuration with a signed FME Flow request, if the SAML login fails and the fmesaml.log file has the following format error”

Tue-11-Jun-2024 03:01:19.112 PM   ERROR https-jsse-nio-443-exec-12   417551 : An error occurred during SAML login: Key is not in PEM-encoded PKCS#8 format, please check that the header begins with -----BEGIN PRIVATE KEY-----

Or 

Tue-11-Jun-2024 03:04:41.304 PM   ERROR https-jsse-nio-443-exec-1   417551 : An error occurred during SAML login: java.security.spec.InvalidKeySpecException: java.security.InvalidKeyException: IOException : DerValue.getBigIntegerInternal, not expected 48

Please confirm that the format for the FME Flow certificate and key uploaded on the FME and SAML side are DER-encoded or PEM-encoded X.509 certificate and PEM PKCS#8-encoded key.

“The SAML request fails with Internal Error 500 and SAML Tracer shows no login request being sent out to the SAML provider.”

Try manually providing the Identity Provider SSO URL, Identity Provider Issuer and Identity Provider X.509 Certificate instead of uploading the metadata file. 

“SAML integration and login were working well until Microsoft IIS was setup as a Reverse proxy and now the SAMl login attempt experiences an "HTTP Status 404 - Not Found" error. You also notice that clicking on “Log in with SAML“ takes you to the link https://<reverse-proxy-hostname> instead of the expected "https://login.microsoftonline.com........ ”.

This error could be related to the IIS settings. Per our article Using IIS and ARR as a Reverse Proxy in FME Server, please untick the option “Reverse rewrite host in response headers” [it would be ticked by default] in the ARR server proxy settings. Otherwise, this would cause the issue where the redirect request FME sends to "login.microsoftonline.com" will have a modified host and hostname/URL instead.

"SAML with Azure AD on an FME with a reverse proxy setup gives an error "XML attribute 'AssertionConsumerServiceURL' in the SAML message must be a URI." [Another SAML provider might have a different error message string.]"

You would need to make changes as mentioned in SAML Authentication Failure  when you introduce reverse proxy or load balancer to the Flow setup and need to enable SAML . But please confirm that the fmeserver.saml.custom.baseurl value has the string "https://". 

Are you still experiencing issues?

Please consider posting to the FME Community Q&A  if you are still experiencing issues that are not addressed in this article. There are also different support channels available. When contacting support please share the tomcat log folder located in Resources > Logs. 

Have ideas on how to improve this?

You can add ideas or product suggestions to our Ideas Exchange.