Background

Some Triofox clients may already be using Active Directory Federation Services (AD FS) and wish to use their Active Directory credentials for a single sign-on to Triofox. This article describes how a Triofox can be federated with an AD FS such that AD FS is the Security Assertion Markup Language (SAML) Identity Provider (IdP0 and Triofox will be the SAML Relying Party (RP).

Known Limitations

• Triofox version 12.2 or later is required.

Configuration

1. On the AD FS server start the Server Manager application.
2. From the Tools menu select AD FS Management
3. In the AD FS application, click on the Relying Party Trusts node in the left-most pane.
4. Click Add Relying Party Trust… in the right-most Actions pane.
5. The Claims aware option should be enabled, then click the Start button:
6. Enable SSO in your Triofox:
   
7. Select the text in the Access service provider metadata using the following link field and copy it to the clipboard, in this example:

   https://tt3hcslsv01.triofox.io/portal/saml2.aspx

8. Back in the AD FS Management application, enable the Import data about the relying party published online or on a local network option, then paste the text from the Access service provider metadata using the following link text box into the Federation metadata address field:
   
9. Click the Next button in the preceding dialog
10. Update the Display Name and Notes fields appropriately then click the Next button:
    
11.  
12. For the purposes of this example, select Permit everyone and click Next:
    
13. Click Next in this dialog (all of the necessary settings for the Triofox Relying Party were already specified in the XML document that was imported):
    
14. Leave the Configure claims issuance policy for this application enabled then click the Close button:
    
15. With the new relying party selected in the middle pane, click Edit Claim Issuance Policy... in the Actions pane.
16. In the Edit Claim Issuance Policy… dialog click the Add Rule… button:
    
17. From the Claim rule template drop-down, select Send Claims Using a Custom Rule then click the Next button:
18. Use these values:
    • Claim rule name: Generate opaque identifiers
    • Custom rule: (Copy and paste the text below and replace the sts.hadroncloud.com in the text with the FQDN of your AD FS server)

      c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
       => add(store = "_OpaqueIdStore", types = ("http://triofoxadfs.eastus.cloudapp.azure.com/internal/persistentId"), query = "{0};{1};{2}", param = "ppid", param = c.Value, param = c.OriginalIssuer);

      
    • Click Finish in the preceding dialog
19. Click the Add Rule button for the second time:
    
20. From the Claim rule template drop down, select Transform an Incoming Claim then click the Next button:
    
21. Use these values
    • Claim rule name: Create Persistent Name ID
    • Incoming claim type: http://tt3hcslsv01.hadroncloud.com/internal/persistentId (paste the text, ignoring the drop-down control and replace sts.hadroncloud.com with the FQDN of your AD FS server)
    • Outgoing claim type: Name ID (using the drop-down control)
    • Outgoing name ID format: Persistent Identifier (using the drop-down control)
    • 
      
    • Click OK in the preceding dialog
22. Click the Add Rule button for the third time:
    
23. From the Claim rule template drop-down, select Send LDAP Attributes as Claims then click the Next button:
    
24. In the Configure Rule dialog:
    • Claim Rule name text box type Send Triofox Attributes,
    • Select Active Directory from the Attribute store drop-down.
    • In the LDAP Attribute field select User-Principal-Name and in the Outgoing Claim Type select Name.
    • For the next LDAP Attribute field select Given-Name and then Given Name for the Outgoing Claim Type.
    • Finally, the last LDAP attribute is Surname and the Outgoing Claim Type is Surname.
    • The Configure Rule dialog should look like this, then click Finish:
      
      Click Finish
25. Now that the three rules have been defined click the OK button:
    
26. Switch back to the browser where the Triofox SINGLE SIGN-ON page is displayed. Click the Next button
27. Set the Fully Qualified Domain Name to the FQDN of your AD FS server (in this example the AD FS is triofoxadfs.eastus.cloudapp.azure.com): Click the Next button
28. Optional: Enable "Don't redirect to IdP login page automatically"
    
    End-users will sign in using the so-called "RP initiated sign-on URL" displayed in the Access single signon functionality using the following link text box at the top of the page, or through the "IdP initiated sign-on URL" provided by AD FS (i.e. https://<fqdn>/adfs/ls/idpinitiatedsignon.aspx, where "<fqdn>" is the fully qualified domain name of the AD FS server farm.
29. Add some descriptive text in the Display text for SSO link. This text will only be displayed in the Triofox sign-on dialog
    
30. Optional: Enable the Create user when User Doesn't Exist option:
    
    
    If this option is enabled users will be automatically created in the Triofox tenant after they have been authenticated with AD FS. This is very convenient in most situations.
31. Click the Commit button
32. Test it by navigating to:
    1. The IdP initiated sign on URL:
       https://<fqdn>/adfs/ls/idpinitiatedsignon.aspx
       i.e.: https://triofoxadfs.eastus.cloudapp.azure.com/adfs/ls/idpinitiatedsignon.aspx
    2. The RP initiated sign-on URL, which is the URL specified in the Access single sign-on functionality using the following link text box.

Troubleshooting

SAML Devtools Extension for Chrome

For any errors reported by the browser when signing in, it may be very useful to examine the SAML assertion using an extension for Google Chrome:

1. Start Chrome on the client and navigate to: https://chrome.google.com/webstore/category/extensions?hl=en-US
2. In the search box type: saml devtools extension:
3. For the extension offered by stefan.rasmusson.as click the Add to Chrome button:
   
4. Click the Add Extension in the next dialog.
5. The SAML extension will be displayed in Chrome:
   
6. To use the tool, press F12 to display Chrome's developer tools, the click the SAML tab, then click the Show only SAML option:
   
7. In the address bar, navigate to the Relying Party Initiated Sign-On URL, for example:  https://tt3hcslsv01.hadroncloud.com/portal/LoginPage.aspx
8. Sign into the AD FS idpinitiatedsignon.aspx  page:
   
9. Click on the last POST in the middle pane to view the SAML assertion. Click on the SAML tab to view the XML data:
   
10. The most important part of the XML data is the Attributes in the assertion. This is usually where problems happen because Triofox requires the name, givenname and surname attributes similar to what is seen here: