Set up the Azure AD Connector

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

Microsoft Azure Active Directory is an external user management system that can be connected with OpenCities to manage users and enable single sign-on for OpenCities 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 Azure AD to your OpenCities sites properly:

• What you'll need before you begin
• Set up an Application Registration in Azure AD
  • Your connection items
• Connect Azure AD with OpenCities
• Role mapping
• User detail mapping
• Azure AD sync schedule

Before You Begin

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

• An Azure Active Directory that your organization connects to.
• An Application Registration within Azure AD for OpenCities.
• Azure AD groups that you’d like to assign to different roles in OpenCities.

Set Up an Application Registration in Azure AD

Before connecting Azure AD with OpenCities, you'll need to set up an Application Registration within Azure AD; use Microsoft's step-by-step guide to help you.

You’ll need to take some additional steps within Azure AD to connect to OpenCities.

1. Make sure you configure redirect URIs. You only need to input your admin URL if you use the Azure AD 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 Azure AD settings.
   
   
2. Set up access permissions. In Azure AD’s 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 OpenCities.
     
3. Set up ID tokens. In Azure AD's 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 Azure Active Directory is ready to accept a connection from OpenCities, you’ll need a couple of items from Azure AD to enter into our connector. 

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

Connect Azure AD with OpenCities

You can set up the connector when your Azure AD 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 Azure AD permissions are set up correctly, as described above, and that your client secret has not expired. The secret must remain active to maintain the Azure AD 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 Azure AD to roles in OpenCities, controlling the level of access and permissions different groups have in OpenCities.

If Intranets is installed, 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” Azure AD group to the OC Member role, you can automate this process by adding new staff to your “all staff” group at onboarding. 

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 to OpenCities, 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 Azure AD 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 Azure AD groups you’d like to assign roles to. 
11. Save your completed role mapping settings.

User Detail Mapping

If you have Intranets installed, you can also map properties within Azure AD groups to OpenCities 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. Choose a corresponding Azure AD 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.

Azure AD Sync Schedule

By default, your OpenCities installation will sync with Azure AD 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 Azure AD 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.