Configure phixflow-domains.xml

Connection details to the domain servers are configured in the file phixflow-domains.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-domains.xml.example (see PhixFlow Server Installation).

Create domain reference

To create a reference to a domain, update the section in the example file:

        <!-- Template of a authentication-provider -->
        <!-- 
        <security:authentication-provider ref="exampleActiveDirectoryAuthProvider" /> 
        -->

For example, if this domain will be referred to as corporate, update this to (remembering to remove the surrounding comment):

        <!-- Template of a authentication-provider -->
        <security:authentication-provider ref="corporate" />

Add connection details

Simple connection

The simplest type of connection is illustrated below, referencing a single AD server.

Update the section in the example file:

    <!-- Template of a 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>
    -->

to include connection details to the domain. For example, if the domain is called corporate.local and this is manged by the domain controller at 10.23.109.45, update this to (remembering to remove the surrounding comment):

    <!-- Template of a bean providing domain and url to authentication-provider -->
    <bean id="corporate" parent="activeDirectoryAuthProvider">
        <constructor-arg index="0" value="corporate.local" />
        <constructor-arg index="1" value="ldap://10.23.109.45" />
    </bean>

Advanced options

For the connection you can also specify:

Option

Purpose

Example

Multiple servers

Some domains are served by multiple servers, to provide resilience and load balancing. These can be specified in a list. PhixFlow will try each of these in turn.

<constructor-arg index="1" value="ldap://ad1.example.com ldap://ad2.example.com" />

Root DN

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-domains.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"/>
		</bean>
    -->

PhixFlow Active Directory Setup

System Configuration

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

There are two fields to configure:

Field

Value

Example

Default Domain

This is the domain that users will be presented with when they open PhixFlow. They will be able to select a different domain by selecting from a drop-down list, which will show all configured domains, as well as local. The local domain is used when logging in as an internal PhixFlow user.

local

narnia.local

Active Directory Login Group

The list of names of Active Directory groups authorized to use this instance of PhixFlow, separated by semicolons. Use {instance} to include the PhixFlow instance name (this is set up in System configuration).

Note that these groups do not have to be mapped to any of the PhixFlow User Groups (see below), although they can be if you wish.

PHIXFLOW_ADMINS; PHIXFLOW_USERS_{instance}

With the given configuration, assuming the instance name is ‘LIVE’, members of the following Active Directory groups will be authorized to log in into this PhixFlow instance:

PHIXFLOW_ADMINS
PHIXFLOW_USERS_LIVE

User Groups

The current PhixFlow mechanism of User Groups can be applied to Active Directory users. There is a new Active Directory Group field in the User Group editor window. Members of the given Active Directory group will be members of the configured PhixFlow User Group. Use {instance} to include the PhixFlow instance name.

With the given configuration, assuming the instance name is ‘LIVE’, members of the Active Directory ‘PHIXFLOW_USERS_LIVE’ will be members of the ‘Designers’ PhixFlow User Group.

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 a login screen.

By default it is set to local, which means that the user logs in as local, PhixFlow user.

To log in as an Active Directory user, the user needs to pick one of the domains configured in the phixflow-domains.xml file from the highlighted drop-down list.

After choosing a domain, the proper suffix will be added to the username automatically:

While logging as an Active Directory user, the user must use the Active Directory password, which cannot be changed through the PhixFlow.

If the Active Directory user is not a member of a group authorized to use the PhixFlow, the proper message is shown.

Use the encrypted connection

To use the encrypted connection, the protocol of the connection must be set to ldaps:// instead of ldap://. It can be set in the phixflow-domains.xml file, in the value of the url field of selected bean.

Note that server’s certificate must be installed in the user’s Java Certification Store. To do this user needs to obtain a certificate file from the server and install it. One way of doing this is using a keytool:

In the command prompt type:

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

keytool is provided as part of the standard Java installation.

PhixFlow Active Directory Guide