Configure Active Directory Integration

This page is for PhixFlow administrators who want to integrate PhixFlow authentication with Active Directory via LDAP.

Overview

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. To manage user access to the items and data in PhixFlow:
    1. Define the external login group. This defines the external group needed to login.
    2. Map external groups to PhixFlow's User Groups. When the user logs in, PhixFlow maps the user's external groups to its own user groups. This determines what the user is allowed to do in the particular PhixFlow instance.

Note that you do not need to create users explicitly in PhixFlow. Who in AD can log into PhixFlow can is controlled entirely by which AD users are placed in the PhixFlow external login group within AD.

As users successfully log into PhixFlow, user records will be created - you can view these with the PhixFlow GUI. These are read-only and do not represent authorisation for any future sessions for these users - again, this is entirely governed by the AD groups that these users are placed in. These user records in PhixFlow can be best thought of as an audit record of the latest successful login to PhixFlow via this AD integration.


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 the PhixFlow Webapp).

To configure this file for Active Directory login:

  1. Configure an Active Directory authentication provider.
  2. Add it to the authentication manager.
  3. To manage access to items and data, configure external groups.
  4. Configure one or more login forms to make the option to login using Active Directory visible to users.

Configure an Authentication Provider

Find this part of the file:

	<!-- Active Directory AuthProvider-->
	
	<!--
		You must provide 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:

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

Example

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

If this is true Active Directory is used for authentication when logging in, but not authorisation. This is a mixed user.

The user must be configured in PhixFlow before logging in and user groups must be configured for the user. External groups will not be used to determine access rights.

The default value is false if this property is not specified.

<property name="authenticationOnly" value="true" />

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

    <!-- 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"/>
		<property name="authenticationOnly" value="false" />
	</bean>

Configure the Authentication Manager

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

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>

Edit it to include the new AuthProvider.

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

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

Configure External Groups

System Configuration defines an external login group, which grants the right to login to that PhixFlow instance.

Each PhixFlow User Group can optionally have an external group. When a user successfully logs into PhixFlow via the AD LDAP integration, if any of the user's assigned AD groups match to external user group names defined in PhixFlow, they will be authorised as if they were in the PhixFlow users groups to which the external user groups have been added.

See Configure Groups for External Login for how to configure External Login groups.

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://.

The AD server’s certificate must be installed in the Java Certification Store on the PhixFlow application server. To do this you must obtain a certificate file from the AD server and install it.

One way of installing the certificate on the PhixFlow Application server is using the use the Java keytool command. This is installed with the Java environment. In the command prompt enter:

keytool -import -alias <alias-name> -keystore  </path/to/java/cacerts> -file <example.der>

Troubleshooting

Enhanced diagnostics can be generated by adding the lines

<!-- detailed logging for AD connection attempts -->
<logger name="org.springframework.security" level="debug" />
<logger name="com.accipia.centerview.util.ContextUserExtractor" level="debug" />
<logger name="com.accipia.centerview.util.security" level="debug" />
<logger name="com.accipia.centerview.model.POJOImpl" level="debug" />

to your logback.xml file - see Server Log Files for details on controlling logging options with this file, and where to find the results.

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 logback.xml file, if you want to keep them in the file, by placing <!-- at the beginning of the section and --> at the end.

You could also consider applying a more limited set of debugging options, e.g.

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

This will not give you as complete a log of what is happening during a login attempt, but the log files generated will be smaller. In particular, this reduced set of debugging options will include messages from:

com.accipia.centerview.util.security.ActiveDirectoryLdapAuthenticationProvider

which provides information about the groups to which the user belongs.

Sections on this page