This page is for administrators who need to integrate PhixFlow authentication with a SAML system.

Overview

Security Assertion Markup Language (SAML) is a standard for providing secure single-sign on for users. On Microsoft Windows Servers, the single sign-on identity for users are provided by the Active Directory Federation Services (ADFS) component.

On Windows Server systems that are running ADFS, you can configure PhixFlow to be a SAML Service Provider. This involves mapping PhixFlow user groups to the Active Directory groups. When a user attempts to log into PhixFlow, they are redirected to the authentication page of your system's identity provider, where they enter their username and password. If they are successfully authenticated they will then be redirected to PhixFlow and logged in.

Panel

borderColor	#7da054
titleColor	white
titleBGColor	#7da054
borderStyle	solid
title	Sections on this page

Table of Contents

indent	12px
style	none

To set up SAML integration, you need to add details to the configuration file, phixflow-login.xml, which is in the directory <tomcat root>/webapps/phixflow/WEB-INF/classes. This file is created during installation, by copying the example file phixflow-login.xml.example, and setting any essential options; see Install PhixFlow Webapp.

1.1 Specify the Authentication Manager

Edit the authenticationManager section of phixflow-login.xml to add a samlAuthProvider.

Find this section of the file:

Code Block

	<security:authentication-manager alias="authenticationManager">
		<!-- test authentication provider, leave commented out -->
		<!-- <security:authentication-provider ref="testAuthProvider" /> -->

		<!-- local authentication provider - provide access for CenterView database users. Don't change it -->
		<security:authentication-provider ref="localAuthProvider" />

		<!-- Add an Active Directory Authentication Provider below this line; uncomment if using active directory integration -->
		<!-- <security:authentication-provider ref="exampleActiveDirectoryAuthProvider" /> -->

		<!-- Add SAML Authentication Provider; uncomment if using saml / single sign-on -->
		<!-- <security:authentication-provider ref="samlAuthProvider"/> -->
	</security:authentication-manager>

Edit it to look like this (omitting comments):

Code Block

language	xml

	<security:authentication-manager alias="authenticationManager">
		<security:authentication-provider ref="localAuthProvider" />
		<security:authentication-provider ref="samlAuthProvider" />
	</security:authentication-manager>

Tip
We recommend that you keep the `localAuthProvider` and a local administrator user. This means you can still login if there is problem with the SAML integration.

1.2. Configure Login Forms

Edit the loginConfiguration section of phixflow-login.xml to define the login form options (local, single sign-on, active directory). These specify what the user sees on their PhixFlow login screen. This mechanism allows you to define a default form tailored to regular users and one or more forms for advanced users; see Configure Login Forms for details.

1.3. Enable SAML Beans

Edit the beans profile section section of phixflow-login.xml. Edit the 2 blocks that disable the options that are only required when PhixFlow is managing user authentication.

Find these lines:

Code Block
<!-- comment out to enable saml / single sign-on --> <beans profile="saml">

Remove them or comment them out:

Code Block
<!-- comment out to enable saml / single sign-on --> <!-- <beans profile="saml"> -->

Find these lines, near the end of the file:

Code Block
<!-- comment out to enable saml --> </beans>

and remove them or comment them out:

Code Block
<!-- comment out to enable saml --> <!-- </beans> -->

1.4. Configure the keyManager

Edit the keyManager section of phixflow-login.xml to specify the keystore.

Tip
SAML integration requires one or more public/private keys. Keys are stored in a Java keystore file. For information about configuring a keystore, see Configure Tomcat For HTTPS.

The minimum updates required are to set:

"file:/.../keystore.jks" to your keystore
"KeyStorePassword" to your keystore password
"keyPassword" to your key password
"keyAlias" to an key entry name that exists in the keystore.
"defaultKeyAlias" to a key that exists. If the key does not exist PhixFlow will report an error when a user attempts to log in.

Example of a keyManager bean configuration:

Code Block

language	xml

	<!-- The KeyStore stores encryption keys -->
	<bean id="keyManager" class="org.springframework.security.saml.key.JKSKeyManager">
		<!-- the keystore file -->
		<constructor-arg value="file:/opt/tomcat/secure/keystore.jks" />
		<!-- password protecting the keystore -->
		<constructor-arg type="java.lang.String" value="keyStorePassword" />
		<constructor-arg>
			<map>
				<!-- key alias and key-specific password; add one entry for each key in the keystore -->
				<entry key="keyAlias" value="keyPassword" />
			</map>
		</constructor-arg>
		<!-- default key alias -->
		<constructor-arg type="java.lang.String" value="defaultKeyAlias" />
	</bean>

Warning
For security reasons, access to phixflow-login.xml and to keystore.jks should be read-only to the Tomcat user or user account. It must be unreadable by all other users.

1.5. Configure the Context Provider

The context provider communicates the external view of the PhixFlow server to other parts of the configuration.

If the server does not run behind a reverse proxy, you can skip this section.

If the server runs behind a reverse proxy, a different context provider must be configured to reflect the public view of the service.

Edit the Context Provider section of phixflow-login.xml.

Delete the original contextProvider
Uncomment the reverse proxy version
Change the serverName, serverPort and contextPath to match the public view.

Find these lines:

Code Block     <!-- context provider when not behind reverse proxy

Insert excerpt

	_Banners
	_Banners
name	administration
nopanel	true

This page is for PhixFlow administrators who need to integrate PhixFlow with Azure AD to support Single Sign-on (SSO). This uses the SAML protocol.

Overview

Security Assertion Markup Language (SAML) is a standard for providing secure single-sign on for users.

This page describes integrating with Azure Active Directory to support SSO. If you would like to use ADFS (Active Directory Federation Services) to support SSO, please contact support@phixflow.com.

This page describes two modes:

mixed - in mixed mode, AAD performs the authentication for the users, and PhixFlow the authorisation.
mapped groups - in mapped groups mode, the groups that the user has been assigned to in AAD are mapped to PhixFlow groups; in other words, AAD is responsible for both authentication and authorisation.

Prerequisites

Before configuring SAML integration you must set Tomcat:

to use HTTPS
to have the secure flag on session cookies.

See Install Tomcat.

Adding an Unlisted (Non-Gallery) Application in Azure

Log into the Azure portal and navigate to the Enterprise Applications blade

Image Added

Click on New application
Image Added
Select Create your own application and then radio button Integrate any other application you don't find in the gallery (Non-gallery)Image Added
Enter a suitable name to represent the application, e.g. example-phixflow-prod, then click Create
The application Overview page will then appear
Image Added
Under the Manage section on the left hand side menu, click Properties and ensure the following settings apply:
1. Enabled for users to sign-in? is set to Yes - this determines whether users assigned to the application can sign in
2. User assignment required? is set to Yes - this determines whether users who aren't assigned to the application can sign in
3. Visible to users? is set to Yes - this determines whether users assigned to an app can see it in the access panel and M365 launcher

Image Added

Configuring SAML-Based Single Sign-On to Non-Gallery Applications via Azure AD (Identity Provider)

Under the Manage section for the above application in Azure, select Single sign-on
Select SAML

Image Added

The Set up Single Sign-On with SAML page will appear. The only changes required are in step 1 and 2 as shown in the following screenshot:

Image Added

Click the pencil icon in the top left corner of the first step and enter the following:
- Identifier (Entity ID): https://[domain]/[webapp], e.g. https://phixflow.example.com/phixflow
- Reply URL (Assertion Consumer Service URL): https://[domain]/[webapp]/saml/SSO, e.g. https://phixflow.example.com/phixflow/saml/SSO
  Image Added
Click Save and close this configuration box to return to the main Set up Single Sign-On with SAML page above.
Click the pencil icon in the top left corner of the second step to edit the user attributes and claims. The default attributes and claims should look similar to the following list:
Image Added
Click the Unique User Identifier (Name ID) attribute and set Source to Transformation on the claim page. A configuration window will open up:

Image Added

Set Transformation to ExtractMailPrefix() and Parameter to user.userprincipalname. Press Add, then press Save:

Image Added

Click Add a group claim
In the configuration window which opens up, select All groups
Select the source attribute - in the example it shows Group ID

Note

Source attribute

Group ID is fine to use when using mixed mode - that is, authentication is performed by AAD and authorisation is performed by PhixFlow.

When using mapped groups mode, this option works, but you will have to put GUIDs (e.g. 6f674ed0-bc19-4150-8af0-09100a33b6a2) into the external group fields in PhixFlow, which is less user friendly for PhixFlow administrators.

Other than Group ID, most options are only available if you are syncing with an on-premise Active Directory.

However, if you select Groups assigned to the application you can select Cloud-only group display names. If you choose this option, make sure you add groups as needed to the Enterprise Applcation (see https://phixflow.atlassian.net/wiki/spaces/HELP100/pages/9106732489/Configure+AAD+Integration+via+SAML#Add-users%2Fgroups-to-the-enterprise-application)

Image Added

Press Save. This can be updated in future to harden the groups that are emitted
The resulting list of attributes and claims should look similar to the following:
Image Added
In the third step (SAML Certificates), there is an option to download the Federation Metadata XML. Click Download:

Image Added

Upload the downloaded XML file to the server that is hosting the PhixFlow application
In the fourth step (Set up <enterprise application name>), copy the value for Azure AD Identifier (it is of the form https://sts.windows.net/[id_string]/) - this will be needed later in the configuration of PhixFlow

Image Added

Add users/groups to the enterprise application

Navigate to the Users and groups section of the Enterprise Application:

Image Added

Assign users or groups to the application as needed by following the on-screen prompts.
There is functionality to bulk select users from the list and search for specific users.

Configuring PhixFlow (Service Provider)

To set up SAML integration, you need to add details to the configuration file, phixflow-login.xml, which is in the directory <tomcat root>/webapps/phixflow/WEB-INF/classes. This file is created during installation, by copying the example file phixflow-login.xml.example, and setting any essential options; see Install the PhixFlow Webapp.

Specify the Authentication Manager

Edit the authenticationManager section of phixflow-login.xml to add a samlAuthProvider.

Find this section of the file:

Code Block

	<security:authentication-manager alias="authenticationManager">
		<!-- test authentication provider, leave commented out -->
		<!-- <security:authentication-provider ref="testAuthProvider" /> -->

		<!-- local authentication provider - provide access for CenterView database users. Don't change it -->
		<security:authentication-provider ref="localAuthProvider" />

		<!-- Add an Active Directory Authentication Provider below this line; uncomment if using active directory integration -->
		<!-- <security:authentication-provider ref="exampleActiveDirectoryAuthProvider" /> -->

		<!-- Add SAML Authentication Provider; uncomment if using saml / single sign-on -->
		<!-- <security:authentication-provider ref="samlAuthProvider"/> -->
	</security:authentication-manager>

Edit it to look like this (omitting comments):

Code Block

	<security:authentication-manager alias="authenticationManager">
		<security:authentication-provider ref="localAuthProvider" />
		<security:authentication-provider ref="samlAuthProvider" />
	</security:authentication-manager>

Note
We recommend that you keep the `localAuthProvider` and a local administrator user. This means you can still login if there is problem with the SAML integration.

Set up User Accounts

If you are using mixed mode, create PhixFlow user accounts. Mixed users are authenticated by SAML but their access privileges are managed using User Groups in PhixFlow; see User.

Configure Login Forms

Edit the loginConfiguration section of phixflow-login.xml to define the login form options (local, single sign-on, active directory). These specify what the user sees on their PhixFlow login screen. This mechanism allows you to define a default form tailored to regular users and one or more forms for advanced users; see Configure Login Forms for details.

Enable a Cookie Filter

Edit the sameSiteCookieFilter section of phixflow-login.xml to set the SameSite property on the session cookie. This is required to initiate login from the PhixFlow login form.

Edit it to look like this:

Code Block

language	xml

<bean id="sameSiteCookieFilter"
	class="com.accipia.centerview.web.filter.SameSiteCookieFilter">
	<property name="cookies">
		<props>
			<prop key="JSESSIONID">None</prop>
		</props>
	</property>
</bean>

Enable SAML Beans

Edit the beans profile section section of phixflow-login.xml. Edit the 2 blocks that disable the options that are only required when PhixFlow is managing user authentication.

Find these lines:

Code Block
<!-- comment out to enable saml / single sign-on --> <beans profile="saml">

Remove them or comment them out:

Code Block
<!-- comment out to enable saml / single sign-on --> <!-- <beans profile="saml"> -->

Find these lines, near the end of the file:

Code Block
<!-- comment out to enable saml --> </beans>

and remove them or comment them out:

Code Block
<!-- comment out to enable saml --> <!-- </beans> -->

Create a certificate and configure the keyManager

In this section we will generate a self-signed certificate, store associated private and public keys in a keystore, and edit the keyManager section of phixflow-login.xml to specify the keystore. A self-signed certificate is acceptable in this case because this is used to protect the SAML exchange, a private exchange between two systems. This certificate is not used to identity the service provider to general users over the public internet.

These steps involve the use of the Java program keytool, which should already be installed on your server if it has been prepared for PhixFlow by a standard installation of Java.

Windows

Code Block

language	powershell

keytool -genkey -alias tomcat -keyalg RSA -keystore pathToKeystoreFile

E.g.

Code Block

language	powershell

keytool -genkey -alias tomcat -keyalg RSA -keystore C:\app\secure\saml\keystore.jks

Linux

Code Block

language	bash

keytool -genkey -alias tomcat -keyalg RSA -keystore /opt/phixflow/secure/saml/keystore.jks

Recommended: select the default option not to set a separate password for the private key. You can set separate passwords if you wish; if you do, take a note of these and set as needed in the configuration of phixflow-login.xml (see below). The security advantages of setting separate passwords are limited in this case.

E.g.

Code Block

language	bash

sudo mkdir /opt/phixflow/secure/saml
keytool -genkey -alias tomcat -keyalg RSA -keystore /opt/phixflow/secure/saml/keystore.jks
sudo chown -R tomcat:tomcat /opt/phixflow/secure
sudo chmod 500 /opt/phixflow/secure
sudo chmod 400 /opt/phixflow/secure/saml/keystore.jks

Warning
Ensure that you create your keystore in a location that is only accessible to privileged users

Now update the section of phixflow-login.xml that describes the keystore:

Code Block
<!-- The KeyStore stores encryption keys --> <bean id="

contextProvidercontextSAMLContextProviderImpl />

Example of Context Provider configuration (comments omitted):

Code Block <bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderLB"<propertynamescheme" value="https"<property name="serverName" value="myserver.com"/<propertynameserverPort443<property name="includeServerPortInRequestURL" value="false"/> <property name="contextPath" value="/phixflow"/> </bean>

1.6. Configure the Metadata Generator

SAML communication is via an exchange of metadata between:

the SAML identity provider, such as Active Directory Federation Services (ADFS)
and a SAML Service Provider, in this case PhixFlow

Each party generates metadata to describe how to connect to it. That metadata must be installed into the other party before any connection can be made.

The metadata generator generates the PhixFlow server's metadata based on configuration parameters and data available when a user tries to connect to it.

Edit the metadataGeneratorFilter section of phixflow-login.xml and set:

entityId to a value that globally identifies the PhixFlow instance
entityBaseURL to a the URL normally used to start PhixFlow.
If PhixFlow is running behind a reverse proxy, this should be the public URL, not the internal URL which only the proxy sees.

This is the metadataGeneratorFilter section before configuration:

Code Block  <bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter"> <constructor-arg> <bean class="

<constructor-arg>
			<map>
				<!-- key alias and key-specific password; add one entry for each key in the keystore -->
				<entry key="keyAlias" value="keyPassword" />
			</map>
		</constructor-arg>
		<!-- default key alias -->
		<constructor-arg type="java.lang.String" value="defaultKeyAlias" />
	</bean>

The minimum updates required are to set:

"file:/.../keystore.jks" to your keystore
"KeyStorePassword" to your keystore password
"keyPassword" to your key password; if you took the recommended option above when creating the keystore, this will be the same as the previous password
"keyAlias" to the key you created in the keystore above; if you followed the example, this will be tomcat
"defaultKeyAlias" to a key that exists. If the key does not exist PhixFlow will report an error when a user attempts to log in. If you followed the example, this will also be tomcat.

For example:

Code Block

language	xml

	<!-- The KeyStore stores encryption keys -->
	<bean id="keyManager" class="org.springframework.security.saml.

metadataMetadataGenerator <property name="entityId" value="urn:test:phixflow:phixflow" /> <property name="entityBaseURL"https/myhostname:myport/phixflow <property name="extendedMetadata" <bean classorgspringframework.security.saml.metadata.ExtendedMetadata"> <property name="idpDiscoveryEnabled"false</bean>/property> </bean> </constructor-arg> </bean>

1.7. Configure the Identity-Provider Metadata Provider

The identity provider metadata provider defines how PhixFlow installs and handles the identity-provider's metadata. For example, PhixFlow can either enable or disable additional security checks.

Save the identity provider's metadata file in a convenient folder. This example assumes it is in the metadata directory, which is alongside the phixflow-login.xml file. To put the metadata in an unrelated directory, you can specify a path using:

either classpath:dir1/file
This refers to a file in directory dir1 under the webapp's classpath. This is ambiguous as it can mean webapp/WEB-INF/classes/dir1 and tomcat/lib/dir1.
or file:/dir1/file
This refers to the top-level directory /dir1. Without the forward slash / it refers to dir1 under the current directory, which is normally the Tomcat home directory.

Edit the metadata provider

This is the metadata provider section of phixflow-login.xml.

Code Block

language	xml

!-- key alias and key-specific password; add one entry for each key in the keystore -->
				<entry key="tomcat" value="83dSKFnck130xSLDjzjd9Y" />
			</map>
		</constructor-arg>
		<!-- default key alias -->
		<constructor-arg type="java.lang.String" value="tomcat" />
	</bean>

Warning
For security reasons, access to phixflow-login.xml and to keystore.jks should be read-only to the Tomcat user or user account. It must be unreadable by all other users.

1.7. Configure the Context Provider

The context provider communicates the external view of the PhixFlow server to other parts of the configuration.

If the server does not run behind a reverse proxy, you can skip this section.

If the server runs behind a reverse proxy, a different context provider must be configured to reflect the public view of the service.

Edit the Context Provider section of phixflow-login.xml.

Change metadata/idp-metadata.xml to the location of the identity provider's metadata file.

file-base identity-provider (idp) metadata-thisdefinesthemetadata for a single identity provider -->idpFileMetadataProvidermetadataExtendedMetadataDelegate<constructor-arg> <bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider" <constructor-arg> <value type="java.io.File">classpath:metadata/idp-metadata.xml</value> </constructor-arg> parserPoolrefparserPool </bean> </constructor-arg> <constructor-arg> <bean class="org.springframework.security.saml.metadata.ExtendedMetadata"> addpropertiestoextendthemetadata

<bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderImpl" />

Example of Context Provider configuration (preceding comments omitted):

Code Block
<bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderLB"> <property name="

localfalse </bean> </constructor-arg>metadataTrustChecktrue

Step 2 Generate Service Provider Metadata

When phixflow-login.xml is configured, you can generate metadata for the PhixFlow server.

2.1 Attempt to login using SAML / Single Sign-on.
The login attempt generates metadata. However the login itself will fail because you have not yet installed PhixFlow's metadata in the identity provider.

2.2 Login as a local user with administration rights.
You need to be logged in in order to download the metadata file.

2.3 Download the metadata file.
Browse to the directory phixflow/saml/metadata, for example https://myhost.com/phixflow/saml/metadata.

2.4 Save the resulting metadata file.

Step 3 Install the Service Provider Metadata in the Identity Provider

How you do this is specific to the Identity Provider. For a Windows Server ADFS identity provider, follow these steps:

3.1 Log into the Windows ADFS Server.

3.2 Run the command mmc.exe to open the windows server management console.

3.3 Go to File → Add/Remove Snap in and add ADFS.

3.4 In the tree view displayed on the left, open Relying Party Trusts.

3.5 In the menu on the right, click Add Relying Party Trust.

3.6 Select Claims aware.

3.7 Select import data about the relying party from a file.

3.8 Browse to the service provider metadata xml file created in the previous step and select it.

3.9 Name the new relying party.

3.10 Select Access Control Policy: Permit Everyone.

On the final screen you can review the details of the relying party that will be created. You should not have to edit any of this information.

A new entry will appear in the list of relying party trusts on the mmc.exe management console.

Step 4 Configure Attribute Mapping on the Identity Provider

How you do this is specific to the Identity Provider.

The following steps are for a Windows Server ADFS identity provider. You must complete these steps immediately after installing the service provider metadata in the identity provider.

4.1 Select the relying party trust that has been created.

4.2 In the menu on the right, click Edit Claim Issuance Policy to open an empty Issuance Transform Rules list.

4.3 Click on Add Rule.

4.4 For the claim rule template, select Send LDAP Attributes as Claims.

4.5 On the next screen, give the claim rule a name, and select Active Directory as the attribute store.

4.6 Map the LDAP Attributes to Outgoing Claim Types. This mapping determines which user fields are sent from the Active Directory server to PhixFlow.

You must map the User-Principal-Name, which is the user name. Without this PhixFlow will reject the SAML login request.
You must map Token-Groups - Unqualified Names to Role, as shown in the screenshot below. The mapping for user groups is mandatory for the SAML login request.
Map any remaining LDAP attributes that you require. You may need to test different mappings, to identify what information is sent to the PhixFlow server.

When you map an LDAP Attribute to an Outgoing Claim Type, enter a Name ID. You can specify any name for an outgoing claim type. However, for clarity the name should be similar to the LDAP Attribute.

ADFS SAML Rule Mapping Image Removed

Tip
When you configure the attribute mapping on PhixFlow (the service provider) in Step 5, below, remember to match the domain to the service provider domain.

Step 5 Configure Attribute Map in PhixFlow (Service Provider)

As part of the SAML single sign-on process, the identity provider sends details of the user who is logging in as a set of name/value pairs. An attribute map defines how PhixFlow maps the identity provider's attribute names to the names required by PhixFlow.

Each of the Outgoing Claim Types has a unique URN, which can be found under ADFS → Service → Claim Descriptions. For example Name ID has a URN claim type of http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier. Add this claim type to the attribute mapping in phixflow-login.xml.

ADFS Claim Types Image Removed

Alternatively, look in the phixflow.log file to see what attributes are being sent; see Log Files.

Info
Turn on debug logging in logback.xml for com.accipia.centerview.util.security. The log file will show the attributes and values that are available. Even if you choose to use the list of claim types as a guide, this logging can be useful diagnostic information.

As long as you have correctly mapped the username and domain and the rest of the SAML setup is correct, you should see lines like these:

Code Block

2019-08-21 16:28:38,839 DEBUG [http-nio-8080-exec-3] o.s.s.s.w.WebSSOProfileConsumerImpl [WebSSOProfileConsumerImpl.java:237] Including attribute http://schemas.microsoft.com/ws/2008/06/identity/claims/role from assertion _8c9686b7-9029

The URN is the same as the URN given in the list of Claim Descriptions.

Back in phixflow-login.xml, find the attribute map section:

Code Block

language	xml

	<!-- map external user attribute names to saml response attribute names -->
	<bean id="example1SamlAttributeMap"	class="com.accipia.centerview.util.security.UserDetailsMapper" >
		<!-- this will be used to mark external users in the database as from this login provider / domain -->
		<property name="domain" value="mysaml.org" />
		<property name="username" value="urn:oid:0.9.2342.19200300.100.1.1" />
		<property name="firstname" value="urn:oid:2.5.4.42" />
		<property name="lastname" value="urn:oid:2.5.4.4" />
		<property name="phonenumber" value="urn:oid:2.5.4.20" />
		<property name="company" value="urn:oid:2.5.4.10" />
		<property name="department" value="urn:oid:2.5.4.11" />
		<property name="email" value="urn:oid:0.9.2342.19200300.100.1.3" />
		<property name="groups" value="1.2.840.113556.1.2.613" />
	</bean>

Create a new map by copying the example and changing it's id.

Change the domain to the value you want to be displayed as the domain for any users who login using SAML (it is hard-coded).

Change the property values to match the attributes supplied by the identity provider.

Step 6 Configure SAML User Details Service

The user details service is responsible for mapping the working out which attribute map to use, based on the identity provider's entity id.

Find the following section:

Code Block

language	xml

	<bean id="samlUserDetailsService"
		class="com.accipia.centerview.util.security.ResolvingSAMLUserDetailsService" >
		<property name="externalUserLoader" ref="externalUserLoader" />
		<property name="mappers">
			<util:map>
				<!-- the key is the identity provider's entity id: add an entry for each external identity-provider -->
				<entry key="exampleEntityId">
					<ref bean="example1SamlAttributeMap" />
				</entry>
			</util:map>
		</property>
	</bean>

Change exampleEntityId to match the value of entityID sent by the identity provider. This should be in the metadata provided, but you can also see it by turning on logging as in the previous section.

Change example1SamlAttributeMap to reflect the id of the attribute map created in the previous section.

Step 7 Configure External Groups

Each PhixFlow User Group defines a list of external group names which grant access rights (the rights to view, activate, change, delete objects) conferred by membership of those user groups. For a user to login using SAML, he must be in at least one external group listed on one user group.

System Configuration also defines a list of external login groups. For a user to login, either the list must be empty or the user must be in at least one of the groups listed.

A user who successfully logs in using SAML / Single Sign-on is considered a member of each User Group, and has the access rights of that User Group, if he is a member of any of the User Group's External Login Groups.

External group names may contain references to the current instance name as '{instance}' e.g. 'ADMIN_{instance}'. This allow groups to be moved from one instance to another and for each instance to use it's own set of external group names.

See Configure Groups for External Login for how to configure External Login groups.



    <!-- context provider when not behind reverse proxy -->
    <!-- <bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderImpl" /> -->

1.8. Configure the Metadata Generator

To support a SAML exchange, each party generates metadata to describe how to connect to it. That metadata must be installed into the other party before any connection can be made.

The metadata generator generates the PhixFlow server's metadata based on configuration parameters and data available when a user tries to connect to it.

Edit the metadataGeneratorFilter section of phixflow-login.xml and set:

entityId to a value that globally identifies the PhixFlow instance - https://[domain]/[webapp], e.g. https://phixflow.example.com/phixflow
entityBaseURL to a the URL normally used to start PhixFlow - https://[domain]/[webapp], e.g. https://phixflow.example.com/phixflow

Note
If PhixFlow is running behind a reverse proxy, this should be the public URL, not the internal URL which only the proxy sees.

This is the metadataGeneratorFilter section before configuration:

Code Block

	<!-- filter that generates metadata based on configured properties -->
	<bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
		<constructor-arg>
			<bean class="org.springframework.security.saml.metadata.MetadataGenerator"> 
				<property name="entityId" value="urn:test:phixflow:phixflow" />
				<property name="entityBaseURL" value="https://myhostname:myport/phixflow" />
				<property name="extendedMetadata">
					<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
						<property name="idpDiscoveryEnabled" value="false" />
					</bean>
				</property>
			</bean>
		</constructor-arg> 
	</bean>

Configure the Identity-Provider Metadata Provider

The identity provider metadata provider defines how PhixFlow installs and handles the identity-provider's metadata - in our case, the Federation Metadata XML downloaded from AAD in a previous section on this page.

Save the identity provider's metadata file in a convenient folder. You can specify a path using:
- either classpath:dir1/file
  This refers to a file in directory dir1 under the webapp's classpath. This is ambiguous as it can mean webapp/WEB-INF/classes/dir1 and tomcat/lib/dir1.
- or file:/dir1/file
  This refers to the top-level directory /dir1. Without the forward slash / it refers to dir1 under the current directory, which is normally the Tomcat home directory.
Edit the metadata provider section of phixflow-login.xml.
- Change metadata/idp-metadata.xml to the location of the identity provider's metadata file.
- Update metadataTrustCheck to false

This is the metadata provider section of phixflow-login.xml.

Code Block

language	xml

	<!-- file-base identity-provider (idp) metadata provider - this defines the metadata for a single identity provider -->
	<bean id="idpFileMetadataProvider" class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
		<constructor-arg>
				<bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
					<constructor-arg>
						<value type="java.io.File">classpath:metadata/idp-metadata.xml</value>
					</constructor-arg>
					<property name="parserPool" ref="parserPool" />
				</bean>
		</constructor-arg>
		<constructor-arg>
			<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
				<!-- add properties to extend the metadata -->
				<!-- see https://docs.spring.io/spring-security-saml/docs/current/reference/html/configuration-metadata.html for values -->
				<property name="local" value="false" />
			</bean>
		</constructor-arg>
		<property name="metadataTrustCheck" value="true" />
	</bean>

A resulting example configuration:

Code Block

	<!-- file-base identity-provider (idp) metadata provider - this defines the metadata for a single identity provider -->
	<bean id="idpFileMetadataProvider" class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
		<constructor-arg>
				<bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
					<constructor-arg>
						<value type="java.io.File">file:/opt/phixflow/secure/saml/idp-metadata.xml</value>
					</constructor-arg>
					<property name="parserPool" ref="parserPool" />
				</bean>
		</constructor-arg>
		<constructor-arg>
			<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
				<!-- add properties to extend the metadata -->
				<!-- see https://docs.spring.io/spring-security-saml/docs/current/reference/html/configuration-metadata.html for values -->
				<property name="local" value="false" />
			</bean>
		</constructor-arg>
		<property name="metadataTrustCheck" value="false" />
	</bean>

Configure SAML User Details Service

For mixed mode

Mixed mode is when AAD performs the authentication, and PhixFlow performs the authorisation.

For this step you will need the Azure AD Identifier, this was captured earlier during the Azure AD set up
In phixflow-login.xml, find the samlUserDetailsService bean:

Code Block

        <!-- The following beans are for configuring SAML login -->
        <bean id="samlUserDetailsService"
                class="com.accipia.centerview.util.security.ResolvingSAMLUserDetailsService" >
                <property name="externalUserLoader" ref="externalUserLoader" />
                <property name="mappers">
                        <util:map>
                                <!-- the key is the identity provider's entity id: add an entry for each external identity-provider -->
                                <!--
                                <entry key="exampleEntityId">
                                        <ref bean="example1SamlAttributeMap" />
                                </entry>
                                -->
                        </util:map>
                </property>
        </bean>

Uncomment the entry key section
Update exampleEntityId to the value of Azure AD Identifier
Ensure the entry is pointing to exampleAuthenticationOnlySamlAttributeMap

A resulting example samlUserDetailsService bean:

Code Block

        <!-- The following beans are for configuring SAML login -->
        <bean id="samlUserDetailsService"
                class="com.accipia.centerview.util.security.ResolvingSAMLUserDetailsService" >
                <property name="externalUserLoader" ref="externalUserLoader" />
                <property name="mappers">
                        <util:map>
                                <!-- the key is the identity provider's entity id: add an entry for each external identity-provider -->
                                <entry key="https://sts.windows.net/0597bXXXXXXXXXXXXXXXXXXXXXXXX/">
                                        <ref bean="exampleAuthenticationOnlySamlAttributeMap" />
                                </entry>
                        </util:map>
                </property>
        </bean>

Update the exampleAuthenticationOnlySamlAttributeMap bean:
- Replace the contents of the bean with the contents below
- Update the property domain to reflect the domain of your identity provider, i.e. of your Microsoft tenant (technically, this is the value that will be displayed as the domain for any users who login using SAML; but you are strongly recommended to make this the domain of your identity provider)

Code Block

        <bean id="exampleAuthenticationOnlySamlAttributeMap"    class="com.accipia.centerview.util.security.UserDetailsMapper" >
                <property name="domain" value="example.com" />
                <property name="username" value="nameid" />
                <property name="authenticationOnly" value="true" />
                <property name="globalLogout" value="true" />
        </bean>

For mapped group mode

In mapped group mode, you rely on the groups a user is assigned to in AAD to allow them access to certain PhixFlow apps and features. I.e. AAD is responsible for both authentication and authorisation of users.

Set up mapped groups in PhixFlow

See Configure Groups for External Login. To complete this you will need the names or IDs of groups that are being supplied by AAD via the SAML exchange. These can be obtained directly from AAD but see also https://phixflow.atlassian.net/wiki/spaces/HELP100/pages/9106732489/Configure+AAD+Integration+via+SAML#Discovering-details---claims-values-and-group-names%2F-IDs for a handy way of discovering these.

For this step you will need the Azure AD Identifier, this was captured earlier during the Azure AD set up
In phixflow-login.xml, find the samlUserDetailsService bean:

Code Block

        <!-- The following beans are for configuring SAML login -->
        <bean id="samlUserDetailsService"
                class="com.accipia.centerview.util.security.ResolvingSAMLUserDetailsService" >
                <property name="externalUserLoader" ref="externalUserLoader" />
                <property name="mappers">
                        <util:map>
                                <!-- the key is the identity provider's entity id: add an entry for each external identity-provider -->
                                <!--
                                <entry key="exampleEntityId">
                                        <ref bean="example1SamlAttributeMap" />
                                </entry>
                                -->
                        </util:map>
                </property>
        </bean>

Uncomment the entry key section
Update exampleEntityId to the value of Azure AD Identifier
(Note that you can update the value example1SamlAttributeMap or use this section as a template to create a new mapping with a different name, and rename the reference to this bean in the step below to match this, but in these instructions we have assumed that you will use the default names)

Find the example1SamlAttributeMap bean:

Code Block

<!-- map external user attribute names to saml response attribute names -->
<bean id="example1SamlAttributeMap"  class="com.accipia.centerview.util.security.UserDetailsMapper" >
    <!-- this will be used to mark external users in the database as from this login provider / domain -->
    <property name="domain" value="mysaml.org" />
    <property name="username" value="urn:oid:0.9.2342.19200300.100.1.1" />
    <property name="firstname" value="urn:oid:2.5.4.42" />
    <property name="lastname" value="urn:oid:2.5.4.4" />
    <property name="phonenumber" value="urn:oid:2.5.4.20" />
    <property name="company" value="urn:oid:2.5.4.10" />
    <property name="department" value="urn:oid:2.5.4.11" />
    <property name="email" value="urn:oid:0.9.2342.19200300.100.1.3" />
    <property name="groups" value="1.2.840.113556.1.2.613" />
</bean>

There are a number of ways of updating this attribute map, this is a flexible mechanism for specifying the format of token claims, but for the remainder of this configuration we supply a recommended configuration that should suit the majority of PhixFlow instances.

Update the example1SamlAttributeMap bean:
- Replace the contents of the bean with the contents below
- Update the property domain to reflect the domain of your identity provider, i.e. of your Microsoft tenant (technically, this is the value that will be displayed as the domain for any users who login using SAML; but you are strongly recommended to make this the domain of your identity provider)

Code Block

        <!-- map external user attribute names to saml response attribute names -->
        <bean id="example1SamlAttributeMap"     class="com.accipia.centerview.util.security.UserDetailsMapper" >
                <!-- this will be used to mark external users in the database as from this login provider / domain -->
                <property name="domain" value="phixflow.org" />
                <property name="username" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
                <property name="firstname" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" />
                <property name="lastname" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" />
                <property name="email" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
                <property name="groups" value="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"/>
                <!-- set below property to true to enable single/global logout -->
                <property name="globalLogout" value="false" />
        </bean>

Discovering details - claims values and group names/ IDs

There are various ways of getting details of the claims, and the names/ IDs of groups to be mapped (from AAD), but in many cases it is easiest to see what is being provided via SAML. To do this:

Apply the debug settings Option 1 (as described below)
Attempt a login with a test user that you believe has been set up correctly
Examine the server log file

In the example below, in the groups claim, Group ID has been set as the source attribute.

Code Block

2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.ResolvingSAMLUserDetailsService [ResolvingSAMLUserDetailsService.java:43] resolved entityId 'https://sts.windows.net/ac26b444-992c-45e0-9963-d5640855a490/' to realm 'phixflow.org'
2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:113] credentials: org.springframework.security.saml.SAMLCredential@5a65288c
2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/identity/claims/tenantid': 'ac26b444-992c-45e0-9963-d5640855a490'
2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/identity/claims/objectidentifier': '061fe582-ed14-4ce6-82e7-f59137d07211'
2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/identity/claims/displayname': 'Test User'
2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups': '65831f5a-06fa-4245-92f0-ad2252b79c04'
2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups': 'c06755b1-cfd5-4abf-9177-d497a463898f'
2023-09-08 10:41:38,163 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups': '91f46287-da2d-41b2-a145-1a3f476a969e'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/identity/claims/identityprovider': 'https://sts.windows.net/ac26b444-992c-45e0-9963-d5640855a490/'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/claims/authnmethodsreferences': 'http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/claims/authnmethodsreferences': 'http://schemas.microsoft.com/claims/multipleauthn'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/ws/2008/06/identity/claims/wids': '34f948d8-759b-4f63-9427-79b007402544'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.microsoft.com/ws/2008/06/identity/claims/wids': '290f8b04-e964-48ac-9063-c4fc669defb1'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname': 'Test'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname': 'User'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress': 'test.user@example.com'
2023-09-08 10:41:38,166 DEBUG [http-nio-8080-exec-1] c.a.c.u.s.SAMLExternalUserSource [SAMLExternalUserSource.java:123] attr 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name': 'test.user@example.com'

Other settings for SAML User Details Service

You can optionally add property name attributes to configure:

single (global) logout
By default, PhixFlow uses local logout. When a user logs out the PhixFlow session is terminated but
- the SAML identity provider is not notified
- the user is not logged out of their identity provider session.
Alternatively, single logout terminates the PhixFlow session and logs out of the identity provider. Depending on your identity provider configuration, this may include terminating sessions with other identity providers. To apply single logout to all users in this domain, add the line:
<property name="globalLogout" value="true" />

Troubleshooting

When troubleshooting the configuration, you can include additional diagnostics information in logs, by adding lines to logback.xml.

Option 1: more debug information

Code Block
<logger name="org.springframework.security" level="error" /> <logger name="com.accipia.centerview.util.security" level="debug" />

Option 2: full debug information

Code Block

#Log information about the SAML login framework
<logger name="org.springframework.security" level="error" />
<logger name="com.accipia.centerview.util.security" level="debug" />
<logger name="org.springframework.security.saml" level = "debug" />
<logger name="org.opensaml" level="debug" />

Tip
With additional debug information, PhixFlow will generate very large log files. Remember to remove these lines when your configuration is working and you no longer need the debug information. For information about accessing logs, see Server Log Files.

Live Search
spaceKey @self
additional none
placeholder Search all help pages
type page

Panel

borderColor	#00374F
titleColor	white
titleBGColor	#00374F
borderStyle	solid
title	Sections on this page

Table of Contents

maxLevel	3
indent	12px
style	none

Version	Old Version 36	New Version Current
Changes made by	Gary Parden	Zoe Baldwin
Saved on	Sept 19, 2019	Nov 24, 2023

Page Comparison

Versions Compared

Key

Overview

Step 1 Configure phixflow-login.xml

1.1 Specify the Authentication Manager

1.2. Configure Login Forms

1.3. Enable SAML Beans

1.4. Configure the keyManager

1.5. Configure the Context Provider

Overview

Prerequisites

Adding an Unlisted (Non-Gallery) Application in Azure

Configuring SAML-Based Single Sign-On to Non-Gallery Applications via Azure AD (Identity Provider)

Add users/groups to the enterprise application

Configuring PhixFlow (Service Provider)

Configure phixflow-login.xml

Specify the Authentication Manager

Set up User Accounts

Configure Login Forms

Enable a Cookie Filter

Enable SAML Beans

Create a certificate and configure the keyManager

1.6. Configure the Metadata Generator

1.7. Configure the Context Provider

Step 2 Generate Service Provider Metadata

Step 3 Install the Service Provider Metadata in the Identity Provider

Step 4 Configure Attribute Mapping on the Identity Provider

Step 5 Configure Attribute Map in PhixFlow (Service Provider)

Step 6 Configure SAML User Details Service

Step 7 Configure External Groups

1.8. Configure the Metadata Generator

Configure the Identity-Provider Metadata Provider

Configure SAML User Details Service

For mixed mode

For mapped group mode

Set up mapped groups in PhixFlow

Complete configuration of phixflow-login.xml to support mapped groups

Discovering details - claims values and group names/ IDs

Other settings for SAML User Details Service

Troubleshooting

Live SearchspaceKey@selfadditionalnoneplaceholderSearch all help pagestypepage

Live Search
spaceKey @self
additional none
placeholder Search all help pages
type page