Okta

Configuring Provisioning for RingCentral

This guide provides the steps required to configure Provisioning for ServiceNow and includes the following sections:


Features

The following provisioning features are supported:


Requirements

Before you configure provisioning for RingCentral, check the following requirements:


Configuration Steps

Make sure you have selected your RingCentral Brand under the General Settings tab:

ringcentral_prov1.png

You can now configure your Provisioning settings for RingCentral as follows:

  1. Check the Enable API Integration box, then click Authenticate with RingCentral:

    ringcentral_new1.png

    Note: If you are setting up the RingCentral UAT application in Okta Preview, you will need to plug in the API Base URL under the General tab. The URL is https://api.uat.ringcentral.com.

  2. Enter your RingCentral Admin account credentials, then click Log In at the pop-up window:

    ringcentralprov2.png

  3. Select To App in the left panel, then select the Provisioning Features you want to enable.

    Note: The authenticated session is valid for one month since last usage of provisioning features. If you will not use provisioning for more that one month, you'll have to re-authenticate the app.

    ringcentral_new2.png

Refer to the Schema Discovery section for information about adding extra user attributes.


Bi-directional Sync (Attribute Level Mastering)

While either Okta or Active Directory are the sources of truth for most attributes in a user profile, in the case of a RingCentral deployment, the Direct Number and Extension information comes from RingCentral. To support this, you need to setup bi-directional sync for these attributes so that values can flow back to Okta or Active Directory.

To achieve this, do the following:

  1. Contact Okta Support to enable the ALLOW_BOTH_PROFILE_MASTERING_AND_PUSH feature flag.

  2. Add the Direct Number and Extension Number attributes via Schema Discovery to the AppUser profile by navigating to Profile Editor > RingCentral > Add Attributes.

  3. Set mappings via the Profile Editor in the RingCentral to Okta section:

    1. You should have the following configured:

      • appuser.userName > login

      • appuser.firstName > firstName

      • appuser.lastName > lastName

      • appuser.userName > email

    2. Configure the mapping for directNumber and extensionNumber:

      For example, map a combined value to the primaryPhone attribute in the Okta profile – the format is [directNumber]#[extensionNumber]:

      (appuser.directNumber != null ? appuser.directNumber : "") + "#" + appuser.extensionNumber

      ringcentralprov4.png

  4. For the primaryPhone attribute, you need to set the RingCentral as the Master:

    • Click on the Primary phone attribute in the Profile Editor.

    • Under Master priority, select Override profile master.

    • Add RingCentral as the master as shown below.

    • Click Save Attribute.

    ringcentralprov5.png

  5. Enable the Profile Master provisioning feature for the application.

    Note: Make sure you have the right master priority set if there are other Profile Master apps. You can do so by going to Directory > Profile Masters.

    ringcentralprov6.png


Schema Discovery

RingCentral supports User's Schema Discovery, so you can add extra attributes to User's Profile. To do that in Okta:

  1. Navigate to Directory > Profile Editor.

  2. Select the APPS section and find your app in the list.

  3. Check the list of the attributes and if you didn't found what you need, click Add Attribute and you'll get the list of extended attributes.

  4. Check the attributes you want to add, then click Save.

You are now able to import and push these User's attributes values from/to RingCentral.


Okta > RingCentral Attribute Mapping Requirements

The following list is the minimum set of attributes needed from Okta into RingCentral:

OKTA TO > RingCentral

user.firstName

firstName

user.lastName

lastName

user.email email
user.mobilePhone mobilePhone
user.streetAddress street
user.city city

user.state

Note: Make sure State in AD/Okta is in proper ISO format

state
user.zipCode zip
user.countryCode country
user.department department

Make sure that the state name is either a standard state name (such as California) or state code (such as CA).


Provisioning Errors

ERROR MESSAGE EXPLANATION

The [${parameterName}] is invalid. Please correct the parameter in Active Directory.

Values coming from Active Directory are not right. Please correct the values. Make sure all the values are right.

Resource for parameter [${parameterName}] is not found.

Value is missing in Active Directory. Please correct it.

JSON can not be parsed. Please check your data AD and correct it. JSON can not be parsed. Please check your data AD and correct it.
Service Temporarily Unavailable. Please check back later. Please check back again in sometime. Issues on Okta.
Extension already in use. Please go to RingCentral's web portal and see what extensions are available. Extension already in use. Please check in service web if extension is available or not.
user.city city
Extension number is duplicate. Please correct in Active Directory if you have an extension field. Otherwise edit it in the RingCentral Service web portal To bulk edit extensions in the RingCentral web portal. Please go to User Management > edit extensions and follow the instructions to edit.
More than one record found for Email: [email] RingCentral has more than one user record for the given [email]. Since Okta uses email address as the unique identifier per user, you need to ensure that does not have duplicate users with the same email address.
user.countryCode country
user.department department

Troubleshooting Tips

Note that you might have a limited number of Phone Extensions in RingCentral, so you won't be able to create new users if all Phone Extensions are busy.

RingCentral may have more than one user record for one email. Since Okta uses email address as the unique identifier per user, you need to ensure that RingCentral does not have duplicate users with the same email address.