Set up the Okta connector

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

Okta Identity Cloud 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 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 you can connect 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’ll need to include your ‘admin’ and ‘web’ return URLs. We've listed your login redirect URLs in the More > External User Management > Okta screen. Simply copy and paste these into your Okta settings. 
   
4. Your Logout redirect URIs are also listed in the More > External User Management > Okta screen. Simply 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 yet.

Once you've created your Okta application, you need to set your Okta scopes.

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 you have the connection items ready.

1. From the main menu, go to More > External User Management and select Okta.
   
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 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 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 Okta 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” Okta group mapped to the OC Member role, you can automate this process by simply adding new staff to your “all staff” Okta group at onboarding. 

To map roles:

1. From the main menu, 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 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 > Okta and choose the User detail mapping tab.
2. For each detail you’d like to map, choose a corresponding Okta 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.

Sync schedule

By default, your OpenCities installation will sync with Okta 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 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'll need to convert your users from external to local management before deleting the external user management system.