Set up the Microsoft Entra ID (Azure AD) Connector

This task is for users with the OC System Administrator role.

Microsoft Entra ID was formerly known as Azure AD and is currently referred to as such in your website admin. Microsoft Entra ID is an external user management system that can be connected with the CMS to manage users and enable single sign-on for admins, Intranet users, and password-protected subsites.

The External User Management module is included with Intranets and can be purchased for organizations without an Intranet.

There are a few steps to go through to connect Microsoft Entra ID to your CMS and websites properly:

• What you'll need before you begin
• Register an application with Microsoft Entra ID
  • Your connection items
• Connect with the CMS
• Role mapping
• User detail mapping
• Sync schedule

Before You Begin

Before you can use the connector, you'll need:

• A Microsoft Entra account that your organization connects to.
• An Application Registration within Microsoft Entra ID for this platform.
• Microsoft Entra groups that you’d like to assign to different roles.

Register an Application with Microsoft Entra ID

Before connecting, you'll need to register an application within Microsoft Entra ID; use Microsoft's step-by-step guide to help you.

You’ll need to take some additional steps to connect:

1. Make sure you configure redirect URIs. You only need to input your admin URL if you use the connector to manage single sign-on. You must include your admin and web return URLs for Intranets. We've listed your redirect URIs in the More > External User Management > Azure AD screen. Copy and paste these into your Microsoft Entra ID settings.
   
2. Set up access permissions. In the API Permission screen, the API you’ll need to give permissions to is “Microsoft Graph.” The specific permissions you’ll need to add are:
   • Application permissions:
     Group.Read.All
     User.Read.All
   • Delegate permissions:
     email
     Group.Read.All
     GroupMember.Read.All
     openid
     profile
     User.Read
     User.Read.All
     User.ReadBasic.All
     
     You will also need to grant consent for the CMS platform. 
3. Set up ID tokens. In the Overview > Authentication screen, navigate to Advanced settings and locate the Implicit grant section. Select ID tokens and save your changes.

Your Connection Items

Once your Microsoft Entra ID account is ready to accept a connection, you’ll need a couple of items from Microsoft Entra ID to enter into our connector. 

• Client secret: Another name for a key. Generate this from the Certificates & secrets screen in your Microsoft Entra ID admin screen. Client secrets expire every two years, so you must update it in your admin.
• Directory ID: This is on the Properties page for the application you just registered (OpenCities).
• Domain name: This is on the Custom domain names page.
• Application ID: This is on the Overview page for the application you just registered (OpenCities). 

Connect with OpenCities

You can set up the connector when your Microsoft Entra ID application is ready to receive a connection and you have the connection items ready.

1. Go to More > External User Management and select Azure AD.
   
2. Enter all the connection items you’ve prepared in the Connector Settings screen and Test your connection.
   
3. Save your settings.

If your connection was successful, two additional tabs will appear on your Azure AD connector screen when you save: Role mapping and User detail mapping.

If your connection failed, double-check that your Microsoft Entra ID permissions are set up correctly, as described above, and that your client secret has not expired. The secret must remain active to maintain the connection, so give this a prolonged duration. If you still can’t connect after checking these, let us know, and we’ll help. 

Role Mapping

Role mapping automatically assigns user groups in Microsoft Entra ID to roles in the CMS, controlling the level of access and permissions different groups have in the platform.

To map roles:

1. Go to More > External User Management > Azure AD, and select the Role mapping tab.
2. Select Add mapping.
   
3. From the Choose Azure AD group list, choose the group you'd like to map to a role.
   
4. Decide whether you’d like to give this group admin access, or just a member login to your Intranet.
   
   If you’re using an “all staff” group to populate your staff directory, leave this box unchecked for that group.
5. Choose which site you’re mapping roles to, then Add site. This is important because users may have different roles across different sites. For example, a library admin might not have admin access to your main site.
6. Select the roles you want to give the group.
   
7. Alternatively, choose roles available in the All Websites section if you're mapping an Microsoft Entra ID group with the same role across all the sites you use the connector with (such as yourself, the system administrator).
   
8. Save your group mapping. 
9. Repeat the mapping process (steps 5-7) for any additional sites you’d like that group to have roles in, remembering to Save your mapping each time. 
10. Repeat steps 3-8 for any additional groups you’d like to assign roles to. 
11. Save your completed role mapping settings.

If your organization has purchased an Intranet, you can use role mapping to populate your staff directory. Intranets add any users with the OC Member role to the staff directory. By mapping an “all staff” group to the OC Member role, you can automate this process by adding new staff to your “all staff” group at onboarding. 

User Detail Mapping

If you have Intranets installed, you can also map properties within Microsoft Entra ID groups to website and CMS user details. This lets you automatically fill profiles in your staff directory with items like:

• Job titles
• Departments
• Phone numbers
• Staff photos

To map user details, 

1. Go to More > External User Management > Azure AD and choose the User detail mapping tab.
2. Use the Property in Azure AD drop-down to choose a corresponding property from the drop-down menu for each detail you'd like to map. If you don’t see the property you’d like to add, you can choose "other" and enter it manually.
   
3. Save your mapping.

All fields in the user detail mapping tab are optional — map as many (or as few) as you need for your organization. However, if you’re mapping profile images, you must specify an image format.

Some properties available to map may also require additional Microsoft licenses. For example, fields that require the SharePoint Online license include "MySite," "PreferredName," and "AboutMe." If fields that require a specific license are used within user detail mapping without that appropriate license, it will display the error "[Unable to display]" on staff directory pages.

Sync Schedule

By default, your CMS installation will sync with Microsoft Entra ID daily at 3 am. We use an off-peak time because syncing can affect your site performance. 

If you’d like to manually sync at another time, go to More > External User Management and choose Sync now.

You can also pause the daily sync schedule (if you’re performing maintenance, for example) by choosing Pause auto sync, but make sure to Resume auto sync when you’re ready to go again. 

Please note that deleting a connected external user system will deactivate synced users. If you're disabling a connection with Okta, you must convert your users from external to local management before deleting the external user management system.