Set Up the Okta Connector

This task is for users with the OC Developer and OC System Administrator roles.

Okta Identity Cloud 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 Okta to your OpenCities sites properly:

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

Before You Begin

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

• An Okta Identity Cloud that your organization connects to.
• An application created within Okta for OpenCities.
• Okta groups that you’d like to assign to different roles in OpenCities.

Set Up an Application in Okta

Before connecting Okta with OpenCities, you'll need to set up an application for OpenCities with the Okta Developer console; use Okta's step-by-step guide to help you.

When creating your application, use the following information:

1. Select OpenID Connect as the Sign-in method, then choose Web Application from the Application type. 
2. Make sure you configure your redirect URIs.
   
3. For your login redirect URIs, if you’re using the Okta connector to manage single sign-on, you’ll need to input your admin URL. For Intranets, you must include your admin and web return URLs. We've listed your login redirect URLs in the More > External User Management > Okta screen. Copy and paste these into your Okta settings. 
   
4. Your Logout redirect URIs are also listed in the More > External User Management > Okta screen. Copy and paste these into your Okta settings. 
   
5. Make sure you check the Authorization code and Implicit (Hybrid) checkboxes. You don't need to worry about any optional fields, such as Base URLs or adding groups.

You must set your Okta scopes once you've created your Okta application.

1. Go to Applications > Active in the Okta developer console, and select the application you just made.
2. Go to the Okta API Scopes tab for your application (Applications > Active > your application > Okta API Scopes), and grant the following scopes:
   • okta.groups.read
   • okta.roles.read
   • okta.users.manage.self
   • okta.users.read 
3. Double-check that you've added the scopes above by checking the Granted menu in the Okta API Scopes tab
   

Your Connection Items

Once your Okta application is ready to accept a connection from OpenCities, you’ll need to take note of a couple of items from Okta to enter into our connector. 

Client ID and Client Secret	These are at the bottom of the General tab for your application. (Applications > Active > your application > General)
API Key (token)	To create an API token, follow Okta's step-by-step guide.  Please copy this token before closing the Create Token window, as it will not be displayed again.
Org URL	If you don't know your organization's Okta domain URL, you can find it here.

Connect Okta with OpenCities

You can set up the connector when your Okta application is ready to receive a connection and the connection items are ready.

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

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

If your connection fails, double-check that your Okta application is set up properly and that your API token has not expired. To maintain the Okta connection, the token must remain active; check the API > Tokens screen in Okta to ensure your token is active. If it has lapsed, you'll need to create another one. 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 Okta to roles in OpenCities, controlling the level of access and permissions different groups have in OpenCities.

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

To map roles:

1. Go to More > External User Management > Okta, and select the Role mapping tab.
2. Select Add mapping.
   
   
3. From the Choose Okta 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” Okta 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 Okta 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 Okta 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 Okta 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 > Okta and choose the User detail mapping tab.
2. Choose a corresponding Okta 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 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.

Sync Schedule

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