Create Service Account in Okta to Synchronize Users

This page describes how to create a service account user with minimal permissions for users synchronization.

• It is always better to use regular admin user for users sync.

• This procedure should not be used to avoid sync by super admin because application gets only rights that are granted in Okta (Applications → LH → Scopes) so there is no way to get any sensitive rights.

• This approach makes sense if you want to limit set of users available in LH app or want to use service account instead of real admin user.

• If a Service Account is used for the Okta integration, we advice to use an email address for the Service Account that is monitored to receive system notifications like broken Service Account integrations.

• Okta Service Account permissions can be limited via roles (allow Service Account only to read users and not modify users, in this way the integration will be more safe and secure).

Step 1: Create Service Account

1. In Okta admin panel go to Directory → People.

2. Click Add person.

   1. Fill fields required in your tenant.

   2. Password: Set by admin.

   3. Create secure password.

   4. Ucheck User must change password on first login.

   5. Save.

Step 2: Assign Minimal Reveal Hold Role

As described in documentation - grant desired user Reveal Hold - System Administrator role - it will give minimal required access to manage subscription and address book.

Step 3: Create Minimal Okta Role

1. In Okta admin panel go to Security → Administrators → Roles.

2. Click Create new role.

   1. Name it (for example “Reveal Hold Users sync manager”).

   2. Select View users and their details permission.

   3. Save.

3. In Okta admin panel go to Security → Administrators → Resources.

4. Click Create new resource set.

   1. Add Assignment.

      • Resource type: Users.

      • Group names: Select Constrain to all users if you want all users to be accessible from LH app OR select groups of users to be visible. For groups make sure that these are Okta groups, users from Provisioned groups (like originated from Microsoft Entra ID) may not be visible.

   2. Name it accordingly (for example “All users”).

   3. Save.

Alternative

• Super Admin user  can be used for accessing all users, however, it will not grant any extra rights unless specified in Okta application scopes.

• Group Admin user can be used.

Step 4: Assign Minimal Okta Role

1. In Okta admin panel go to Security → Administrators → Roles.

2. In desired role row click Edit → View or Edit Assignments.

3. Add Assignment:

   1. Admin: Select created user.

   2. Resource set: Select created set.

4. Save.

Step 5: Users Sync

1. Log in to your Reveal Hold subscription with the newly created service account and select Synchronize users in the Address Book. Don’t forget to login with this user into the system at least once every 3 months so Reveal Hold will get a new OpenId Connect refresh token and proceed with background synchronization.

2. In the Okta Admin Console, enable refresh token rotation for the Reveal Hold app integration:

   1. Go to Applications and Resources > Applications.

   2. Select the Reveal Hold app integration.

   3. On the General tab, select Edit under General Settings.

   4. Under Grant type, select Refresh Token.

   5. Under Refresh Token, select Rotate token after every use.

   6. Set the Grace period for token rotation, if needed. The default is 30 seconds and can be configured from 0 to 60 seconds.

   7. Select Save.

For additional information about configuring refresh token rotation, see the Okta documentation: Enable refresh token rotation.