Introduction

This guide provides step-by-step instructions for configuring a basic Identity Federation deployment between Microsoft Active Directory Federation Services (AD FS) and Bentley's Identity Management System (IMS). 

The document is intended for server and active directory administrators with knowledge of ADFS. 

Prerequisites

• Federation with Bentley IMS requires the WS-Federation protocol with the SAML 2.0 token format. 
• This guide assumes that your AD FS is properly setup on a SSL/TLS endpoint using HTTPS and the authentication address is accessible by your corporate users.
• Federation can only be configured for an email domain which is owned by your organization.  This email domain can only be associated with a single Bentley account hierarchy.
• A Microsoft Windows Server with Microsoft AD FS and the latest operating system updates.

Setup

Step 1 - Download Bentley's Federation Metadata File

Bentley's Federation Metadata XML can be downloaded from https://ims.bentley.com/FederationMetadata/2007-06/FederationMetadata.xml. 

DO NOT open the XML file in Notepad or make any edits to the document as it is signed.  This file will be required for step 2.5.

 

Step 2 - Register IMS as a Relying Party (RP) in ADFS

1. Open ADFS Management and navigate to Trust Relationships > Relying Party Trusts

2. Click Add Relying Party Trust

3. Click Start

4. In the Select Data Source screen, select the second option “Import data about the relying party from a file”.

5. Click Browse, select the FederationMetadata.xml you saved from step 1, and click Next.

6.  On the next screen, enter a name in the Display name field and click Next.

Enter Bentley IMS for the production environment

7. On the next screen, select the “I do not want to configure multi-factor authentication settings for this relying party trust at this time” radio button and click Next.  Note, configuring multi-factor authentication is outside the scope of this document.

8. On the next screen, select the “Permit all users to access this relying party” radio button and click Next.

9. On the next screen, verify the Signature details shown are valid. Click Next.

10. On the final screen, leave the checkbox “Open the Edit Claim Rules dialog for this relying party trust when the wizard closes” checked and click Close.

Step 3 - Setup Claims Issuance

If the Edit Claim Rules wizard does not open automatically, access it from the AD FS Management application under AD FS > Trust Relationships > Relying Party Trusts.  Click Edit Claim Rules ... on the right hand side. 

1. On the Edit Claim Rules page, click Add Rule.

2. Select the claim rule template Send LDAP Attributes as Claims from the dropdown and click Next.

3. Select the attribute store Active Directory. Select the following LDAP Attributes and outgoing claims using the screenshot below as a reference.

Notes:

#1 – The Country attribute is typically stored in the LDAP database under an attribute named “c”, however in your tenant it may be stored elsewhere, so verify the location of the country information for your tenant. If "c" is not in the drop-down list, and that is where your country information is stored, you must manually type “c” into the blank attribute box.  Regardless of where it is stored in LDAP, the outgoing claim should be called “Country”.   

#2 – If you define “c” as the country attribute, you will also need to define the correct schema for the “c” attribute in the Claim Descriptions as seen below or it could cause the federation to fail:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country

 

#3 – You should send the e-mail attribute if you are using the email address as the unique identifier for your users, but use the UPN attribute and value instead if your users are identified by their UPN. The UPN claim syntax is as follows:

LDAP Attributes	Outgoing Claim Type
User-Principal-Name	UPN

#4 – We suggest using e-mail address as the primary identifier, but if you need to use the UPN, do not send the email address attribute as well.  Either the "UPN" or the "E-mail Address" claim should be sent - not both. 

#5 – After chosing to send either the "E-mail Address" or "UPN" claim, always send the NameID claim with the UPN. The NameID field is required regardless.

4. Click Finish when you have completed adding claim rules.

5. Using the Edit Claim Rules wizard, click Add Rule again.

6. Select Pass Through or Filter an Incoming Claim and click Next.

7. Enter Name Claim as the rule name. Select Name as Incoming claim type and choose Pass through all claim values. Click Finish.

8. Click OK to close the Edit Claim Rues dialog.

Step 4 - Adjust the trust settings

1. Right click on Bentley IMS in the Relying Party Trusts pane and select Properties.

2. Click on the Endpoints tab.

3. Click on Add WS-Federation.

4. Type in the endpoint in the Trusted URL field. Make sure to check Set the trusted URL as default. Click OK.

Enter https://ims.bentley.com/ for the production environment (must include the trailing slash)

5. Click on the Encryptions tab.  Make sure that you do not have any certificate here for token encryption.

6. Click OK to close the Properties dialog.

This completes the ADFS server configuration portion for Single Sign On with Bentley IMS using the WS-Federation protocol.

 

Step 5 - Provide your Organization's Federation Metadata URL to Bentley

Your organization's Federation Metadata URL is available in the AD FS Management Console.

Browse to Service > Endpoints > Metadata > Type:Federation Metadata to find your federation metadata URL.

You will need to provide your organization's Federation Metadata URL to Bentley.  Once the Federation Metadata URL is provided, Bentley will configure your organization for federated identity in Bentley's Identity Management System.