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:
| Table of Contents | ||
|---|---|---|
|
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).
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"> <!-- 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> |
... and 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> |
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 active directory integration.
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"> |
Find these lines, near the end of the file, and remove them or comment them out:
| 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 | ||
|---|---|---|
| ||
<!-- 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 users access the server directlydoes 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 and , uncommenting the reverse proxy version, and changing the serverName, serverPort and serverPort contextPath to match the public view.
It should look something like this (most comments omitted):
| Code Block |
|---|
<!-- Context Provider -->
<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.
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="http(s)://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 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:
...
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. We asume that it will be in the metadata directory, which is along side the phixflow-login.xml file.
Find this section of the file:
...
| Code Block | ||
|---|---|---|
|
...
<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> <!-- 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 | ||
|---|---|---|
| ||
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). |
| Code Block | ||
|---|---|---|
| ||
<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 | ||
|---|---|---|
| ||
<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.
...