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.

Prerequisites

Before configuring SAML integration you must set Tomcat:

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

Adding an Unlisted (Non-Gallery) Application in Azure

Log into the Azure portal and navigate to the

"

Enterprise Applications

"

blade

.

Image Modified
Click on

"

New application

":

Image Modified

(For reference, you are creating a “Non-gallery application”, but this terminology doesn’t feature in the creation process)

Select

“

Create your own application

”

and then radio button

“

Integrate any other

…”)

application you don't find in the gallery (Non-gallery)Image Modified
Enter a suitable name to represent the application, e.g.

"PhixFlow Ops"

example-phixflow-prod, then click

"

Create

":

The application

"

Overview

"

page will then appear

when it has been created:

Image Modified
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?

"

1. is set to

"yes". This

1. Yes - this determines whether users assigned to the application can sign in

.

"

1. User assignment required?

"

1. is set to

"yes". This

1. Yes - this determines whether users who aren't assigned to the application can sign in

.

"

1. Visible to users?

"

1. is set to

"yes". This

1. Yes - this determines whether users assigned to an app can see it in the access panel and

O365

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

"

if setting up for the first time

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 Removed

Image Added
Click the pencil icon in the top left corner of the first step and enter the following:
1. Identifier (Entity ID): https://[

subdomainphixflow.com

1. domain]

.

1. /[webapp], e.g. https://

ops

1. phixflow.

phixflow

1. example.com/phixflow
Reply URL (Assertion Consumer Service URL): https://[

subdomain].phixflow.com/[webapp]

domain]/[webapp]/saml/SSO, e.g. https://phixflow.example.com/phixflow/saml/SSO

Image Removed

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 Modified
Click the Unique User Identifier (Name ID) attribute and set Source to Transformation on the claim page. A configuration window should open up like in the following screenshot:
Image Modified
Set Transformation to ExtractMailPrefix() and Parameter to user.userprincipalname. Press Add, then press Save:
Image Modified
Click Add a group claim:
Image Modified
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:
Image Modified
The resulting list of attributes and claims should look similar to the following:
Image Modified
In the third step (SAML Signing Certificate), there is an option to download the Federation Metadata XML. Click Download:
Image Modified
Upload the downloaded XML file to the server that is hosting the PhixFlow application using FileZilla or similar.
Navigate to the Users and groups section of the Enterprise Application:
Image Modified
Click Add user:
Image Modified
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)

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

For mixed users in your SAML authentication system, 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

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/keystore.jks

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

To complete the command:

Enter a keystore password when prompted - keystorePasswd
Enter information about your company, contact name, etc - this information will be displayed when users access PhixFlow
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.

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

Code Block

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

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="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>

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.

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

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

Code Block

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

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. 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 section of phixflow-login.xml.
Change metadata/idp-metadata.xml to the location of the identity provider's metadata file.

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>

Complete configuration

Go to the Azure portal and navigate to the "Enterprise Applications" blade. Under the "Manage" section, select "Single sign-on". Copy the value for "Azure AD Identifier" in step 4 (it should be of the form https://sts.windows.net/[id_string]/):

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="">
				<ref bean="exampleAuthenticationOnlySamlAttributeMap" />
			</entry>
		</util:map>
	</property>
</bean>

Set entry key to the "Azure AD Identifier" value from step 5 above.
Ensure the entry is pointing to exampleAuthenticationOnlySamlAttributeMap.
Ensure the exampleAuthenticationOnlySamlAttributeMap bean looks like the following:

Code Block

<!-- map the domain name and set as authentication only to use local user groups -->
<bean id="exampleAuthenticationOnlySamlAttributeMap"	class="com.accipia.centerview.util.security.UserDetailsMapper" >
	<property name="domain" value="phixflow.com" />
    <property name="username" value="nameid" />
	<property name="authenticationOnly" value="true" />
</bean>

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

Versions Compared

Old Version 60

New Version 61

Key

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)

Configuring PhixFlow (Service Provider)

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.7. Configure the Context Provider

1.8. Configure the Metadata Generator

Configure the Identity-Provider Metadata Provider

Complete configuration

Troubleshooting

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

Page Comparison

Versions Compared

Old Version 60

New Version 61

Key

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)

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.7. Configure the Context Provider

1.8. Configure the Metadata Generator

Configure the Identity-Provider Metadata Provider

Complete configuration

Troubleshooting

Live SearchspaceKey@selfadditionalnoneplaceholderSearch all help pagestypepage

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