Configuring your Azure AD for OIDC Federation and Automatic User Provisioning


Table of Contents

I. Prerequisites
II. Creating the Application
III. Instructions for OIDC Federation Configuration
IV. Instructions for Sync Configuration
V. Syncing Users and Groups
VI. Provisioning of External Users
VII. Attributes That Can Be Modified
VIII. On-Demand Provisioning (Users Only)

I. Prerequisites

To set up your Azure AD for federated authentication and automatic syncing of users and groups, you must have:

Note: All Azure AD federations must sync their users to utilize federation. This is a precautionary measure to help prevent issues with user identities where federation may fail to keep you signed into the correct user account through identity updates in your Azure AD.

Reach out to the Bentley IMS Team by submitting a request for federation to start this process. Once coordinated with the team, they will provide you with a 365-day secret token that you can use to enable the sync portion of this application on your Azure Active Directory.  This token process will be replaced once it is offered on the MS store, where the authentication process will be slightly different.

II. Creating the Application

1. In the Azure portal, from the middle navigation panel, select "Manage Microsoft Entra ID".

2. Go to "Enterprise applications"


3. To add a new application, select the "New application" button at the top of the pane.

4. Search "Bentley" and click on the Bentley application: 

5. You may keep the name of the application, rename it to reflect your own preference, or rename to "Bentley Systems SSO and User Sync" to reflect that this app will be used for both.

6. Select "Create" at the bottom of the page on the right. After a few moments the page will automatically redirect you to the enterprise application that was just created to support this work. This also created an app registration with the same name at the same time. 

III. Instructions for OIDC Federation Configuration

This guide will first walk you through the configuration of federation utilizing the OIDC protocol. For questions regarding federation, please first browse the Federation FAQ, and relay any follow up questions to the Identity Engineer who assists you with your federation. 

  1. Navigate back to your Azure AD homepage by selecting the name of your tenant in the top left:

2. Select "App Registrations" from menu on the left:

3. Select the app registration with the same name as the enterprise application you just created. 

4. On the left-hand side go to "Token configuration" and select "Add optional claim" to set up the details we will receive in your id_token. 

5. Select "ID" as the token type. From the menu that populates, select "ctry", "family_name", "given_name", "upn". Then hit add. A pop up will prompt for the Microsoft Graph permissions required to access these details. Click the checkbox to grant the permission, and hit add.

6. On the left, go to "Certificates & Secrets", and click on "New Client Secret". 

7. For the description field provide "Bentley". Expiration is up to your organizations discretion. Most commonly secrets are issued for 6 months or 1 year, but may vary depending on your organization's security stance regarding client secret rotations. Click add once an expiration as been chosen. 

8. A new client secret will populate on the page. Use the clipboard option to copy the client secret value. We do not need the secret ID. Keep note of the secret on a notepad as you will not be able to see this value again once you navigate away from this page. 

9. (OPTIONAL) Federations which utilize OIDC present a consent screen to the user when they go to authenticate for the first time which allows for access to the users data. The user must provide consent or they will get an error returned when trying to authenticate. To avoid the consent screen all together, your Azure AD admin can grant admin consent on their behalf. This allows for access to an end user's data during authentication without prompting for consent. NOTE: This does not give Bentley access to all of your users data. This only allows the Azure AD application to access the data of the user who is performing authentication. To do this, select "API Permissions" from the left and hit "Grant admin consent for <your org name>":

10. Now go back to "Overview" to collect the other necessary details for federation. From this page you can gather the Application (client) ID and add it to your notepad, then select "Endpoints":

 

11. From the Endpoints tab, copy the "OpenID Connect metadata document" URL from the center of the menu: 

12. Provide the gathered Client ID, Client Secret, and Metadata URL to the Bentley IMS team. The Bentley IMS team will use these provided details to set up your federation for testing. The Bentley IMS team will provide instructions back to you which explain how you can test. The instructions will also have you input Redirect URI's in order to finalize the OIDC set up. When you have received these URL's, go the Authentication tab on the left hand side and select "Add a platform":

13. Select "Web" from the options: 

14. In the Redirect URI's section, supply one of the two provided redirect URI's and hit configure:

15. In the Web platform that has now populated the authentication tab, select "Add URI" and provide the second URL that the Bentley IMS team provided you and hit save at the bottom:

16. By default, the application restricts what users can sign into the application and the users must be a part of the Users and Groups for the application to access it. To set this, go to Enterprise Applications and select the application you created for this set up. Navigate to Users and Groups on the left hand side. 

The users that you put here will not only be authorized to sign in, but once you enable your sync, will also be synced into IMS. For now, only supply the users that you would like to have test. Do not provide all of the users or groups containing users at this time.

During testing, only supply the users that you would like to have test. Once you have confirmed that the federation and sync are both working as expected, we'll have you update the Users and Groups section to ensure that all of your Bentley users are loaded into the Users and Groups section.

17. This completes the set up for federation authentication. You may now use the instructions provided by the Bentley IMS team to test your federation. If you encounter any issues, please be sure to let the engineer assisting you know.

IV. Instructions for Sync Configuration

  1. Navigate to your Enterprise Applications and select the application that you created. Select the Provisioning tab.

2. Click "Get Started".

3. Set the Provisioning Mode to Automatic.

4. Under the Admin Credentials section, input https://userprovisioning.bentley.com/scim in the field titled Tenant URL. Input the secret token generated by Bentley support in the Secret Token field. If you do not have one, please email IMSTeam@bentley.com to have one generated for you. Click Test Connection to ensure Azure AD can connect to Bentley. If the connection fails, ensure your Bentley account has Admin permissions and try again.

5. Under the "Settings" area, there is a Notification Email field, enter the email address of a person or group who should receive the provisioning error notifications and check the checkbox - Send an email notification when a failure occurs.

6. Scroll to the top and click Save.

7. To enable the Azure AD provisioning service for Bentley, change the Provisioning Status to On in the Settings

8. Define the users and/or groups that you would like to provision to Bentley by choosing the desired values in Scope in the Settings.

9. When you are ready to provision, click Save.

This operation starts the initial synchronization of all users and/or groups defined in Scope in the Settings section. The initial sync takes longer to perform than subsequent syncs, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running. You can use the Synchronization Details section to monitor progress and follow links to the provisioning activity report, which describes all actions performed by the Azure AD provisioning service into IMS.

For more information on how to read the Azure AD provisioning logs, see Reporting on automatic user account provisioning.

WarningWarning: To avoid unintentionally removing users from User Management, do not set the Provisioning Status to On until your list of users and groups has been finalized. Users can be provisioned on demand for testing purposes using the instructions in the section titled "VIII. On-Demand Provisioning (Users Only)." Once users display a green badge in User Management, indicating they are synced with Azure AD, they will be removed from User Management if removed from the access list in your enterprise application. They can be restored by adding them back to the access list, but any roles they previously possessed must be re-assigned in User Management.

V. Syncing Users and Groups

If while configuring the application you selected to sync only the assigned users and groups, then those users/groups must be added to the application manually.

Microsoft currently does not allow for the ability to sync nested groups through enterprise applications.

The Requirement is :

  1. Group description cannot be empty.
  2. Group name or description cannot contain any special characters. Here is a list of unsupported characters. *  \  /   <  >  ?  :  ;  "  +  !  (  )  ^  @  #  &  `  ~  =  {  }  [  ]  |  $  %

To add users/groups, go to the Bentley User Provisioning Application:

During testing, only supply the users that you would like to have test. Once you have confirmed that the federation and sync are both working as expected, we'll have you update the Users and Groups section to ensure that all of your Bentley users are loaded into the Users and Groups section.

  1. Open the application and click "Assign users and groups" from an Overview page

 

  1. On the opened page click “+ Add User"

 

  1. Click on the “Users and groups” section and choose users or groups that you want to synchronize into the Bentley system, select and click “Assign”.

 

Users and groups will be synchronized on the next provision run.

VI. Provisioning of External Users

In the future, we are exploring the possibility to sync external users, but in its current state, we do not allow external users to be synced into IMS by using this tool.  We will provide updates as new releases come out when this ability is added.

VII. Attributes That Can Be Modified

You can update user details through Azure AD and those attributes will be automatically updated in User Management after next Provision run.

User Attributes that can be updated:

Group attributes that can be updated:

VIII. On-Demand Provisioning (Users Only)

1. Go to Provisioning section of the application in the Azure Portal:

2. Click On-Demand Provision. A new page should open:

3. Enter the user you want to Provision/update Attributes and click Provision:

4. The user should be provisioned instantly and the results are shown on the same page.

See also Instructional Video