Skip to main content
Version: 2023.1

Scopes and permissions

Introduction

Each application has a defined set of scopes that it can request when generating an access token, allowed scopes will be used to limit access through the token.

Scopes

We have to start by configuring the scopes, this can be done via the admin panel. After upgrading the version, old applications will have all the scopes required to work as before. In the edition of the REST application under the secrets, we should have the Application permissions (scopes) section available, we will use it to manage scopes.

List of allowed scopes contains:

  • name - actual scope that we will use in the token request
  • description - a brief description of the possible use
  • remove button
  • detailed info button - this information will also contain a list of applications with appropriate permissions to use this scope

Information on what scopes are required for specific endpoints can be found in our swagger under each endpoint description.

Information about granted scopes is stored in the token, so we have to request specific scopes during authentication. We can request any number of scopes, if we don't, we will get a token with all the scopes available for the specific API application.

Below is example request in curl:

curl -X POST "http://dev20/WEBCONBPS/api/oauth2/token" 
-H "accept: text/plain”
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=2be2fd55-5662-4507-b255-1558a7ab9786&client_secret=2tLryMUReamB01Lh7Zwww1ud2qGiWQMRwgc%2F800xub4%3D&
scope=Admin.ReadWrite.All App.Elements.Read.All"

We have divided the scopes into several logical groups. Each of these groups will require a different permission set and application type:

AppContext Admin scopes

It mainly applies to scopes for endpoints from the PublicApiAdmin group. They are only available to applications of App context type. These endpoints previously required global administrator privileges, and are now only available with an appropriate scope.

Below is list of these scopes:

Admin.ReadWrite.All Access to all administrative endpoints (groups, users, licenses, business entities, data connections, constants, substitutions, URLs).

Admin.Read.All Read only access to all administrative endpoints (groups, users, licenses, business entities, data connections, constants, substitutions, URLs).

Admin.BusinessEntities.Read Read business entities list and properties.

Admin.Groups.Read Read local groups and list group members.

Admin.Groups.ReadWrite Read, add, update and delete local groups. List, add and remove group membership.

Admin.Licenses.Read Read information about currently assigned licenses (Cloud installation type only).

Admin.Licenses.ReadWrite Read information about currently assigned licenses and assign licenses to users (Cloud installation type only).

Admin.Users.Read Read BPS defined (external) users profiles.

Admin.Users.ReadWrite Read, add, update and delete BPS defined (external) users.

Admin.Connections.Read Read list of data connections and basic connection properties.

Admin.Connections.ReadWrite Read, add, and update data connections.

Admin.Constants.Read Read global constants.

Admin.Constants.ReadWrite Read, add and update global constants.

Admin.ProcessConstants.Read Read process constants in all processes.

Admin.ProcessConstants.ReadWrite Read, add and update process constants in all processes.

Admin.Read.Urls Access to basic information of all instances based on URL addresses.

Admin.Substitutions.Read Read substitutions.

Admin.Substitutions.ReadWrite Read, add, update and delete substitutions.

AppContext App scopes

These scopes are also only available to applications of the App context type. They are used in Elements, Metadata, Reports and Tasks. Endpoints that require these scopes will also require the appropriate permissions. So, for example, to start an instance, the application will have to have the appropriate scope and permissions to start instances in a given process. Metadata endpoints require application-level permissions, while others require process-level permissions.

App.Metadata.Read Read metadata of applications and processes. Additional read permissions on each application are required.

App.Metadata.ReadWrite Read metadata of applications and processes. Set application and process privileges. Additional read or admin permissions on each application are required.

App.Reports.Read.All Read reports’ and views’ content in all applications. Additional read permissions on each report are required.

App.Tasks.Read.All Read tasks assigned to the registered API application.

App.Elements.Read.All Read workflow instances in all processes (form fields, attachments and metadata). Additional read permissions on each instance are required.

App.Elements.ReadWrite.All Read, start new and update workflow instances in all processes (form fields, attachments and metadata). Additional read, update or start new permissions on each instance are required.

App.Elements.Admin.All Read, start new, update and delete workflow instances in all processes (form fields, attachments and metadata). Change instance permissions and delegate tasks. Additional permissions on each instance are required.

UserContext scopes

These scopes are available only to User Context applications, and endpoints will use the permissions of the user on whose behalf the application is running. Several scopes below contain the \<AppGuid> or \<ProcGuid> part. In the correct scope it will be replaced with the appropriate guid and will only grant permissions for the related process or application

User.Reports.Read.All Read reports’ and views’ contents on behalf of the signed-in user.

User.Reports.Read.\<AppGuid> Read reports’ and views’ contents in the specified application on behalf of the signed-in user.

User.Tasks.Read.All Read tasks in all applications on behalf of the signed-in user.

User.Tasks.Read.\<AppGuid> Read tasks in the specified application on behalf of the signed-in user.

User.Elements.Read.All Read workflow instances in all processes (form fields, attachments and metadata) on behalf of the signed-in user.

User.Elements.Read.\<ProcGuid> Read workflow instances in the specified process (form fields, attachments and metadata) on behalf of the signed-in user.

User.Elements.ReadWrite.All Read, start new and update workflow instances in all processes (form fields, attachments and metadata) on behalf of the signed-in user.

User.Elements.ReadWrite.\<ProcGuid> Read, start new and update workflow instances in the specified process (form fields, attachments and metadata) on behalf of the signed-in user.

User.Elements.Admin.All Read, start new, update, change permissions, delegate tasks and delete workflow instances in all processes (form fields, attachments and metadata) on behalf of the signed-in user.

User.Elements.Admin.\<ProcGuid> Read, start new, update, change permissions, delegate tasks and delete workflow instances in the specified process (form fields, attachments and metadata) on behalf of the signed-in user.

Other\special scopes

For now, this group only contains one scope which does not require any other permissions and only applies to the endpoint /api/data/beta/me. This scope is available to both types of application.

User.Data View users’ basic profile.

OpenId scopes

These scopes can only be used by UserContext applications and cannot be combined with the scopes listed above. They allow external systems to use WEBCON BPS as an OpenId Connect authentication server.

openid Necessary for the external system to be able to use WEBCON BPS as the OpenId Connect authentication server.

email Returns additional information about the user's email during OpenId Connect authentication.

profile Returns additional information about the user's display name during OpenId Connect authntication.