You can set up access to PhixFlow either through PhixFlow Users Managing the User List, by integrating with your Active Directory infrastructure, or with SAML. If you integrate with SAML, Access Control is maintained by mapping Active Directory Groups to PhixFlow User Groups, as described below. By using the SAML integration users will be redirected to a chosen identity provider page where they will enter their username and password. If they are successfully authenticated they will then be redirected to PhixFlow and logged in.

This page describes how to integrate PhixFlow with SAML: Table of ContentsmaxLevel1.

Insert excerpt

	_admin_user_topic
	_admin_user_topic
nopanel	true

Configuration details for SAML are configured in the file phixflow-SAMLlogin.xml, under [tomcat root]/webapps/phixflow/WEB-INF/classes. When you first install PhixFlow, you probably created a copy of this file by simply copying the example file phixflow-login.xml.example (see Install PhixFlow Webapp).

Create SAML reference

To create a reference to SAML, update the section in the example file to:

Code Block

language	xml

Configure the authentication manager

Add the SAML auth provider (which is already defined) to the authenticationProvider.

Find this section of the file:

Code Block

	<security:authentication-manager alias="authenticationManager">
		<!-- exampletest ofauthentication aprovider, SAMLleave authenticationcommented providerout 		-->
		<!-- <security:authentication-provider ref="samlAuthenticationProvidertestAuthProvider"/>

Add key store details

In order to SAML A keystore must be included at [tomcat root]/webapps/phixflow/WEB-INF/classes/keystore/<<youtkeystorename.jks>>. Instructions for creating a keystore can be seen at Configure Tomcat For HTTPS. The configuration files included assume that the alias of the key is "PhixflowSAML", if you wish to use another alias you will have to replace all instances of "PhixflowSAML" with your alias. Below is an example of a keystore:

Code Block

language	xml

    /> -->

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

		<!-- AnAdd Examplean ofActive aDirectory KeyStoreAuthentication FileProvider -->below 	this 	<bean id="keyManager"
		class="org.springframework.security.saml.key.JKSKeyManager">
		<constructor-arg
			value="classpath:keystore/samlKeystore.jksline; uncomment if using active directory integration -->
		<!-- <security:authentication-provider ref="exampleActiveDirectoryAuthProvider" /> -->

		<constructor-arg type="java.lang.String"
			value="<<KeyStorePassword>>" /<!-- Add SAML Authentication Provider; uncomment if using saml / single sign-on -->
		<constructor<!--arg>
			<map>
				<entry key="PhixflowSAML" value="<<KeyPassword>>" />
			</map>
		</constructor-arg>
		<constructor-arg type="java.lang.String"
			value="PhixflowSAML <security:authentication-provider ref="samlAuthProvider"/> -->
	</security:authentication-manager>

... and 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" />
	</bean>

For the most basic configuration just replace the "/samlKeystore.jks" with your keystore, "<<KeyStorePassword>>" with the password to the keystore and then "<<KeyPassword>>" with the password for the key.

Metadata generator

In order to connect to your identity provider PhixFlow must be configured to contain service provider metadata. The configuration file contains all the tools needed in order to generate a metadata file. It is recommended to follow this procedure to generate your metadata then save the resulting xml in a file called "sp-metadata.xml" in the folder at [tomcat root]/webapps/phixflow/WEB-INF/classes/metadata. In order to configure the metadata generator two things need to be customised.

Firstly replace the value of the entityId with something unique so that the service provider will correctly be associated with only you.

Code Block

language	xml

  <property name="entityId"	
			value="urn:test:phixflow:phixflow" />

Secondly replace the values under entityBaseURL to point at your tomcat configuration.

Code Block

language	xml

<property name="entityBaseURL"
					value="http(s)://<<hostname>>:<<port>>/Phixflow" />

For example if you are using the default tomcat configuration :

Code Block

language	xml

<property name="entityBaseURL"
					value="http://localhost:8081/Phixflow" />

or alternatively using a tomcat configured for HTTPS:

Code Block

language	xml

<property name="entityBaseURL"
					value="https://localhost:8443/Phixflow" />

Metadata configuration

The next step is to configure PhixFlow so that it knows where to look for both identity provider and service provider metadata. First we look at identity provider metadata:

With the default configuration the identity provider metadata is saved as a file under the metadata folder named "idp-metadata.xml". If you wish to use a different file name just change it here.

Code Block

language	xml

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

Next comes the service provider metadata. If you are using the metadata generator leave this next section commented out as if you do not PhixFlow will not start as it will be looking for a file that does not exist. Below is a completed service provider bean which will be broken down in more detail lower down.

Code Block

language	xml

	<bean
					class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
					<constructor-arg>
						<bean
							class="org.opensaml.saml2.metadata.provider.ResourceBackedMetadataProvider">
							<constructor-arg>
								<bean class="java.util.Timer" />
							</constructor-arg>
							<constructor-arg>
								<bean class="org.opensaml.util.resource.ClasspathResource">
									<constructor-arg value="/metadata/sp-metadata.xml" />
								</bean>
							</constructor-arg>
							<property name="parserPool" ref="parserPool" />
						</bean>
					</constructor-arg>
					<constructor-arg>
						<bean
							class="org.springframework.security.saml.metadata.ExtendedMetadata">
							<property name="local" value="true" />
							<property name="alias"
								value="urn:test:phixflow:phixflow" />
							<property name="signingKey" value="PhixflowSAML" />
							<property name="encryptionKey" value="PhixflowSAML" />

						</bean>
					</constructor-arg>
				</bean>

The first configurable part of the service provider metadata is the file name. By default this is expecting a file named "sp-metadata.xml" under the metadata folder. If you wish to use another file name change it here :

Code Block

language	xml

		<constructor-arg value="/metadata/sp-metadata.xml" />

Next we have the Extended metadata configuration. For the simplest setup all that needs changing here is the alias needs to be updated to the entity ID that you specified earlier. If you are using the recommended Key name of "PhixflowSAML" then no further configuration is required. If you are not using this key name then you will have to replace the PhixflowSAML with your keyname under the "signingKey" and "encryptionKey" sections.

Code Block

language	xml

	<!-- The following sections must be uncommented to enable SAML Login -->
	<!--

	<security:http entry-point-ref="samlEntryPoint"
		pattern="/saml/**" use-expressions="false">
		<security:intercept-url pattern="/**" access="ROLE_USER" />
		<security:custom-filter	after="BASIC_AUTH_FILTER" ref="samlFilter" />
	</security:http>
	
	<import resource="phixflow-SAML.xml/>
	-->

After this there is only one remaining section which contains a line that needs to be included when you wish to generate your metadata, but commented out if you do not wish to generate your own metadata. This line is as follows :

Code Block

language	xml

<!--<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>-->

so to generate your metadata the configuration should look like

Code Block

language	xml

 	<!-- with the exception of the metageneratorfilter line the following must be uncommented to enable SAML login -->
	<security:http entry-point-ref="samlEntryPoint"
		pattern="/SAMLLogin" use-expressions="false">
		<security:intercept-url pattern="/**"
			access="ROLE_USER" />
		<security:custom-filter
			after="BASIC_AUTH_FILTER" ref="samlFilter" />
	<!--  uncomment the line below to generate your service provider metadata -->		
	<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>
	</security:http>

and if you do not need to generate your metadata the configuration should look like

Code Block

language	xml

 	<!-- with the exception of the metageneratorfilter line the following must be uncommented to enable SAML login -->
	<security:http entry-point-ref="samlEntryPoint"
		pattern="/SAMLLogin" use-expressions="false">
		<security:intercept-url pattern="/**"
			access="ROLE_USER" />
		<security:custom-filter
			after="BASIC_AUTH_FILTER" ref="samlFilter" />
	<!--  uncomment the line below to generate your service provider metadata -->		
	<!--<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>-->
	</security:http>

Other configuration

After this in order to enable SAML all that is required is to uncomment the following sections with a few exceptions. First uncomment all of the text listed below:

Code Block

language	xml

		<!--

	<security:http entry-point-ref="samlEntryPoint"
		pattern="/saml/**" use-expressions="false">
		<security:intercept-url pattern="/**"
			access="ROLE_USER" />

		<security:custom-filter
			after="BASIC_AUTH_FILTER" ref="samlFilter" />

	</security:http>
	
		<import resource="phixflow-SAML.xml/>
	-->

Metadata Generation

After completing this initial setup. It's time to generate the metadata. To do this setup the login configuration form to have a log in with SAML button and click it. You should be redirected to your identity provider and rejected, but your metadata will be generated by this step. Next log in as a local user then go to <<yourhost>>/Phixflow/saml/metdata in order to download an XML file of your metadata.This will need to be given to your identity provider to log in. In order to simplify configuration it is recommended to save this as metadata/sp-metadata.xml

At this point please refer to the Phixflow Active Directory Setup section for more information on how to connect your identity provider provided groups to PhixFlow groups. The "default domain" section is not needed.

Logging in as a SAML user

Image Removed

...

security:authentication-manager>

We recommend that you do not remove the localAuthProvider, and that you retain a local administrator user so that you can still login in the event of a problem with the SAML integration.

Configure Login Forms

Login forms define the login options (local, single sign-on, active directory) to be presented on the login screen when a user opens the PhixFlow URL. 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 how to configure and use login forms.

Enable SAML beans

These 2 blocks serve to disable the bulk of the file for the normal case where SAML is not required.

Find these lines and remove them or comment them out:

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

E.g.

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

Find these lines, near the end of the file, and remove them or comment them out:

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

E.g.

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

Configure the keyManager

The SAML integration requires one or more public/private keys. These are stored in a Java keystore file, and the information needed to access that file is configured in the keyManager.

Instructions for creating a keystore can be found here: Configure Tomcat For HTTPS.

Below is an example of a keystore:

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>

For the most basic configuration just replace the "file:/.../keystore.jks" with your keystore, "KeyStorePassword" with your keystore password and "keyPassword" with your key password.

Warning
For security reasons, access to phixflow-login.xml and to keystore.jks should be restricted so that they are read-only to the tomcat user / account and not readable by regular users.

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 the rest of 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.

Find this section:

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

Edit this by deleting the original contextProvider, uncommenting the reverse proxy version, and changing the serverName, serverPort and contextPath to match the public view.

It should look something like this (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>

Configure the Metadata Generator

The core of the interaction between a SAML identity provider (e.g. Active Directory Federation Services) and a SAML Service Provider (e.g. PhixFlow) relies on the exchange of metadata. Each party generates metadata which describes how to connect to it, and 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.

Find the metadata generator section:

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>

Then

change the entityId value to something that globally identifies the PhixFlow instance
change the entityBaseURL value to 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.

Configure the Identity-Provider Metadata Provider

The identity provider metadata provider defines how we have installed the identity-provider's metadata and how we should handle it e.g. we can control whether to enable or disable additional security checks.

First, install the identity provider's metadata file in a convenient folder. In the example, we assume that it will be in the metadata directory, which is along side the phixflow-login.xml file, but you can also use a file: reference (see below) to place the metadata in an unrelated directory.

Find this section of the file:

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>

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

Info

title	classpath: and file:

You can refer to a file as classpath:dir/file or as file:dir/file.

classpath:dir1/file2 refers to a file in directory dir1 under the webapp's classpath; this can mean $webapp/WEB-INF/classes/dir1, but could also mean $tomcat/lib/dir1.

file:/dir1 refers to the top-level directory /dir1; without the '/' it refers to dir1 under the current directory (which is normally the tomcat home directory).

Generate Service Provider metadata

You are now in a position to generate metadata for the PhixFlow server.

Do the following:

Attempt to login using SAML / Single Sign-on.

This will fail as you have not yet installed PhixFlow's metadata in the identity provider, but the attempt will cause the metadata to be generated.

Login as a local user with admin rights

You need to be logged in in order to download the metadata file.

Download the metadata file

Browse to $phixflow/saml/metadata

e.g.

https://myhost.com/phixflow/saml/metadata

Save the resulting metadata file.

Install the Service Provider Metadata in the Identity Provider

How you do this is specific to the Identity Provider.

Configure Attribute Map

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.

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.

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

Info
Turn on debug logging in log4j.properties for com.accipia.centerview.util.security, the log file will show the attributes and values that are available.

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.

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.

Troubleshooting

Enhanced diagnostics can be generated by adding the lines

...

Versions Compared

Old Version 3

New Version Current

Key

Contents

Create SAML reference

Configure the authentication manager

Add key store details

Metadata generator

Metadata configuration

Other configuration

Metadata Generation

Logging in as a SAML user

Configure Login Forms

Enable SAML beans

Configure the keyManager

Configure the Context Provider

Configure the Metadata Generator

Configure the Identity-Provider Metadata Provider

Generate Service Provider metadata

Attempt to login using SAML / Single Sign-on.

Login as a local user with admin rights

Download the metadata file

Install the Service Provider Metadata in the Identity Provider

Configure Attribute Map

Configure SAML User Details Service

Configure External Groups

Troubleshooting

Page Comparison

Versions Compared

Old Version 3

New Version Current

Key

Contents

Configure phixflow-login.xml

Create SAML reference

Configure the authentication manager

Add key store details

Metadata generator

Metadata configuration

Other configuration

Metadata Generation

Logging in as a SAML user

Configure Login Forms

Enable SAML beans

Configure the keyManager

Configure the Context Provider

Configure the Metadata Generator

Configure the Identity-Provider Metadata Provider

Generate Service Provider metadata

Attempt to login using SAML / Single Sign-on.

Login as a local user with admin rights

Download the metadata file

Install the Service Provider Metadata in the Identity Provider

Configure Attribute Map

Configure SAML User Details Service

Configure External Groups

Troubleshooting