Background
Some CentreStack tenants may already be using Active Directory Federation Services (AD FS) and wish to use their Active Directory credentials for single sign-on to CentreStack. This article describes how a CentreStack tentant can be federated with an AD FS such that AD FS is the Security Assertion Markup Language (SAML) Identity Provider (IdP0 and CentreStack will be the SAML Relying Party (RP).
Known Limitations
- CentreStack build 10.2.6335.43041 or later is required.
Configuration
- On the AD FS server start the Server Manager application.
- From the Tools menu select AD FS Management
- In the AD FS application, click on the Relying Party Trusts node in the left-most pane.
- Click Add Relying Party Trust… in the right-most Actions pane.
- The Claims aware option should be enabled, then click the Start button:
- Enable SSO in your CentreStack tenant:
- Select the text in the Access service provider meta data using the following link field and copy it to the clipboard, in this example:
https://cstackjjr.hadroncloud.com/portal/saml2.aspx?sso=y6oL0772
- 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:
- Click the Next button in the preceding dialog
- Update the Display Name and Notes fields appropriately then click the Next button:
- For the purposes of this example, select Permit everyone and click Next:
- Click Next in this dialog (all of the necessary settings for the CentreStack Relying Party were already specified in the xml document that was imported):
- Leave the Configure claims issuance policy for this application enabled then click the Close button:
- With the new relying party selected in the middle pane, click Edit Claim Issuance Policy... in the Actions pane.
- In the Edit Claim Issuance Policy… dialog click the Add Rule… button:
- From the Claim rule template drop down, select Send Claims Using a Custom Rule then click the Next button:
- 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://sts.hadroncloud.com/internal/persistentId"), query = "{0};{1};{2}", param = "ppid", param = c.Value, param = c.OriginalIssuer); - Click OK in the preceding dialog
- Click the Add Rule button for the second time:
- From the Claim rule template drop down, select Transform an Incoming Claim then click the Next button:
- Use these values
- Claim rule name: Create Persistent Name ID
- Incoming claim type: http://sts.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
- Click the Add Rule button for the third time:
- From the Claim rule template drop down, select Send LDAP Attributes as Claims then click the Next button:
- In the Configure Rule dialog:
- Claim Rule name text box type Send CentreStack 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
- Now that the three rules have been defined click the OK button:
- Switch back to the browser where the CentreStack SINGLE SIGN ON page is displayed.
- Optional: Enable Add SSO link to login page:
It is recommended that this option be disabled. This option doesn't make sense in a multi-tenant deployment where more than one tenant may be using SAML for single sign on. 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. - Add some descriptive text in the Display text for SSO link. This text will only be displayed in the CentreStack sign on dialog if the Enable Add SSO link to login page option is enabled.
- Optional: Enable the Create user when User Doesn't Exist option:
If this option is enabled users will be automatically created in the CentreStack tenant after they have been authenticated with AD FS. This is very convenient in most situations. - Set the SSO Provider to AD FS:
- Set the Fully Qualified Domain Name to the FQDN of your AD FS server (in this example the AD FS is sts.hadroncloud.com):
- Click the Save icon:
- Test it by navigating to:
- The IdP initiated sign on URL:
https://<fqdn>/adfs/ls/idpinitiatedsignon.aspx - The RP initiated sign on URL, which is the URL specified in the Access single signon functionality using the following link text box.
- The IdP initiated sign on URL:
Troubleshooting
Database Column Width
If your CentreStack server was deployed prior to late 2018, it's possible that you will see this error when saving the settings in the GROUP POLICY HOME > SINGLE SIGN ON page:
This may be caused by the AD FS server responding with a metadata xml doc whose size exceeds the column width of the Value column in the xaf_namedvalue table in the CentreStack database. More recent versions of CentreStack avoid this problem by having a database schema that defines the Value column as type MEDIUMTEXT. Unfortunately older versions of CentreStack that were upgraded to later versions don't have their schema altered. It is possible to work around this problem by running this MySQL command:
ALTER TABLE csmain.xaf_namedvalue MODIFY COLUMN Value MEDIUMTEXT
You may want to contact CentreStack technical support with help running this command.
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:
- Start Chrome on the client and navigate to: https://chrome.google.com/webstore/category/extensions?hl=en-US
- In the search box type: saml devtools extension:
- For the extension offered by stefan.rasmusson.as click the Add to Chrome button:
- Click the Add Extension in the next dialog.
- The SAML extension will be displayed in Chrome:
- To use the tool, press F12 to display Chrome's developer tools, the click the SAML tab, then click the Show only SAML option:
- In the address bar, navigate to the Relying Party Initiated Sign On URL, for example: https://cstackjjr.hadroncloud.com/portal/LoginPage.aspx?sso=y6oL0772
- Sign into the AD FS idpinitiatedsignon.aspx page:
- Click on the last POST in the middle pane to view the SAML assertion. Click on the SAML tab to view the XML data:
- The most important part of the XML data is the Attributes in the assertion. This is usually where problems happen because CentreStack requires the name, givenname and surname attributes similar to what is seen here:
Comments
0 comments
Please sign in to leave a comment.