docs: Custom Applications multiple permissions #2806
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
kark
changed the title
|
Deploy preview for merchant-center-application-kit ready! ✅ Preview Built with commit 17ac6c9. |
kark
force-pushed
the
multiple-permissions-docs
branch
from
2e3ad2b
to
b75ba02
Compare
emmenko
reviewed
Nov 22, 2022
| @@ -355,6 +357,68 @@ Using `manage_` OAuth Scopes always imply the corresponding `view_` OAuth Scope. | |||
|
|
|||
| </Info> | |||
|
|
|||
| ## `additionalOAuthScopes` | |||
|
|
|||
| The configuration for [additional OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions#additional-oauth-scopes) extending [oAuthScopes configuration](#oauthscopes). | |||
There was a problem hiding this comment.
Suggested change
| The configuration for [additional OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions#additional-oauth-scopes) extending [oAuthScopes configuration](#oauthscopes). | |
| <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#additional-oauth-scopes). |
Comment on lines
366
to
368
| A name used to build the permission keys based on the default permissions pair. | ||
|
|
||
| The `additionalOAuthScopes.name` value must adhere to the following restrictions: |
There was a problem hiding this comment.
Let's try to use the same terminology "permission group" to make it easier for users to relate things to each other.
Suggested change
| A name used to build the permission keys based on the default permissions pair. | |
| The `additionalOAuthScopes.name` value must adhere to the following restrictions: | |
| A unique name for the additional permission group. | |
| ```json | |
| { | |
| "additionalOAuthScopes": [ | |
| { | |
| "name": "movies", | |
| } | |
| ] | |
| } | |
| ``` | |
| The name value must adhere to the following restrictions: |
|
|
||
| The configuration for [additional OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions#additional-oauth-scopes) extending [oAuthScopes configuration](#oauthscopes). | ||
|
|
||
| ## `additionalOAuthScopes.name` |
There was a problem hiding this comment.
Suggested change
| ## `additionalOAuthScopes.name` | |
| ## `additionalOAuthScopes.*.name` |
Comment on lines
395
to
397
| ## `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` permission scoped to the respective permission group. |
There was a problem hiding this comment.
Suggested change
| ## `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` permission scoped to the respective permission group. | |
| ## `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. |
Comment on lines
374
to
376
| ## `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` permission scoped to the respective permission group. |
There was a problem hiding this comment.
Suggested change
| ## `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` permission scoped to the respective permission group. | |
| ## `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. |
| @@ -27,6 +29,36 @@ 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> | |||
There was a problem hiding this comment.
Suggested change
| <Info> | |
| <Info> | |
| This feature is available from version `21.21.0` onwards. |
| @@ -2,12 +2,14 @@ | |||
| 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." | |||
There was a problem hiding this comment.
I think we can simply mention the additional groups here in the intro.
Suggested change
| 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." | |
| 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, more granular permission groups can be used to cover more strict business requirements. |
|
|
||
| The values of the user permissions are derived from the application `entryPointUriPath`. | ||
|
|
||
| When developing a Custom Application you might want to enforce these user permissions in some parts of your application. For example, performing certain actions like creating, updating, or deleting a resource should only be possible if the user has "manage" permission. | ||
|
|
||
| Furthermore, more granular additional permissions can optionally be used, for example, to allow the team access to only certain parts or functionality of the Custom Application. |
There was a problem hiding this comment.
Can be removed, see suggestion for the intro section.
Suggested change
| Furthermore, more granular additional permissions can optionally be used, for example, to allow the team access to only certain parts or functionality of the Custom Application. |
| @@ -27,6 +29,36 @@ 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> | |||
|
|
|||
| To leverage the optional, more granular permissions, a distinctive name has to be introduced for each of the permission groups. | |||
There was a problem hiding this comment.
Suggested change
| To leverage the optional, more granular permissions, a distinctive name has to be introduced for each of the permission groups. | |
| When using additional permission groups, the unique group names should be provided to the `entryPointUriPathToPermissionKeys` function to generate the correct permission keys. | |
| The group names can be exported and referenced also int he Custom Application config file. |
Comment on lines
41
to
51
| export const teamA = "team-a"; | ||
|
|
||
| export const teamB = "team-b"; | ||
|
|
||
| export const PERMISSIONS = entryPointUriPathToPermissionKeys( | ||
| entryPointUriPath, | ||
| [teamA, teamB] | ||
| ); |
There was a problem hiding this comment.
Nit: maybe we can define the names as an constants object.
Suggested change
| export const teamA = "team-a"; | |
| export const teamB = "team-b"; | |
| export const PERMISSIONS = entryPointUriPathToPermissionKeys( | |
| entryPointUriPath, | |
| [teamA, teamB] | |
| ); | |
| export const groupNames = { | |
| teamA: 'team-a', | |
| teamB: 'team-b', | |
| }; | |
| export const PERMISSIONS = entryPointUriPathToPermissionKeys( | |
| entryPointUriPath, | |
| [groupNames.teamA, groupNames.teamB] | |
| ); |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| @@ -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, more granular permission groups can be used to cover more strict business requirements. | |||
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Google.Quotes] Commas and periods go inside quotation marks.
kark
force-pushed
the
multiple-permissions-docs
branch
2 times, most recently
from
a8a494e
to
1114961
Compare
CarlosCortizasCT
approved these changes
Nov 24, 2022
| @@ -42,7 +81,7 @@ Each Custom Application gets a **unique pair** of user permissions: "view" and " | |||
|
|
|||
| <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>`. | |||
There was a problem hiding this comment.
We have this sentence above:
Each Custom Application gets a unique pair of user permissions: "view" and "manage."
I'm wondering if we should update that because a Custom Application using additionalOAuthScopes will not only get one pair of user permissions.
There was a problem hiding this comment.
Good point, we should maybe rephrase that section yes.
emmenko
reviewed
Nov 24, 2022
| @@ -30,6 +30,45 @@ 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 | |||
There was a problem hiding this comment.
Nit: I would make it a subsection
Suggested change
| # Permission groups | |
| ## Permission groups |
Comment on lines
35
to
39
| <Info> | ||
|
|
||
| This feature is available from version `21.21.0` onwards. | ||
|
|
||
| </Info> |
There was a problem hiding this comment.
I think this should be placed where we mention the additional groups, as otherwise it seems like all permission groups are something new.
|
|
||
| </Info> | ||
|
|
||
| Defining `oAuthScopes` in the Custom Application config yields the default permision group which allows using permissions limited to 1 unique pair (view/manage) specific to the Custom Application. The default permission pair can cover access control needs of Custom Applications intended to be used by one team. |
There was a problem hiding this comment.
I would start the introduction of this section by explaining what the group is and that there is a default one.
Suggested change
| Defining `oAuthScopes` in the Custom Application config yields the default permision group which allows using permissions limited to 1 unique pair (view/manage) specific to the Custom Application. The default permission pair can cover access control needs of Custom Applications intended to be used by one team. | |
| 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. |
Comment on lines
45
to
47
| For more granular permissions [additional OAuth Scopes](https://docs.commercetools.com/api/scopes) can be requested as part of various additional permission groups. | ||
|
|
||
| These additional OAuth Scopes must be specified in your Custom Application config, using the [`additionalOAuthScopes` field](/api-reference/application-config#additionaloauthscopes). |
There was a problem hiding this comment.
Here I would then mention the version requirement:
Suggested change
| For more granular permissions [additional OAuth Scopes](https://docs.commercetools.com/api/scopes) can be requested as part of various additional permission groups. | |
| These additional OAuth Scopes must be specified in your Custom Application config, using the [`additionalOAuthScopes` field](/api-reference/application-config#additionaloauthscopes). | |
| To enable such use cases, you can define additional permission groups that have different access requirements. 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> |
|
|
||
| Defining `oAuthScopes` in the Custom Application config yields the default permision group which allows using permissions limited to 1 unique pair (view/manage) specific to the Custom Application. The default permission pair can cover access control needs of Custom Applications intended to be used by one team. | ||
|
|
||
| However, in certain cases more granular access control is needed. For example, if multiple teams accross the organization have access to a Custom Application but only one team is allowed to manage discount codes, the default permission pair is not enough. |
There was a problem hiding this comment.
Suggested change
| However, in certain cases more granular access control is needed. For example, if multiple teams accross the organization have access to a Custom Application but only one team is allowed to manage discount codes, the default permission pair is not enough. | |
| However, you might need more granular access control to fulfil specific business requirements. For example, if your Custom Application manages products, discounts and orders, you might want only a group of users to manage products and discounts while another group of users handles orders.<br /> | |
| In this kind of scenario a single permission group (the default one) is not enough as you would need multiple permission groups fulfil the access requirements. |
Comment on lines
49
to
69
| In the following example, permission group named `team-a` allows to manage orders but not manage discount codes, while permission group named `team-b` allows both. | ||
|
|
||
| ```json title="custom-application-config.json" highlightLines="6-17" | ||
| { | ||
| "oAuthScopes": { | ||
| "view": ["view_products", "view_customers"], | ||
| "manage": ["manage_products"] | ||
| }, | ||
| "additionalOAuthScopes": [ | ||
| { | ||
| "name": "team-a", | ||
| "view": [], | ||
| "manage": ["manage_orders"] | ||
| }, | ||
| { | ||
| "name": "team-b", | ||
| "view": [], | ||
| "manage": ["manage_orders", "manage_discount_codes"] | ||
| } | ||
| ] | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Nit: I would suggest to avoid using "team-x" in the group name, as it gives the impression that this maps to a team name.
Let's use something else
Suggested change
| In the following example, permission group named `team-a` allows to manage orders but not manage discount codes, while permission group named `team-b` allows both. | |
| ```json title="custom-application-config.json" highlightLines="6-17" | |
| { | |
| "oAuthScopes": { | |
| "view": ["view_products", "view_customers"], | |
| "manage": ["manage_products"] | |
| }, | |
| "additionalOAuthScopes": [ | |
| { | |
| "name": "team-a", | |
| "view": [], | |
| "manage": ["manage_orders"] | |
| }, | |
| { | |
| "name": "team-b", | |
| "view": [], | |
| "manage": ["manage_orders", "manage_discount_codes"] | |
| } | |
| ] | |
| } | |
| ``` | |
| In the following example, we are 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"] | |
| } | |
| ] | |
| } |
| @@ -42,7 +81,7 @@ Each Custom Application gets a **unique pair** of user permissions: "view" and " | |||
|
|
|||
| <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>`. | |||
There was a problem hiding this comment.
Good point, we should maybe rephrase that section yes.
Comment on lines
43
to
51
| export const groupNames = { | ||
| teamA: 'team-a', | ||
| teamB: 'team-b', | ||
| }; | ||
|
|
||
| export const PERMISSIONS = entryPointUriPathToPermissionKeys( | ||
| entryPointUriPath, | ||
| [groupNames.teamA, groupNames.teamB] | ||
| ); |
There was a problem hiding this comment.
See other suggestion about the group names
Suggested change
| export const groupNames = { | |
| teamA: 'team-a', | |
| teamB: 'team-b', | |
| }; | |
| export const PERMISSIONS = entryPointUriPathToPermissionKeys( | |
| entryPointUriPath, | |
| [groupNames.teamA, groupNames.teamB] | |
| ); | |
| export const groupNames = { | |
| delivery: 'delivery', | |
| promotion: 'promotion', | |
| }; | |
| export const PERMISSIONS = entryPointUriPathToPermissionKeys( | |
| entryPointUriPath, | |
| ['delivery', 'promotion'] | |
| ); |
Also, if we provide a TS example, we need to make sure to use the as const for the groupNames, so that we can pass the list using variable references
export const groupNames = {
delivery: 'delivery',
promotion: 'promotion',
} as const;
export const PERMISSIONS = entryPointUriPathToPermissionKeys(
entryPointUriPath,
[groupNames.delivery, groupNames.promotion]
);There was a problem hiding this comment.
Thanks! That's a great catch!
❓ I'm still wondering how to approach the TS snippet. Is your point to integrate @commercetools-docs/gatsby-theme-code-examples as part of this PR?
There was a problem hiding this comment.
No that should probably be a follow up.
Comment on lines
54
to
61
| In this scenario the `PERMISSIONS` variable contains a `View`, `Manage`, `ViewTeamA`, `ManageTeamA`, `ViewTeamB` and `ManageTeamB` 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.ViewTeamA`: maps to `ViewChannelsTeamA`. | ||
| * `PERMISSIONS.ManageTeamA`: maps to `ManageChannelsTeamA`. | ||
| * `PERMISSIONS.ViewTeamB`: maps to `ViewChannelsTeamB`. | ||
| * `PERMISSIONS.ManageTeamB`: maps to `ManageChannelsTeamB`. |
There was a problem hiding this comment.
Suggested change
| In this scenario the `PERMISSIONS` variable contains a `View`, `Manage`, `ViewTeamA`, `ManageTeamA`, `ViewTeamB` and `ManageTeamB` 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.ViewTeamA`: maps to `ViewChannelsTeamA`. | |
| * `PERMISSIONS.ManageTeamA`: maps to `ManageChannelsTeamA`. | |
| * `PERMISSIONS.ViewTeamB`: maps to `ViewChannelsTeamB`. | |
| * `PERMISSIONS.ManageTeamB`: maps to `ManageChannelsTeamB`. | |
| 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`. |
|
|
||
| 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 fulfil specific business requirements. For example, if your Custom Application manages products, discounts and orders, you might want only a group of users to manage products and discounts while another group of users handles orders.<br /> |
There was a problem hiding this comment.
[Google.OxfordComma] Use the Oxford comma in 'For example, if your Custom Application manages products, discounts and'.
|
|
||
| The default permission group is always defined, even when not adding additional groups. | ||
|
|
||
| When additional groups are defined, the default group can be left "empty", without specifying any OAuth Scopes. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Google.Quotes] Commas and periods go inside quotation marks.
emmenko
reviewed
Nov 28, 2022
Comment on lines
2
to
4
| date: 2022-12-15 | ||
| title: Custom Applications multiple permissions | ||
| description: Introducing more granular permissions for Custom Applications. |
|
|
||
| The Application Kit packages have been released with a minor version `v21.21.0`. | ||
|
|
||
| Custom Applications now enable optional configuration for defining more granular [OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions#permission-groups) to cover more strict business requirements. |
There was a problem hiding this comment.
Thanks for keeping it concise! 🤗
I would maybe elaborate a bit more and point to the updated parts of the documentation.
Suggested change
| Custom Applications now enable optional configuration for defining more granular [OAuth Scopes and user permissions](/concepts/oauth-scopes-and-user-permissions#permission-groups) to cover more strict business requirements. | |
| Custom Applications now allow to define more granular OAuth Scopes and user permissions to cover more strict 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 be then [assigned to teams](/merchant-center/managing-custom-applications#assigning-team-permissions) in a more granular way. |
| @@ -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. | |||
There was a problem hiding this comment.
Suggested change
| 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. | |
| 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. |
There was a problem hiding this comment.
@kark, can you apply this one as well?
Anshuman71
suggested changes
Dec 5, 2022
|
|
||
| export const PERMISSIONS = entryPointUriPathToPermissionKeys( | ||
| entryPointUriPath, | ||
| ['delivery', 'promotion'] |
There was a problem hiding this comment.
Suggested change
| ['delivery', 'promotion'] | |
| [groupNames.delivery, groupNames.promotion] |
Let's use the constant values for consistency.
There was a problem hiding this comment.
We can't use the variables here as otherwise the type inference does not work.
Comment on lines
35
to
40
| 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 fulfil specific business requirements. For example, if your Custom Application manages products, discounts, and orders, you might want only a group of users to manage products and discounts while another group of users handles orders.<br /> | ||
| In this kind of scenario a single permission group (the default one) is not enough as you would need multiple permission groups fulfil the access requirements. | ||
|
|
||
| To enable such use cases, you can define additional permission groups that have different access requirements. See [additionalOAuthScopes](/api-reference/application-config#additionaloauthscopes) field in the Custom Application config. |
There was a problem hiding this comment.
Suggested change
| 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 fulfil specific business requirements. For example, if your Custom Application manages products, discounts, and orders, you might want only a group of users to manage products and discounts while another group of users handles orders.<br /> | |
| In this kind of scenario a single permission group (the default one) is not enough as you would need multiple permission groups fulfil the access requirements. | |
| To enable such use cases, you can define additional permission groups that have different access requirements. See [additionalOAuthScopes](/api-reference/application-config#additionaloauthscopes) field in the Custom Application config. | |
| 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. For example, 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. |
There was a problem hiding this comment.
@Anshuman71 could you please rework your suggestion for the paragraph starting with: 'However, you might need more..'. 🙏 It is not so easy to read and there is a sentence starting with 'And'.
|
|
||
| </Info> | ||
|
|
||
| In the following example, we are 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. |
There was a problem hiding this comment.
Suggested change
| In the following example, we are 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. | |
| 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. |
Comment on lines
73
to
77
| 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. | ||
|
|
||
| Even so, remember that the "view-only" user permission must be enabled to allow access to the Custom Application. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| Even so, remember that the "view-only" user permission must be enabled to allow access to the Custom Application. | |
| 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. |
There was a problem hiding this comment.
Hmm here we're actually mixing things up a bit. The first part about defining the permission groups is about the Custom Application configuration while the "view-only" part is about assigning team permissions.
Having the two points in one sentence makes is look like they are strictly related when configuring the app.
Maybe you can try rephrasing this again in case the original version wasn't clear enough?
There was a problem hiding this comment.
@emmenko, thanks for highlighting that. I've rephrased it for clarity.
|
|
||
| * 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>`. |
There was a problem hiding this comment.
Suggested change
| 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>`. | |
| 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>`. |
| @@ -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, more granular permission groups can be used to cover more strict business requirements. | |||
There was a problem hiding this comment.
Suggested change
| 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, more granular permission groups can be used to cover more strict business requirements. | |
| 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. |
|
|
||
| This feature is available from version `21.21.0` onwards. | ||
|
|
||
| When using additional permission groups, the unique group names should be provided to the `entryPointUriPathToPermissionKeys` function to generate the correct permission keys. |
There was a problem hiding this comment.
Suggested change
| When using additional permission groups, the unique group names should be provided to the `entryPointUriPathToPermissionKeys` function to generate the correct permission keys. | |
| When using additional permission groups, you must also provide the unique group to the `entryPointUriPathToPermissionKeys` function to generate the correct permission keys. |
| ); | ||
| ``` | ||
|
|
||
| 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: |
There was a problem hiding this comment.
Suggested change
| 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: | |
| 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: |
Comment on lines
12
to
16
| The Application Kit packages have been released with a minor version `v21.21.0`. | ||
|
|
||
| Custom Applications now allow to define more granular OAuth Scopes and user permissions to cover more strict 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 be then [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). |
There was a problem hiding this comment.
Suggested change
| The Application Kit packages have been released with a minor version `v21.21.0`. | |
| Custom Applications now allow to define more granular OAuth Scopes and user permissions to cover more strict 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 be then [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). | |
| 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). |
Comment on lines
432
to
436
| <Info> | ||
|
|
||
| Using `manage_` OAuth Scopes always imply the corresponding `view_` OAuth Scope. | ||
|
|
||
| </Info> |
There was a problem hiding this comment.
Suggested change
| <Info> | |
| Using `manage_` OAuth Scopes always imply the corresponding `view_` OAuth Scope. | |
| </Info> |
We can skip this callout, as it's already shared above.
emmenko
reviewed
Dec 5, 2022
Comment on lines
73
to
77
| 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. | ||
|
|
||
| Even so, remember that the "view-only" user permission must be enabled to allow access to the Custom Application. |
There was a problem hiding this comment.
Hmm here we're actually mixing things up a bit. The first part about defining the permission groups is about the Custom Application configuration while the "view-only" part is about assigning team permissions.
Having the two points in one sentence makes is look like they are strictly related when configuring the app.
Maybe you can try rephrasing this again in case the original version wasn't clear enough?
kark
force-pushed
the
multiple-permissions-docs
branch
from
5b9cc37
to
6126d50
Compare
Anshuman71
reviewed
Dec 6, 2022
| @@ -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. | |||
There was a problem hiding this comment.
@kark, can you apply this one as well?
Anshuman71
reviewed
Dec 6, 2022
|
|
||
| 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. For example, 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 /> |
There was a problem hiding this comment.
@kark, another one
Suggested change
| However, you might need more granular access control to fulfill specific business requirements. For example, 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 /> | |
| 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 /> |
Anshuman71
approved these changes
Dec 6, 2022
emmenko
approved these changes
Dec 9, 2022
emmenko
force-pushed
the
multiple-permissions-docs
branch
from
aa1e4b7
to
17ac6c9
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
In preparation for the Custom Applications Multiple Permissions support.
Relates to #2799