Set up the Azure AD connector

This task can be undertaken by users with the following roles: OC System Administrator.

Microsoft Azure Active Directory is an external user management system, which 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 you can connect 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.

There are some additional steps you’ll need to take within Azure AD to connect to OpenCities.

1. Make sure you configure redirect URIs. If you’re using the Azure AD connector to manage single sign-on, you’ll just need to input your ‘admin’ URL. For Intranets you’ll need to include your ‘admin’ and ‘web’ return URLs. We've listed your redirect URIs in the More > External User Management > Azure AD screen. Simply 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'll need to update it in your admin.
Directory ID	This is in the Azure AD Properties page for the application you just registered (OpenCities).
Domain name	This is in the Azure AD Custom domain names page
Application ID	This is in 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. From the main menu, 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, you'll see two additional tabs appear in 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 properly, 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 long duration. If you still can’t make a connection after checking these, let us know and we’ll jump in to 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 you have Intranets installed, you can also use role mapping to populate your staff directory. Intranets add any users with the OC Member role to the staff directory. By making an “all staff” Azure AD group mapped to the OC Member role, you can automate this process by simply adding new staff to your “all staff” group at onboarding. 

To map roles:

1. From the main menu, 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 of the sites you're using 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 OC 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. For each detail you’d like to map, choose a corresponding Azure AD property from the dropdown menu. 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 of the fields in the user detail mapping tab are optional. Map as many (or as few) as you need for your organization. If you’re mapping profile images, however, you will be required to 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 as with 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 3am. We use an off-peak time to do this 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'll need to convert your users from external to local management before deleting the external user management system.