Understand access control for applications
The access control system for internal users can also be used to manage access for registered applications such as integrations and server-side extensions.
When an application is registered in the administration interface, it is automatically assigned a role that provides it access to a wide range of Commerce endpoints on the administration server. If you want to restrict the application's access, you can remove this role from the application and assign a custom role to it that provides access to only specific endpoints.
Default role and privileges
A predefined role, Advanced Application plus Extensions (role ID = ora.advancedApplicationPlusExtensionsRole), is assigned to each registered application by default. This role contains two privileges that provide access to a broad range of functionality in Commerce:
- The Advanced Application privilege (privilege ID = ora.advancedApplicationPrivilege), confers access to many (but not all) of the endpoints that an internal user with the Administrator privilege can access.
- The Extensions privilege (privilege ID = ora.extensionsPrivilege), confers access to certain endpoints for managing extensions.
These privileges are designed to be used only by registered applications and should not be assigned to internal users. For information about predefined roles and privileges intended for internal users, see Use and modify roles for internal users.
Manage extensions from applications
The access provided by the Extensions privilege and the Advanced Application privilege include the ability to call certain Admin API endpoints for managing extensions:
- The Extensions privilege provides access to the
/ccadmin/v1/applicationIds
endpoints, whentype
=extension
. Note that these endpoints, whentype
=application
, cannot be accessed by applications. - The Advanced Application provides access to the
/ccadmin/v1/extensions
endpoints.
Endpoint privileges
Commerce includes a special type of privilege for use by applications, called an endpoint privilege, that you can include in custom roles to grant access to specific endpoints. You cannot create new endpoint privileges, but you can use one or more of the predefined endpoint privileges, which are described in the table below. Note that these endpoints omit any PCI (credit card) data when invoked from an application.
If an endpoint has an associated endpoint privilege, an application with that endpoint privilege has access to the endpoint, regardless of what other privileges the application has. If an application does not have the endpoint privilege, the application might still have access to the endpoint, depending on the functional privileges it has. For example, the Advanced Application privilege confers access to many endpoints.
Endpoint Privilege Name | Endpoint Privilege ID | Associated Endpoint |
---|---|---|
Admin Bulk Export Endpoint Privilege | endpoint.ccadmin.executeExport | POST
/ccadmin/v1/exportProcess |
Admin Get Export Status Endpoint Privilege | endpoint.ccadmin.getExportProcess | GET
/ccadmin/v1/exportProcess/{token} |
Admin Abort Export Endpoint Privilege | endpoint.ccadmin.abortExportProcess | POST
/ccadmin/v1/exportProcess/{token}/abort |
Admin Get Shopper Type Properties Endpoint Privilege | endpoint.ccadmin.getShopperType | GET
/ccadmin/v1/shopperTypes/{id} |
Admin Get Item Type Properties Endpoint Privilege | endpoint.ccadmin.getItemType | GET
/ccadmin/v1/itemTypes/{id} |
Admin List Promotions Endpoint Privilege | endpoint.ccadmin.listPromotions | GET /ccadmin/v1/promotions |
Admin List Sites Endpoint Privilege | endpoint.ccadmin.getSites | GET /ccadmin/v1/sites |
Admin Get Site Endpoint Privilege | endpoint.ccadmin.getSite | GET /ccadmin/v1/sites/{id} |
Create custom roles for applications
To confer more limited access to an application than the predefined
Advanced Application plus Extensions role allows, you can use the
createAdminRole
endpoint in the Admin API to create custom
roles. You then assign one or more of these roles to the application, and remove the
Advanced Application plus Extensions role from the application.
POST /ccadmin/v1/adminRoles HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en
{
"repositoryId": "CustomAppRole1",
"accessRights": [
{
"repositoryId": "ora.extensionsPrivilege"
},
{
"repositoryId": "endpoint.ccadmin.executeExport"
}
],
"name": "CustomAppRole1"
}
The response looks similar to this:
{
"securityCriteria": [],
"name": "CustomAppRole1",
"repositoryId": "CustomAppRole1",
"description": null,
"links": [
{
"rel": "self",
"href": "http://www.example.com:7002/ccadmin/v1/adminRoles"
}
],
"accessRights": [
{
"displayName": "Admin Bulk Export Endpoint Privilege",
"name": "Admin Bulk Export Endpoint Privilege",
"repositoryId": "endpoint.ccadmin.executeExport",
"description": "POST /ccadmin/v1/exportProcess Endpoint Privilege ",
"id": "endpoint.ccadmin.executeExport",
"type": "endpoint"
},
{
"displayName": "Extensions",
"name": "Extensions",
"repositoryId": "ora.extensionsPrivilege",
"description": "Confers the ability to update and delete extensions.",
"id": "ora.extensionsPrivilege",
"type": "privilege"
}
],
"securityCriteriaLastModified": null,
"id": "CustomAppRole1",
"category": "Custom"
}
Assign roles to an application
To register a new application and assign roles to it, you use the
createApplicationID
endpoint in the Admin API. For example:
POST /ccadmin/v1/applicationIds HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en
{
"name": "MyApp",
"type": "application",
"roles": [
"CustomAppRole1"
]
}
The response looks similar to this:
{
"creationTime": "2021-11-08T16:30:53.000Z",
"roles": [
{
"repositoryId": "CustomAppRole1"
}
],
"source": "custom",
"type": "application",
"token": "<application_key>",
"external": false,
"createdBy": {
"firstName": "Amber",
"lastName": "Admin",
"repositoryId": "admin",
"id": "admin"
},
"repositoryId": "71ca5c5d-3e08-46cd-9781-b531ac67ea13",
"name": "MyApp",
"inUse": false,
"links": [
{
"rel": "self",
"href": "http://www.example.com:7002/ccadmin/v1/applicationIds"
}
],
"id": "71ca5c5d-3e08-46cd-9781-b531ac67ea13",
"createdById": null
}
Notice that the response includes two key identifiers for the application: the
token
property, which contains the application key, and the
id
property, which contains the internal ID for the
application.
You can also register an application in the administration interface, as
described in Register applications. If you register applications this way, or if you have existing
applications you want to assign roles to, you can use the
updateApplicationID
endpoint in the Admin API to assign roles.
The request and response payloads for this endpoint are similar to the payload for
createApplicationID
. For example, to assign a custom role named
CustomAppRole2 to the MyApp application shown above:
PUT /ccadmin/v1/applicationIds/71ca5c5d-3e08-46cd-9781-b531ac67ea13 HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en
{
"name": "MyApp",
"type": "application",
"roles": [
"CustomAppRole2"
]
}
When you use the updateApplicationID
endpoint to add
roles to an application, the roles you specify replace any roles currently assigned.
If you want the application to retain the roles previously assigned to it, be sure
to include them in the request payload. In the example above, if you want to add
CustomAppRole2 without removing CustomAppRole1, you need to specify both roles in
the request.
Note: When you register an application, if you do not explicitly specify
roles, the application is automatically assigned several predefined internal user
roles, plus the Advanced Application plus Extensions role. This is true for any
applications you register in the administration interface, and for applications you
register using the createApplicationID
endpoint without specifying
roles. It is also true for existing applications you registered previously without
specifying roles.
The internal roles are included for backward compatibility reasons and are not
functional for registered applications. If you subsequently assign roles to an
application using the updateApplicationID
endpoint, these roles are
removed.
Limitations on custom access control
The access control system does not provide a way for code within your application to check what roles or access rights are assigned to the application. Therefore, your application cannot use roles or the access rights they contain to control access to its custom functionality. Access to functionality that Commerce provides, however, will be enforced based on the privileges that the application's roles contain.