-
Notifications
You must be signed in to change notification settings - Fork 27
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Custom Applications multiple permissions #2806
Conversation
|
Deploy preview for merchant-center-application-kit ready! ✅ Preview Built with commit 17ac6c9. |
2e3ad2b
to
b75ba02
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Super nice, this is looking already good! 🥳
I left some minor suggestions, let me know what you think about it.
Thanks 🤗
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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). |
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's try to use the same terminology "permission group" to make it easier for users to relate things to each other.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
## `additionalOAuthScopes.name` | |
## `additionalOAuthScopes.*.name` |
## `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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
## `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. |
## `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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
## `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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
<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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we can simply mention the additional groups here in the intro.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can be removed, see suggestion for the intro section.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
export const teamA = "team-a"; | ||
|
||
export const teamB = "team-b"; | ||
|
||
export const PERMISSIONS = entryPointUriPathToPermissionKeys( | ||
entryPointUriPath, | ||
[teamA, teamB] | ||
); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: maybe we can define the names as an constants object.
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] | |
); |
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🚫 [vale] reported by reviewdog 🐶
[Google.Quotes] Commas and periods go inside quotation marks.
a8a494e
to
1114961
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
💯
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point, we should maybe rephrase that section yes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Went through the docs again and left some more suggestions.
With that, I think we should have all the important info documented.
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: I would make it a subsection
# Permission groups | |
## Permission groups |
<Info> | ||
|
||
This feature is available from version `21.21.0` onwards. | ||
|
||
</Info> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would start the introduction of this section by explaining what the group is and that there is a default one.
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. |
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here I would then mention the version requirement:
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point, we should maybe rephrase that section yes.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See other suggestion about the group names
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No that should probably be a follow up.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🚫 [vale] reported by reviewdog 🐶
[Google.Quotes] Commas and periods go inside quotation marks.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🤗
date: 2022-12-15 | ||
title: Custom Applications multiple permissions | ||
description: Introducing more granular permissions for Custom Applications. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
💯
|
||
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for keeping it concise! 🤗
I would maybe elaborate a bit more and point to the updated parts of the documentation.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, updated 🙂
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@kark, can you apply this one as well?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good technically. Please review and merge the suggestions.
|
||
export const PERMISSIONS = entryPointUriPathToPermissionKeys( | ||
entryPointUriPath, | ||
['delivery', 'promotion'] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
['delivery', 'promotion'] | |
[groupNames.delivery, groupNames.promotion] |
Let's use the constant values for consistency.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can't use the variables here as otherwise the type inference does not work.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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: |
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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). |
<Info> | ||
|
||
Using `manage_` OAuth Scopes always imply the corresponding `view_` OAuth Scope. | ||
|
||
</Info> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
<Info> | |
Using `manage_` OAuth Scopes always imply the corresponding `view_` OAuth Scope. | |
</Info> |
We can skip this callout, as it's already shared above.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the review! 🙌
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
5b9cc37
to
6126d50
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Final changes. All good otherwise.
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@kark, can you apply this one as well?
|
||
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@kark, another one
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 /> |
aa1e4b7
to
17ac6c9
Compare
Summary
In preparation for the Custom Applications Multiple Permissions support.
Relates to #2799