...
...
Contents
...
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 external groups
- 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:
| 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 | ||
|---|---|---|
| ||
<!-- 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:
| Option | Purpose | Example |
|---|---|---|
| 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
| ||
| 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 | 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 | ||
|---|---|---|
| ||
<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
...
PhixFlow Active Directory Setup
System Configuration
Go to the Active Directory tab in the System Configuration window.
There are two fields to configure:
...
| Code Block |
|---|
local |
| Code Block |
|---|
narnia.local |
...
The list of names of Active Directory groups authorized to use this instance of PhixFlow, separated by semicolons. There must be no spaces between the groups listed, just 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.
| Code Block |
|---|
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
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.
The mapping is configured in the field Active Directory Group in the user group configuration form.
You can 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 the PhixFlow login screen. The value this will have by default is set in System Configuration (see above).
To log in, users must select the domain they need - if this is not the default, they can select one from the drop down list, which will show all configured domains.
After choosing a domain, the suffix will be added to the username automatically:
While logging as an Active Directory user, the user must use their Active Directory password, which cannot be changed through PhixFlow.
If the Active Directory user is not a member of an Active Directory group authorised to use PhixFlow (see above), they will get a standard failure to login message.
...
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. If this group is not configured, or the user is not a member of that external group, she will not be allowed to login, even if she provides a valid username and password for the identity provider.
Each PhixFlow User Group defines external group names which grant access rights (the rights to view, activate, change, delete objects) conferred by membership of those user groups. That User Group may define External Group names. A user who successfully logs in using SAML / Single Sign-on is considered a member of a User Group, and has the access rights of that User Group, if she is a member of any of the User Group's External Login Groups (matched by name).
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 keytool. In the command prompt type:
| Code Block |
|---|
keytool -import -alias example -keystore /path/to/java/cacerts -file example.der |
keytool is provided as part of the standard Java installation.
Troubleshooting
Enhanced diagnostics can be generated by adding the lines
| Code Block |
|---|
...
<!-- 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 Logging
...
for details on controlling logging options with this file, and where to find the results.
| Note |
|---|
...
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.
| Code Block |
|---|
...
<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:
| Code Block |
|---|
com.accipia.centerview.util.security.ActiveDirectoryLdapAuthenticationProvider |
which provides information about
...
the groups to which the user
...
belongs
...
.