docs: Custom Applications multiple permissions (#2806)

* docs: add Custom Applications multiple permissions docs

* docs: group name constraints

* docs: development

* docs: example permission names table

* docs: default oAuth Scopes can be empty if additional configured

* docs: code review improvements

* docs: remove vague content

* docs: rephrase

* docs: improvements

* docs: punctuation

* docs: fix sentence logic

* chore: release notes

* chore: release notes improvements

* docs: improvements

* docs: final improvements

* docs: update release note date

Co-authored-by: Nicola Molinari <nicola.molinari@commercetools.com>

website/src/content/api-reference/application-config.mdx

@@ -323,11 +323,13 @@ The configuration for [OAuth Scopes and user permissions](/concepts/oauth-scopes
 
 You can have "view-only" or "manage-only" OAuth Scopes and leave the other list field empty, as long as at least one OAuth Scope is specified.
 
+Alternatively, if at least one additional permission group is configured in [additionalOAuthScopes](#additionaloauthscopes),  both "view-only" or "manage-only" OAuth Scopes list fields can be left empty.
+
 </Info>
 
 ## `oAuthScopes.view`
 
-A list of "view-only" [OAuth Scopes](https://docs.commercetools.com/api/scopes) required by the Custom Application and associated to the `View` permission.
+A list of "view-only" [OAuth Scopes](https://docs.commercetools.com/api/scopes) required by the Custom Application and associated with the `View` permission.
 
 ```json
 {
@@ -355,6 +357,78 @@ Using `manage_` OAuth Scopes always imply the corresponding `view_` OAuth Scope.
 
 </Info>
 
+## `additionalOAuthScopes`
+
+<Info>
+
+This feature is available from version `21.21.0` onwards.
+
+</Info>
+
+The optional configuration for defining more granular [OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions#permission-groups).
+
+## `additionalOAuthScopes.*.name`
+
+A unique name for the additional permission group.
+
+```json
+{
+  "additionalOAuthScopes": [
+    {
+      "name": "movies",
+    }
+  ]
+}
+```
+
+The name value must adhere to the following restrictions:
+
+* Only lowercase alphabetic characters are allowed.
+* Must be between 2 and 64 characters.
+* Hyphens are allowed except as leading, trailing, and adjacent characters.
+
+## `additionalOAuthScopes.*.view`
+
+A list of "view-only" [OAuth Scopes](https://docs.commercetools.com/api/scopes) required by the Custom Application and associated with the `View<GroupName>` permission.
+
+```json
+{
+  "additionalOAuthScopes": [
+    {
+      "name": "movies",
+      "view": ["view_products"],
+      "manage": []
+    },
+    {
+      "name": "merch",
+      "view": ["view_categories"],
+      "manage": []
+    }
+  ]
+}
+```
+
+## `additionalOAuthScopes.*.manage`
+
+A list of "manage-only" [OAuth Scopes](https://docs.commercetools.com/api/scopes) required by the Custom Application and associated with the `Manage<GroupName>` permission.
+
+```json
+{
+  "additionalOAuthScopes": [
+    {
+      "name": "movies",
+      "view": [],
+      "manage": ["manage_products"]
+    },
+    {
+      "name": "merch",
+      "view": [],
+      "manage": ["manage_categories"]
+    }
+  ]
+}
+```
+
 ## `headers`
 
 An optional object to configure HTTP headers used by the Custom Application.

website/src/content/concepts/oauth-scopes-and-user-permissions.mdx

@@ -30,19 +30,67 @@ Notice here how the OAuth Scopes are grouped by the two fields `view` and `manag
 
 This grouping determines the **mapping and relation between OAuth Scopes and user permissions**.
 
+## Permission groups
+
+Every Custom Application has a **default permission group** with a pair of view and manage permissions. This group maps to the OAuth Scopes specified in the [oAuthScopes](/api-reference/application-config#oauthscopes) field of the Custom Application config.
+
+However, you might need more granular access control to fulfill specific business requirements. Suppose your Custom Application manages products, discounts, and orders, and you want a group of users to only manage products and discounts while another group handles orders. <br />
+In this scenario, more than one permission group (the default one) is needed to fulfill the access requirements.
+
+You can define additional permission groups with different access requirements to enable such use cases. See [additionalOAuthScopes](/api-reference/application-config#additionaloauthscopes) field in the Custom Application config. 
+
+<Info>
+
+This feature is available from version `21.21.0` onwards.
+
+</Info>
+
+In the following example, we're defining two additional permission groups. The group `delivery` allows users to manage incoming orders, while the group `promotion` enables users to work on discount and promotion campaigns.
+
+```json title="custom-application-config.json" highlightLines="6-17"
+{
+  "oAuthScopes": {
+    "view": ["view_products", "view_customers"],
+    "manage": ["manage_products"]
+  },
+  "additionalOAuthScopes": [
+    {
+      "name": "delivery",
+      "view": [],
+      "manage": ["manage_orders"]
+    },
+    {
+      "name": "promotion",
+      "view": [],
+      "manage": ["manage_orders", "manage_discount_codes"]
+    }
+  ]
+}
+```
+
+<Info>
+
+The default permission group is always defined, even when adding additional groups.
+
+When additional groups are defined, the default group can be left empty without specifying any OAuth Scopes.
+
+But still, at least one "view-only" user permission must be enabled to access the Custom Application.
+
+</Info>
+
 # User permissions
 
 In the Merchant Center, you can assign user permissions to Teams to grant or restrict access to certain parts and functionalities of the Merchant Center. See [user permissions in Merchant Center](https://docs.commercetools.com/merchant-center/user-permissions) for more information.<br />
 The same concepts apply for Custom Applications as well. Once your Custom Application has been installed in your Organization, you can assign user permissions for your Custom Application to each specific Team.
 
-Each Custom Application gets a **unique pair** of user permissions: "view" and "manage."
+Each Custom Application gets **unique** "view" and "manage" permissions.
 
 * When assigning "view"-only permission to a Team, only the `view_` OAuth Scopes are used to authorize API requests.
 * When assigning "manage" permission to a Team, both `view_` and `manage_` OAuth Scopes are used to authorize API requests.
 
 <Info>
 
-The permission names are unique to each Custom Application and they derive from the `entryPointUriPath`, based on the following format: `{View,Manage}<EntryPointUriPath>`.
+The permission names are unique to each Custom Application, and, by default, they derive from the `entryPointUriPath`, based on the following format: `{View,Manage}<EntryPointUriPath>`.
 
 Here are some examples:
 
@@ -54,6 +102,15 @@ Here are some examples:
 | `avengers-01` | `{View,Manage}Avengers/01` |
 | `avengers_01` | `{View,Manage}Avengers_01` |
 
+When using additional permission groups, the permission name is derived from the `entryPointUriPath` (same as the default group) plus the group name, based on the following format: `{View,Manage}<EntryPointUriPath><GroupName>`
+
+Here are some examples:
+
+| `entryPointUriPath` | Permission group name | User permission |
+| --- | --- | --- |
+| `avengers` | `thor` | `{View,Manage}AvengersThor` |
+| `the-avengers` | `iron-man` | `{View,Manage}TheAvengersIronMan` |
+
 </Info>
 
 Ultimately, user permissions should be applied and enforced in the actual Custom Application code. For example to restrict access to certain pages, or to deactivate a button, etc.

website/src/content/development/permissions.mdx

@@ -2,7 +2,7 @@
 title: Permissions
 ---
 
-As we learned in [OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions), each Custom Application has a unique pair of user permissions at its disposal: "view" and "manage."
+As we learned in [OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions), each Custom Application has a unique pair of default user permissions at its disposal: "view" and "manage." Additionally, you can use more granular permission groups to cover strict business requirements.
 
 The values of the user permissions are derived from the application `entryPointUriPath`.
 
@@ -27,6 +27,41 @@ The `PERMISSIONS` variable contains a `View` and `Manage` properties, with the v
 
 You can then use the `PERMISSIONS` variable to reference the permission in the application code.
 
+<Info>
+
+This feature is available from version `21.21.0` onwards.
+
+When using additional permission groups, you must also provide the unique group to the `entryPointUriPathToPermissionKeys` function to generate the correct permission keys.
+
+The group names can be exported and referenced also in the Custom Application config file.
+
+```js title="constants.js" highlightLines="5-8, 12"
+import { entryPointUriPathToPermissionKeys } from '@commercetools-frontend/application-shell/ssr';
+
+export const entryPointUriPath = 'channels';
+
+export const groupNames = {
+  delivery: 'delivery',
+  promotion: 'promotion',
+};
+
+export const PERMISSIONS = entryPointUriPathToPermissionKeys(
+  entryPointUriPath,
+  ['delivery', 'promotion']
+);
+```
+
+In this scenario, the `PERMISSIONS` variable contains a `View`, `Manage`, `ViewDelivery`, `ManageDelivery`, `ViewPromotion` and `ManagePromotion` properties, with the values being the computed values based on the `entryPointUriPath` and the provided permission group names:
+
+* `PERMISSIONS.View`: maps to `ViewChannels`.
+* `PERMISSIONS.Manage`: maps to `ManageChannels`.
+* `PERMISSIONS.ViewDelivery`: maps to `ViewChannelsDelivery`.
+* `PERMISSIONS.ManageDelivery`: maps to `ManageChannelsDelivery`.
+* `PERMISSIONS.ViewPromotion`: maps to `ViewChannelsPromotion`.
+* `PERMISSIONS.ManagePromotion`: maps to `ManageChannelsPromotion`.
+
+</Info>
+
 # Applying user permissions
 
 A Custom Application allows, for example, to check and evaluate if certain user permissions are assigned or not, making it possible to determine whether to render something or not, or to turn off some UI functionalities.

website/src/releases/2022-12/custom-applications-multiple-permissions.mdx

@@ -0,0 +1,16 @@
+---
+date: 2022-12-09
+title: Custom Applications multiple permissions
+description: Introducing more granular permissions for Custom Applications.
+type: feature
+topics:
+  - Merchant Center
+  - Configuration
+  - CLI
+---
+
+The Application Kit packages have been released with a minor version `v21.21.0`.
+
+Custom Applications now allow defining more granular OAuth Scopes and user permissions to cover more specific business requirements. You can create [multiple permission groups](/concepts/oauth-scopes-and-user-permissions#permission-groups) and [assign different OAuth Scopes](/concepts/oauth-scopes-and-user-permissions#oauth-scopes) to them. These permission groups can then be [assigned to teams](/merchant-center/managing-custom-applications#assigning-team-permissions) in a more granular way.
+
+As always, if you have questions or feedback, you can open a [GitHub Discussion](https://github.com/commercetools/merchant-center-application-kit/discussions) or a [GitHub Issue](https://github.com/commercetools/merchant-center-application-kit/issues).