You can set up access to PhixFlow either through PhixFlow 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. It assumes that a functioning ADFS server has already been deployed. For related information, see the User Administration topic.
Contents
Configure phixflow-login.xml
Configuration details for SAML are configured in the file phixflow-login.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:
<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):
<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 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:
<!-- comment out to enable saml / single sign-on --> <beans profile="saml">
E.g.
<!-- 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:
<!-- comment out to enable saml --> </beans>
E.g.
<!-- 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 keymanager bean configuration:
<!-- 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. "keyAlias" should match an actual key entry name in the keystore. Make sure also to set "defaultKeyAlias" to a key that actually exists, or you will see an error message when attempting to login to PhixFlow using SAML.
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:
<!-- 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):
<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:
<!-- 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 alongside 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:
<!-- 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.
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. For a Windows Server ADFS identity provider, follow these steps:
Log into the Windows ADFS Server. Run the command mmc.exe - this will open the windows server management console. Go to File -> Add/Remove Snap in... and add ADFS.
In the left hand tree view that appears, open Relying Party Trusts, then click on Add Relying Party Trust..., in the right hand menu.
Select Claims aware.
Next, choose to 'import data about the relying party from a file'. Browse to the service provider metadata xml file created in the previous step, and select it. Give the new relying party a name. Choose 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.
Configure Attribute Mapping on the Identity Provider
How you do this is specific to the Identity Provider. For a Windows Server ADFS identity provider, these steps should be carried out immediately after installing the service provider metadata in the identity provider:
Select the relying party trust that has been created. In the right-hand menu, click on Edit Claim Issuance Policy. This will bring up a list of Issuance Transform Rules, initially empty. Click on Add Rule. For the claim rule template, select Send LDAP Attributes as Claims. On the next screen, give the claim rule a name (anything will do), and select Active Directory as the attribute store.
The mapping of LDAP attributes to outgoing claim types determines which of the user fields held on the active directory server are transmitted to the service provider. The name of the field on the right hand side does not matter, but you should try to pick something semantically close to the LDAP Attribute.
- You must include the Name ID as an Outgoing Claim Type, and it should be mapped to the User-Principal-Name - this is the username, and without this PhixFlow will reject the SAML login request.
- The mapping for user groups is not obvious, and is also mandatory for the SAML login request. You should map 'LDAP Attribute Token-Groups - Unqualified Names' to 'Role', as shown in the screenshot below.
- Finally, when configuring the attribute mapping on the Service Provider (PhixFlow) side, make sure to match the domain to the service provider domain(?).
For the remaining LDAP Attributes, you can try out different mappings, to see what they actually contain when sent down to the phixflow application server.
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.
Each of the Outgoing Claim Types has a unique urn, which can be found under ADFS -> Service -> Claim Descriptions. E.g. Name ID has a urn (Claim Type) of http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier. This Claim Type should go into the attribute mapping in phixflow-login.
Alternatively, you may inspect phixflow.log to see what attributes are being sent down.
Turn on debug logging in logback.xml for com.accipia.centerview.util.security. The log file will show the attributes and values that are available. Even if you choose to use the list of claim types as a guide, this logging can be useful diagnostic information.
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:
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.
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>
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 (it is hard-coded).
Change the property values to match the attributes supplied by the identity provider.
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:
<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
#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