Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

You can set up access to PhixFlow either through PhixFlow Users, by integrating with your Active Directory infrastructure, or both. If you integrate with Active Directory, Access Control is maintained by mapping Active Directory Groups to PhixFlow User Groups, as described below. By using the Active Directory integration users will login to PhixFlow using the same username and password as their Microsoft Windows domain login.

Configuring PhixFlow with Active Directory has a number of steps

  1. Configure an authentication provider - this defines how to connect to an Active Directory domain
  2. Add the authentication provider to the authentication manager
  3. Define the external login group - this defines the external group needed to login
  4. Map external groups to PhixFlow's User Groups - on login PhixFlow maps the user's external groups to PhixFlow's user groups to determine what the user is allowed to do in the particular PhixFlow instance

Contents

Table of Contents
maxLevel1

Configure phixflow-login.xml

Connection details to the domain servers 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).

To configure this file for Active Directory login, you must

  • configure an Active Directory authentication provider
  • add it to the authentication manager

Configure an Authentication Provider

Find this part of the file:

Code Block
	<!-- Active Directory AuthProvider-->
	
	<!--
		You must provided one AuthProvider bean for each domain to which you want to connect, 
		each based on one of the examples below, and add it to the authenticationManager above
	-->

	<!-- Example bean providing domain and url to authentication-provider -->
	<!-- 
	<bean id="exampleActiveDirectoryAuthProvider" parent="activeDirectoryAuthProvider">
		<constructor-arg index="0" value="narnia.local" />
		<constructor-arg index="1" value="ldap://192.168.150.81" />
	</bean>
	-->

Then uncomment and edit one of the example activeDirectoryAuthProvider beans to reflect your active directory configuration.

Simple connection

The simplest configuration, for the domain mydomain.com and the domain controller at a specific IP address, is illustrated below:

Code Block
languagexml
    <!-- authentication-provider for mydomain.com -->
    <bean id="mydomainAuthProvider" parent="activeDirectoryAuthProvider">
        <constructor-arg index="0" value="mydomain.com" />
        <constructor-arg index="1" value="ldaps://192.168.1.1" />
    </bean>

Advanced options

For the connection you can also specify:

OptionPurposeExample
Domain servers
(Constructor-arg 1)
Some domains are served by multiple servers, to provide resilience and load balancing. These are specified in a space-separated list. PhixFlow will try each of these in turn.
<constructor-arg index="1" value="ldaps://ad1.example.com ldap://ad2.example.com" />

You can also specify connecting to the domain itself. This is equivalent to connecting to the list of domain controllers specified in the DNS entry for the domain.<constructor-arg index="1" value="ldaps://example.com" />

Root DN
(Constructor-arg 2)

If you have a large AD tree, searches may take some time, and this could lead to slow authentication for users. Therefore it is possible to specify a root DN (Distinguished name) at which PhixFlow will begin searching for the user. The Distinguished Name format is standard and further details can be found on the web.
<constructor-arg index="2" value="ou=User Accounts,ou=Operations,dc=emea,dc=example,dc=com" />
Timeout

You can specify a timeout. For each server specified, if the server does not respond within the limit specified by the timeout, it will try the next server. If the last server in the list times out, then the authentication will fail.

The timeout is specified in milliseconds.

<property name="timeout" value="5000"/>

The following example, in phixflow-login.xml.example, illustrates the application of all advanced options:

Code Block
    <!-- Template of a bean providing domain, multiple servers, connection timeout and separate rootDn -->
	<bean id="exampleActiveDirectoryAuthProvider" parent="activeDirectoryAuthProvider">
        <constructor-arg index="0" value="example.com" />
        <constructor-arg index="1" value="ldap://ad1.example.com ldap://ad2.example.com" />
        <constructor-arg index="2" value="ou=User Accounts,ou=Operations,dc=emea,dc=example,dc=com" />
        <property name="timeout" value="5000"/>
	</bean>

Configure the authentication manager

Now add the authentication provider you have just defined to the authentication manager.

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 include the new AuthProvider.

The authenticationManager should now look something like this (comments omitted):

Code Block
languagexml
	<security:authentication-manager alias="authenticationManager">
		<security:authentication-provider ref="localAuthProvider" />
		<security:authentication-provider ref="exampleActiveDirectoryAuthProvider" />
	</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.

Configure Group mappings

PhixFlow Active Directory Setup

System Configuration

Go to the Active Directory tab in the System Configuration window.

...

  • PHIXFLOW_ADMINS
  • PHIXFLOW_USERS_LIVE

User Groups

When Active Directory users log into PhixFlow, their Active Directory groups are mapped to PhixFlow User Groups. You can set up this mapping by specifying an Active Directory Group in a PhixFlow User Group. When an AD user in that Active Directory group logs into PhixFlow, they will be put into that PhixFlow User Group. You do not need to map all of a user's Active Directory Groups to PhixFlow User Groups. For each user, any Active Directory groups that are not mapped are simply ignored.

...

Active Directory users appear on the Group Members list. There is a new column which indicates if the user is a local user or a Active Directory user. Only local users can be added or removed from the list.

User Details

While editing an Active Directory user some fields are invisible. Login name cannot be changed. The domain of the User is shown in the header of the editor.

Logging in as a Active Directory user

There is a new Domain field on the PhixFlow login screen. The value this will have by default is set in System Configuration (see above).

...

If the user is in an Active Directory Group authorised to use PhixFlow, but none of their Active Directory groups are mapped to PhixFlow user groups, they will be able to successfully log in, but will have no access.

Use the encrypted connection

To use the encrypted connection, the protocol of the connection specified in phixflow-login.xml must be set to ldaps://instead of ldap://.

...

keytool is provided as part of the standard Java installation.

Troubleshooting

Enhanced diagnostics can be generated by adding the lines

...