Set up the OneLogin Connector

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

OneLogin, Inc. is a cloud-based identity and access management provider for enterprise-level businesses and organizations. You can connect their unified access management system with OpenCities to manage users and enable single sign-on for OpenCities admins, Intranet users, and password-protected sites.

The OneLogin Connector is part of the External User Management module, which is included with Intranets and can be purchased separately for organizations without an Intranet.

There are a few steps to go through to connect OneLogin to your OpenCities site correctly:

1. Set up an Application Registration in OneLogin
   • Create API Credentials
   • Create an OpenID Application in OneLogin
2. Connect OneLogin with OpenCities
3. Role mapping
4. User detail mapping
5. OneLogin sync schedule

Set up an Application Registration in OneLogin

You'll need to create API credentials and set up an application in the OneLogin Developer console before connecting OneLogin with OpenCities; OneLogin's Developer guide can help you.

Create API Credentials

You'll need to create API Credentials within OneLogin, so you'll need to log into your OneLogin account first.

1. In your OneLogin account, go to Developers > API Credentials in the main menu.
2. Select New Credentials, give your API a relevant Name and select Read all as the permission.
3. Select Save, then go back to Developer > API Credentials and select your newly created API credential to copy the Client ID and Client Secret.

Ensure you note your Client ID and Client Secret, as you'll need to input these into your OpenCities admin.

Create an OpenID Connect Application in OneLogin

You'll now need to create an OpenID Connect Application in OneLogin

1. From the main menu of your OneLogin account, go to Application > Applications.
2. Select Add App and use the search bar to search for OpenID Connect.
3. Select Save and then open your OpenID Connect app to configure your redirect URIs.
4. From your Login redirect URIs, you need to input your "admin" URL if you use the OneLogin connecter to manage SSO. We've listed your login redirect URIs in the More > External User Management > OneLogin screen. Copy and paste these into your OneLogin app settings.
   
5. Your Logout redirect URIs are listed in the More > External User Management > OneLogin screen; you'll need to copy these into your OneLogin settings.
6. To enable users to login in bulk, go to Access and select which role is allowed to log in.
7. Alternatively, you can individually add the users allowed to log in using OpenID. Go to Users > Users > Applications, then select the + button on the right-hand Applications panel.
8. Use the dropdown menu to select the application you created and select Continue.
9. Allow the user to sign in should be checked by default, so select Save.
10. Go to Applications > Applications in the main menu, select the application you created, and the Users tab will show you which users can log in.
11. Go to the SSO tab and copy the Client ID, which you'll need to set up the module in your OpenCities admin.

Connect OneLogin with OpenCities

Before you connect, you'll need the following:

• A OneLogin Identity Cloud that your organization can connect to
• API credentials created in OneLogin for OpenCities
• An application made in OneLogin for OpenCities
• User groups that you'd like to assign to different roles in OpenCities

Now that you have the API Client ID, Client Secret, and the OpenID Client ID, you can connect your OneLogin account with your OpenCities site.

1. In your OpenCities admin, go to More > External User Management.
2. Under Identity providers, select OneLogin.
3. Enter your connection items into the appropriate field and add the subdomain from the URL of your OneLogin account into the Org Subdomain field. In this example, "random-dev1234" is the subdomain.
   
4. Save your settings.

Now you can map your user groups to roles in OpenCities.

Role mapping

Role mapping assigns user groups in OneLogin to specific roles in OpenCities, allowing you to control the level of access and permissions groups of users have in OpenCities admin.

If you're using an Intranet, you can also use role mapping to populate your staff directory; users with the OC Member role can access Intranets and be added to the staff directory.

To map roles:

1. In your OpenCities admin, go to More > External User Management > OneLogin, and select the Role Mapping tab.
2. Select Add mapping and choose the group you want to map from the list under Choose OneLogin group.
3. Decide whether you'd like to give this group admin access to OpenCities, or just a member login to your Intranet.
4. Choose which site you're mapping roles to and select Add site. Remember, specific groups of users may have different access across sites; for example, a library admin might not have admin access to your main site.
5. Select the role(s) you want to give the group.
6. Alternatively, choose roles available in the All Websites section if you're mapping a OneLogin group with the same role across all sites with which you're using the connector (such as OC System Administrator).
   
7. Save your group mapping.
8. Repeat the mapping process (steps 4-6) for any other sites in which that group needs roles, remembering to Save your mapping each time.
9. Repeat steps 2-8 for any other OneLogin groups you'd like to assign roles to.
10. Save your completed Role mapping settings.

User detail mapping

If you have an Intranet installed, you can map properties within OneLogin groups to OpenCities user details. This lets you automatically fill profiles in your staff directory with items such as:

• Job titles
• Departments
• Phone numbers

To map user details:

1. In your OpenCities admin, go to More > External User Management > OneLogin and select the User detail mapping tab.
2. Choose a corresponding OneLogin property from the dropdown menu for each detail you want to map. If you don't see the property you'd like to add, you can choose Other and enter it manually.
   Note: the options from Comment to UserPrincipalName are all built-in properties; any options below are Custom User Attributes that are ordered alphabetically.
   
3. Save your mapping.

All of the fields in the User detail mapping tab are options. Map as many (or as few) as you need for your organization. Please note that OneLogin does not support syncing profile photographs.

Sync schedule

Your OpenCities installation will default sync with OneLogin 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 any time, go to More > External User Management and select Sync now.

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