Introduction
PhixFlow can be configured to allow external logins, where users are authenticated by external servers i.e. the user's credentials (username/password) are maintained on external servers and PhixFlow delegates to those external servers to check whether the user's credentials are valid. Currently we support Active Directory and SAML / Single sign-on.
In order to login to a PhixFlow instance, an External User must have an external group matching the PhixFlow instance's external login group which is set in System Configuration.
Once logged in, External Users have access rights based on membership of a number of User Groups, but rather than assigning users directly to User Groups in PhixFlow, the User Groups for an External User are determined by mapping their groups in the external system (e.g. their Active Directory groups) to PhixFlow User Groups.
This document describes how to configure the external login group in System Configuration and how to map external user groups to PhixFlow's User Groups.
See Active Directory or SAML / Single Sign-on for how to configure external login.
Contents
Configure the Login Group
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. 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. | 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.
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://.
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:
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
# detailed logging for AD connection attempts log4j.logger.org.springframework.security=debug log4j.logger.com.accipia.centerview.util.ContextUserExtractor=debug log4j.logger.com.accipia.centerview.util.security=debug log4j.logger.com.accipia.centerview.model.POJOImpl=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
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 what groups the user attempting to login belongs to.