You can set up access to PhixFlow either through PhixFlow Users, 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:
Configure phixflow-login.xml
Configuration details for SAML are configured in the file phixflow-SAML.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:
<!-- example of a SAML authentication provider --> <security:authentication-provider ref="samlAuthenticationProvider"/>
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:
<!-- An Example of a KeyStore File --> <bean id="keyManager" class="org.springframework.security.saml.key.JKSKeyManager"> <constructor-arg value="classpath:keystore/samlKeystore.jks" /> <constructor-arg type="java.lang.String" value="<<KeyStorePassword>>" /> <constructor-arg> <map> <entry key="PhixflowSAML" value="<<KeyPassword>>" /> </map> </constructor-arg> <constructor-arg type="java.lang.String" value="PhixflowSAML" /> </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.
<property name="entityId" value="urn:test:phixflow:phixflow" />
Secondly replace the values under entityBaseURL to point at your tomcat configuration.
<property name="entityBaseURL" value="http(s)://<<hostname>>:<<port>>/Phixflow" />
For example if you are using the default tomcat configuration :
<property name="entityBaseURL" value="http://localhost:8081/Phixflow" />
or alternatively using a tomcat configured for HTTPS:
<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.
<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.
<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 :
<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.
<!-- 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 :
<!--<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>-->
so to generate your metadata the configuration should look like
<!-- 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
<!-- 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:
<!-- <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
To log in, users simply have to select a login option with SAML and click on the login button where they will be redirected to the identity provider to enter their credentials. If the login form configuration has been set to automatically log in with SAML, then they will see this screen and will instead be redirected straight to the identity provider.
Troubleshooting
Enhanced diagnostics can be generated by adding the lines
#Log information about the SAML login framework log4j.logger.org.springframework.security.saml=DEBUG log4j.logger.org.opensaml=DEBUG log4j.logger.PROTOCOL_MESSAGE=DEBUG
to your log4j.properties file - see Server Logging for details on controlling logging options with this file, and where to find the results.
Note that with all options applied, the log files generated will be very large. You must switch off these options as soon as you have completed your tests. You can comment out the lines in the log4j.properties file, if you want to keep them in the file, by placing a # at the beginning of each line.
You could also consider applying a more limited set of debugging options, e.g.
log4j.logger.org.springframework.security=debug log4j.logger.com.accipia.centerview.util.security=debug