Permissions - Features permissions

Coherent plans to deprecate the Features permissions functionality in the near future. Please consider using Client Credentials grant (OAuth 2.0) for implementing secure integrations to Spark.

Some Spark features can be executed independently from the Spark UI through APIs. These API endpoints have been grouped together by function and stored in feature permissions objects (conceptually similar to folders).

When using Authorization - API keys, access to the additional Spark API endpoints is managed through the features permissions objects. Features permissions allow the granular control of API key groups against different permissions to minimize the permissible access. With this functionality it is possible to create different API keys that have separate permissions such as to only download call history or only list folders for particular services.

From the Options tenant configuration page, tenant-admins can access a list of features permissions with descriptions and define functionalities accessible by API key groups.

If you are not already part of the supervisor:pf user group, they will only see a partial list. These users will see a prompt to add themselves to the group and then logout and back in again to see the complete list.

Manage features permissions

Clicking the View icon brings up a modal with additional details about the feature permission. Here tenant-admins can assign non-supervisor user groups to feature permission.

API key groups that contain these assigned user groups will be able to execute the API endpoints listed using their API key.

Assign user groups to feature permissions:

1. Copy the name of the user group you'd like to add to a feature permission.

2. Click the view icon of the feature permsion row (found under the column View).

3. Enter the user group name into the input box under the User groups header and click Add. Please note that the user group name must be written accurately.

4. When you click Add, the updated settings are effective immediately.

Assign all permissions by default

For teams that are more confident with their API key security, it is possible to set an API key group to work across all the listed Spark feature APIs. This can be done by adding the desired user group to the first feature permission in the list called Spark.AllEncompassingProxy.json.

• If a user group is added to this feature permission, if this user group is also part of an API Key group, then the API keys would have permission to use all the listed APIs.

• By default the user group user:api_integration is assigned to this feature permission. This means that if an API key group contains user:api_integration, then its API keys can use all the other APIs as well.

• In some cases user:pf may also be assigned to this group. If you do not want keys containing user:pf to be able to also access all the listed APIs, then remove it from Spark.AllEncompassingProxy.json.

Best practices

Minimizing the permissible access

The optimal way to manage features permissions would be to create API key groups that each contain 2+ user groups:

1. One or more user groups that represent the access to the Spark services that need to be actioned with these APIs.

   • For example the Mexico team may manage folders that are accessible via the user:teamgreen user group. user:teamgreen should be included in the API key group.

   • In a Shared Tenant, user:pf is the user group needed to access services.

2. A second user group what will be attributed to different features permissions, i.e. backend Spark feature APIs.

   • For example, to enable this key to download services using the call_id

     1. Create another user group such as user:download_call. This user group does not need to contain any users.

     2. Assign the user group user:download_call to the feature permission Spark.DownloadServiceByCallId.json.

3. Try to avoid using Spark.AllEncompassingProxy.json if not necessary.

   • This means that any user groups that are assigned to this feature permission supervisor:pf or user:api_integration if can be avoided would help to limit the permissions that an API key can call.

   • In some cases user:pf may also be assigned to this group. If you do not want keys containing user:pf to be able to also access all the listed backend APIs, then remove it from Spark.AllEncompassingProxy.json.

By creating the API key groups in this manner, it is possible to control both 1) the Spark services accessible and 2) the backend APIs exposed.

Manage and test permissions between environments

We advise our customers to use similar setups for Authorization - API keys and Permissions - Features permissions in their testing and production environments to ensure that verification of the security in the testing environment aligns with the behaviours in production.