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.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

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, when type = extension. Note that these endpoints, when type = 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.

A custom role for applications can contain functional privileges (such as the Advanced Application privilege), endpoint privileges, or both. (Roles can also have security criteria and generic access rights, but these apply only to internal users and have no effect on applications.) The following example creates a custom role called CustomAppRole1 and gives it the Extensions privilege and the Admin Bulk Export Endpoint Privilege:

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.