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.

Prerequisites

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

  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 like in the following screenshot:

  

  
  

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

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

  

  
  

• Click Add user:

  

  
  

• Assign users to the application as appropriate 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>

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.

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:

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

Remove them or comment them out:

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

Find these lines, near the end of the file:

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

and remove them or comment them out:

	<!-- 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.

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

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

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:

	<!-- 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="83dSKFnck130xSLDjzjd9Y" />
		<constructor-arg>
			<map>
				<!-- 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>

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.

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

Find these lines:

	<!-- Context Provider -->

	<!-- context provider when behind reverse proxy -->
	<!-- see https://docs.spring.io/autorepo/docs/spring-security-saml/1.0.x/reference/html/configuration-advanced.html -->
	<!--  
	<bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderLB">
		<property name="scheme" value="https"/>
		<property name="serverName" value="www.myserver.com"/>
		<property name="serverPort" value="443"/>
		<property name="includeServerPortInRequestURL" value="false"/>
		<property name="contextPath" value="/spring-security-saml2-sample"/>
	</bean>
	-->

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

Comment out the following contextProvider bean that applies to installations not running behind a reverse proxy.

Example of Context Provider configuration (preceding comments omitted):

	<bean id="contextProvider" class="org.springframework.security.saml.context.SAMLContextProviderLB">
		<property name="scheme" value="https"/>
		<property name="serverName" value="myserver.com"/>
		<property name="serverPort" value="443"/>
		<property name="includeServerPortInRequestURL" value="false"/>
		<property name="contextPath" value="/phixflow"/>
	</bean>

    <!-- 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 - in our case https://[subdomain].phixflow.com/[webapp]
• entityBaseURL to a the URL normally used to start PhixFlow - in our case https://[subdomain].phixflow.com/[webapp]

This is the metadataGeneratorFilter section before configuration:

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