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

Click on New application
Select Create your own application and then radio button Integrate any other application you don't find in the gallery (Non-gallery)
Enter a suitable name to represent the application, e.g. example-phixflow-prod, then click Create
The application Overview page will then appear
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

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

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:

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
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:
Click the Unique User Identifier (Name ID) attribute and set Source to Transformation on the claim page. A configuration window will open up:

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

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

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)

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:
In the third step (SAML Certificates), there is an option to download the Federation Metadata XML. Click Download:

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

Add users/groups to the enterprise application

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

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)

Configure phixflow-login.xml

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:

	<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):

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

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:

<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:

Remove them or comment them out:

Find these lines, near the end of the file:

and remove them or comment them out:

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

E.g.

Linux

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.