This page is for administrators who need to integrate PhixFlow authentication with a SAML system.
Overview
Security Assertion Markup Language (SAML) is a standard for providing secure single-sign on for users. On Microsoft Windows Servers, the single sign-on identity for users are provided by the Active Directory Federation Services (ADFS) component.
On Windows Server systems that are running ADFS, you can configure PhixFlow to be a SAML Service Provider. This involves mapping PhixFlow user groups to the Active Directory groups. When a user attempts to log into PhixFlow, they are redirected to the authentication page of your system's identity provider, where they enter their username and password. If they are successfully authenticated they will then be redirected to PhixFlow and logged in.
Step 1 Configure phixflow-login.xml
To set up SAML integration, you need to add details to the configuration file, phixflow-login.xml, which is in the directory <tomcat root>/webapps/phixflow/WEB-INF/classes
. This file is created during installation, by copying the example file phixflow-login.xml.example, and setting any essential options; see Install the PhixFlow Webapp.
Panel | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
1.1 Specify the Authentication Manager
Edit the authenticationManager
section of phixflow-login.xml to add a samlAuthProvider
.
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> |
Edit it to look like this (omitting comments):
Code Block | ||
---|---|---|
| ||
<security:authentication-manager alias="authenticationManager">
<security:authentication-provider ref="localAuthProvider" />
<security:authentication-provider ref="samlAuthProvider" />
</security:authentication-manager> |
Tip |
---|
We recommend that you keep the |
1.2. Configure Login Forms
Edit the loginConfiguration
section of phixflow-login.xml to define the login form options (local, single sign-on, active directory). These specify what the user sees on their PhixFlow login screen. 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 details.
1.3. Enable SAML Beans
Edit the beans profile section section of phixflow-login.xml. Edit the 2 blocks that disable the options that are only required when PhixFlow is managing user authentication.
Find these lines:
Code Block |
---|
<!-- comment out to enable saml / single sign-on -->
<beans profile="saml"> |
Remove them or comment them out:
Code Block |
---|
<!-- comment out to enable saml / single sign-on -->
<!--
<beans profile="saml">
--> |
Find these lines, near the end of the file:
Code Block |
---|
<!-- comment out to enable saml -->
</beans> |
and remove them or comment them out:
Code Block |
---|
<!-- comment out to enable saml -->
<!--
</beans>
--> |
1.4. Configure the keyManager
Edit the keyManager
section of phixflow-login.xml to specify the keystore.
Insert excerpt | ||||||||
---|---|---|---|---|---|---|---|---|
|
keyManager
bean configurationkeyStorePasswordkeyAliaskeyPassworddefaultKeyAlias5.context.SAMLContextProviderImpl" /></bean>1.67 Rule.4.4 For the claim rule template, select Send LDAP Attributes as Claims.
4.5 On the next screen, give the claim rule a name, and select Active Directory as the attribute store.
4.6 Map the LDAP Attributes to Outgoing Claim Types. This mapping determines which user fields are sent from the Active Directory server to PhixFlow.
- You must map the User-Principal-Name, which is the user name. Without this PhixFlow will reject the SAML login request.
- You must map Token-Groups - Unqualified Names to Role, as shown in the screenshot below. The mapping for user groups is mandatory for the SAML login request.
- Map any remaining LDAP attributes that you require. You may need to test different mappings, to identify what information is sent to the PhixFlow server.
When you map an LDAP Attribute to an Outgoing Claim Type, enter a Name ID. You can specify any name for an outgoing claim type. However, for clarity the name should be similar to the LDAP Attribute.
Tip |
---|
When you configure the attribute mapping on PhixFlow (the service provider) in Step 5, below, remember to match the domain to the service provider domain. |
Step 5 Configure Attribute Map in PhixFlow (Service Provider)
As part of the SAML single sign-on process, the identity provider sends details of the user who is logging in as a set of name/value pairs. An attribute map defines how PhixFlow maps the identity provider's attribute names to the names required by PhixFlow.
5.1 Each of the Outgoing Claim Types has a unique URN, which can be found under ADFS → Service → Claim Descriptions. For example Name ID
has a URN claim type of http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
. Add this claim type to the attribute mapping in phixflow-login.xml.
Alternatively, look in the phixflow.log
file to see what attributes are being sent; see Log Files.
Info |
---|
Turn on debug logging in logback.xml for |
As long as you have correctly mapped the username and domain and the rest of the SAML setup is correct, you should see lines like these:
Code Block |
---|
2019-08-21 16:28:38,839 DEBUG [http-nio-8080-exec-3] o.s.s.s.w.WebSSOProfileConsumerImpl [WebSSOProfileConsumerImpl.java:237] Including attribute http://schemas.microsoft.com/ws/2008/06/identity/claims/role from assertion _8c9686b7-9029 |
The URN is the same as the URN given in the list of Claim Descriptions.
5.2 Back in phixflow-login.xml, find the attribute map section:
language | xml |
---|
5.3 Create a new map by copying the example and changing its ID.
5.4 Change the domain to the value you want to be displayed as the domain for any users who login using SAML (it is hard-coded).
5.5 Change the property values to match the attributes supplied by the identity provider.