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

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

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.

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

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

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

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

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

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

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

E.g.

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

Linux

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

E.g.

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

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:

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

1.  "file:/.../keystore.jks" to your keystore
2. "KeyStorePassword" to your keystore password
3. "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
4. "keyAlias" to the key you created in the keystore above; if you followed the example, this will be tomcat
5.  "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.

1. Delete the original contextProvider
2. Uncomment the reverse proxy version
3. 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

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:

1. entityId to a value that globally identifies the PhixFlow instance
2. 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.

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

E.g.

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

Linux

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

E.g.

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

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.

	<!-- filterThe thatKeyStore generatesstores metadataencryption based on configured properties keys -->
	<bean id="metadataGeneratorFilterkeyManager" 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" /key.JKSKeyManager">
		<!-- the keystore file -->
		<property name="entityBaseURL" <constructor-arg value="httpsfile:/opt/tomcat/myhostname:myport/phixflowsecure/keystore.jks" />
				<property name="extendedMetadata">
					<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
						<property name="idpDiscoveryEnabled<!-- password protecting the keystore -->
		<constructor-arg type="java.lang.String" value="falsekeyStorePassword" />
		<constructor-arg>
			<map>
				</bean>!-- key alias and key-specific password; add one entry for each key in the keystore -->
				</property><entry key="keyAlias" value="keyPassword" />
			</bean>map>
		</constructor-arg> 
	</bean>

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.

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

constructor-arg>
		<!-- default key alias -->
		<constructor-arg type="java.lang.String" value="defaultKeyAlias" />
	</bean>

	<!

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

Step 2  Generate Service Provider Metadata

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

The method depends on your Identity Provider. For a Windows Server ADFS identity provider, use the following 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

The method depends on your Identity Provider. For a Windows Server ADFS identity provider, use the following steps. 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. 

1. You must map the Name ID, which is the user name. Without this PhixFlow will reject the SAML login request.
2. 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.
3. 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.

Image Removed

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.

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

Image Removed

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

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:

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.

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

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

5.3  Create a new map by copying the example and changing its ID.

5.4  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).

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

5.6  Optionally add property name attributes to configure:

• mixed users
  By default all users of this domain are external users, PhixFlow does not manage authentication or authorisation. If you want PhixFlow to manage the authorisation for users who have SAML authentication in this domain, add the line:
    <property name="authenticationOnly" value="true" /> 

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

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.

6.1  Find the following section:

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

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

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

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

1.  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.
2. Edit the metadata provider section of phixflow-login.xml.
3. 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.

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

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

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

6.3  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. A user who logs in using SAML 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 the user 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.

In phixflow-login.xml, find the samlUserDetailsService 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:

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

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

Option 2: full debug information

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