Upcoming Changes: Access & Permissions

Announcements
1

Category: API

Summary: PureCloud's permission system is undergoing a major change with the introduction of Fine-Grained Access Control.

This feature will affect the way that PureCloud controls access to:

  • Queues
  • Users
  • Workforce management units
  • Architect flows
  • Analytics
  • Dialer campaigns
  • Contact lists and do-not-contact lists

There will also be changes to the way PureCloud grants permission to users and displays a list of a user's granted permissions.

More detailed information can be found here.

Context: Fine-Grained Access Control will give administrators the ability to configure which users have access to specific objects within PureCloud. Visit the Resource Center for additional documentation.

Impact: This change has the potential to cause existing API calls to return different results than before the change. There will also be new endpoints for managing users' role grants. Finally, the permission-checking logic for many endpoints will be affected, so it is important for developers to understand how PureCloud grants permissions.

Date of Change: This change was first announced on 12 July, 2018. We have extended the notification window in order to provide additional time for you to assess the impact of the change, to raise any questions, and to plan accordingly. This change is now scheduled to go into effect on 20 February, 2019.

Impacted APIs: Analytics, Authorization, Routing, Flows, Users, Groups, Workforce Management, Outbound Dialing

If you have any questions about Fine-Grained Access Control and how it may impact your application, please reply to this forum topic.

2
3

Hi there. Thanks for the details.

I have one question: I have an oauth client credential with "Outbound Admin" role. I use it for exporting and downloading contact lists. In the Client Credential admin UI, I see a ROLES field, listing this, and other roles I have.

If I understood correctly, I will need to set up a "division" with all the Contact Lists I want this user to be able to export, and assign it to this Client Credential. Is that correct? Can you provide more details based on this simple example?

Thank you very much.

4

Correct, work is under way to support this so it isn't currently possible for client credentials apps to get data outside the home division

5

Division-Aware Permissions

Upon release of Fine-Grained Access Control, the following permissions will include division IDs as an additional "level" of the permission. If your app is currently checking for any of these permissions, it will need to be updated to account for the additional granularity.

This list is accurate as of 23 January 2019 and will not be maintained past this date.

analytics:conversationAggregate:view
analytics:conversationDetail:view
analytics:conversationProperties:index
analytics:evaluationAggregate:view
analytics:flowAggregate:view
analytics:flowObservation:view
analytics:queueObservation:view
analytics:surveyAggregate:view
analytics:userAggregate:view
analytics:userDetail:view
analytics:userObservation:view
architect:flow:add, delete, edit, publish, unlock, view
conversation:call:monitor
conversation:communication:disconnect, transfer, view
conversation:participant:wrapup
directory:user:add, delete, edit, view
outbound:campaign:add, delete, edit, view
outbound:contactList:add, delete, edit, view
outbound:dncList:add, delete, edit, view
quality:evaluation:add, delete, edit, editAgentSignoff, editScore, view, viewAudit
quality:survey:delete, edit, view, viewAudit
recording:annotation:add, delete, edit, view, viewAudit
recording:recording:delete, download, editRetention, restore, view, viewAudit
recording:screenRecording:editRetention, restore, stop, view, viewAudit
routing:queue:add, delete, edit, view, join
wfm:activityCode:add, administer, delete, edit, view
wfm:agent:administer, edit, view
wfm:historicalAdherence:view
wfm:intraday:view
wfm:managementUnit:add, administer, delete, edit, view
wfm:publishedSchedule:view
wfm:realtimeAdherence:view
wfm:schedule:add, administer, delete, edit, view, generate
wfm:serviceGoalGroup:add, administer, delete, edit, view
wfm:shiftTradeRequest:add, delete, edit, view
wfm:shortTermForecast:add, administer, delete, edit, view
wfm:timeOffRequest:add, administer, delete, edit, view
wfm:workPlan:add, administer, delete, edit, view

6

Fine-Grained Access Control introduces several new API resources:

This list is accurate as of 23 January 2019 and will not be maintained past this date.

Authorization
/api/v2/authorization/divisions

/api/v2/authorization/divisions/{divisionId}

/api/v2/authorization/divisions/{divisionId}/objects/{objectType}

/api/v2/authorization/divisions/home

/api/v2/authorization/divisions/limit

/api/v2/authorization/divisionspermitted/{subjectId}

/api/v2/authorization/divisionspermitted/me

/api/v2/authorization/roles/{roleId}/subjectgrants

/api/v2/authorization/subjects/{subjectId}

/api/v2/authorization/subjects/{subjectId}/divisions/{divisionId}/roles/{roleId}

/api/v2/authorization/subjects/me

Architect
/api/v2/flows/divisionviews

Outbound Dialing
/api/v2/outbound/campaigns/divisionviews

/api/v2/outbound/contactlists/divisionviews

/api/v2/outbound/contactlists/divisionviews/{contactListId}

/api/v2/outbound/dnclists/divisionviews

/api/v2/outbound/dnclists/divisionviews/{dncListId}

Workforce Management
/api/v2/workforcemanagement/managementunits/divisionviews

Routing
/api/v2/routing/queues/divisionviews

7

How is this change going to be implemented? I mean, by the time it goes live, is this going to be soft enough, so that it doesn't prevent current credentials from accessing the currently accessed objects/data? In other words, until I have my access control fine-grained up to divisions, will my current "Outbound Admin" role work normally?

Thanks

8

On go-live, everything works the same as it is today. Everything is in a home division and everyone (including client credentials apps) have access to everything in the home division. Things will only change when objects are moved into a division then the client credentials app will not be able to view that object

9

Perfect. Thank you very much for clarifying this.

10

KevinGlinski said:
"On go-live, everything works the same as it is today."

Becky_Powell said:
"Upon release of Fine-Grained Access Control, the following permissions will include division IDs as an additional "level" of the permission. If your app is currently checking for any of these permissions, it will need to be updated to account for the additional granularity."

Just trying to get my head around this, and not sure if I'm reading it the right way (and maybe I just need another coffee).

So if I require one of the listed permissions, say analytics:conversationAggregate:view in order to call POST /api/v2/analytics/conversations/aggregates/query then there's no change required because the Role with that permission will automatically be included into a Home division? However if I introduce a new division, I'll need to update the grants via something like POST /api/v2/authorization/subjects/{subjectId}/divisions/{divisionId}/roles/{roleId}?

11

Hi Kevin,
our Purecloud Organization was enabled to use ACL Features in Beta Version.
We have moved Queues, Calling Lists, Campaigns and Agents from Home division to another one and now we are not able to call some Purecloud REST API (such as GET /api/v2/outbound/campaigns ) from an OAuth Client Application. How can we grant a OAuth Client Application to some specific divisions?
In our experience we have seen that PureCloud Data Actions have the same problem trying to call some Purecloud REST API (such as GET /api/v2/analytics/conversations/{conversationId}/details).

12

which oauth type? Client credentials are not currently supported with divisions

13

that is correct

1 Like
14

Yes, OAuth Client Credential.
From Purecloud documentation Purecloud Data Action supports only OAuth Client Credential (https://help.mypurecloud.com/articles/add-a-purecloud-oauth-client-for-integrations/); how can we solve this issue?
On go-live it will be possibile to associate OAuth client credential with different divisions ad not only with the Home one?
Which type of authorization we have to use for server-side applications (to be compliant with divisions implemetation)?

15

work is in progress to get them working with divisions, no ETA on that. If you depend on client credentials then you most likely won't be able to use divisions when it goes live. If you aren't planning on using divisions then your client credential apps will continue to work as is.

16

Our clients wants to work with divisions and at least the standard Feature of PureCloud Data Action must work with OAuth Client Credential.

17

Hi Matteo,

We understand your sense of urgency. As Kevin mentioned, we're actively working to support Client Credentials with divisions (Fine Grained Access Control). We will keep you posted as we make progress and will communicate a timeline to completion shortly.

Thank you,
Becky

18

Just published a video demonstrating how divisions can impact API calls https://youtu.be/9oAaQmIhy-0

19

Developer FAQs - Fine-Grained Access Control

Here are answers to some of the common questions we've received from developers about the upcoming FGAC changes:

  1. Can we test the new functionality in our developer account?
    Yes! We can enable FGAC in your test account. Reply to this post to request early access.

  2. If my organization intends to use FGAC to limit access to certain objects, what changes should I expect to need to make to my application?
    a. If you're using the Client Credential OAuth grant type, you will need to grant the OAuth client access to all divisions to which you want the client to have object access.
    b. If you're using the PureCloud API to check or assign roles and permissions, you will need to use the new authorization actions.
    c. If your app is making calls that require any of these permissions, it may need to updated to account for divisions.
    d. If your app makes calls to fetch FGAC objects in bulk, you may want to call the new divisionview endpoints to get simplified lists of objects irrespective of division.

  3. What will change on go-live date?
    a. PureCloud will create a default Home Division within every organization. All FGAC-aware objects (Queues, campaigns, contact lists & DNC lists, users, workforce management units, and architect flows) will initially be placed into that Home Division, and all users will have access to all objects until the organization creates additional divisions and places objects with them.

    b. Some responses you receive from the PureCloud will change:
    b1. Certain permission strings will now be appended with the guid of the division(s) in which the permission is granted, even if the only division in the organization is the default home division. For example, a call that previously returned the permission routing:queue:view will now return the permission routing:queue:view:aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa (aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa being the division ID.)
    b2. Certain objects will now include the object's division ID, name, and selfUri.
    b3. There will be no further impact to any client application in Production unless and until its respective org places an object within a division, in which case the client credentials app will not be able to view that object

  4. If my app runs in the context of a user (e.g. implicit grant, code authorization, or SAML2 bearer), is there anything I need to do to make sure that my app behaves like it did pre-change?
    No, as long as the user has access to applicable divisions.

  5. How can I see what division an object is in?
    a. Use the new /divisionviews resources to get simple lists of objects and their associated division. (Example: call GET /api/v2/outbound/campaigns/divisionviews to fetch a simplified list of all campaigns, including campaigns in divisions you don't have access to.
    b. The preexisting routes like /api/v2/routing/queues etc will also show the divisions.

  6. What can I do to ensure that my application can access all objects, regardless of division, in perpetuity?
    Grant your subject (the authenticating user who is making requests) access to all divisions and all future divisions by using POST /api/v2/authorization/roles/{roleId} with a body: { "subjectIds": [ "{user or group id}" ], "divisionIds": [ "{divisionid}" ] } (you can use * for the divisionId.)


If you have a question we haven't addressed here, please let us know!
20

Hi Becky,
Would like to have this enabled on our dev org.
I will message you directly the org details and region.
Many thanks,
Jean-Christophe