From b6b85ba5fe6665b4539655fc67aba9c6773880df Mon Sep 17 00:00:00 2001 From: Athman Gude Date: Tue, 9 May 2023 14:48:25 +0300 Subject: [PATCH 1/3] added provisioninginfo file --- specs/provisioningInfo.md | 56 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 specs/provisioningInfo.md diff --git a/specs/provisioningInfo.md b/specs/provisioningInfo.md new file mode 100644 index 000000000..f97607101 --- /dev/null +++ b/specs/provisioningInfo.md @@ -0,0 +1,56 @@ +# Provisioning Info for Permissions in Graph + +## Abstract +The provisioning info file is a JSON file that contains a list of permissions and the cloud environments in which they are available. + +## Introduction +The JSON permissions model seeks to be the authoritative source of truth for for data on permissions to API mapping. We have restricted the contents of the JSON permission files to modeling data that has to be reviewed for every change. This does not include data about the cloud environments in which API workloads intend to publish permissions to. Some of that data is only known after the permission has been published to the environment and would have to either be automatically or manually updated by the publishing team back to the permissions model file after the change review. This should not require a review of the change to the permission file. The provisioning info file is complementary to the JSON permissions model files and allows us to keep the permissions model file as the authoritative source of truth for permissions modeling data while allowing us to maintain a separate source of truth for cloud availability data. + +## The Provisioning Info file +The provisioning info file is a single file for all permissions. Permissions are still the primary concept with a many to many relationship between permissions and cloud environments. Permission claim values are the top level members to enable quick lookup for provisioning for a permission. Not all implemented schemes of a permission are published consistently across all environments and even when published they would happen to have different unique identifiers. The provisioning info file allows us to model the cloud availability of each scheme of a permission. + +```json +"provisioningInfo": { + “Foo.Read.All”: { + "requiredEnvironments": [ + { + "mooncake": { + "schemes": [ + { + "DelegatedWork": { + "isPresent": true, + "isHidden": false, + "isDisabled": false, + "id": "bed71653-0fa8-42a0-b33c-a1aab02ecda6" + } + } + ] + }, + "global": { + "schemes": [ + { + "DelegatedWork": { + "isPresent": true, + "isHidden": false, + "isDisabled": false, + "id": "bed71653-0fa8-42a0-b33c-a1aab02ecda6" + } + } + ] + } + } + ] + } +} +``` + +### isHidden +The "isHidden" member is a boolean value that indicates if a permission should be publicly usable in the API. + +### requiredEnvironments +The "requiredEnvironments" member is an array of strings that identifies the deployment environments in which the permission SHOULD be supported. When this member is not present, support for all environments is implied. + +### resourceAppId +The "resourceAppId" member value provides an identifier of the resource server that is used to enforce Conditional Access checks for this permission. + + From c9b2b7475b86978b89d679a906ec0befd7ccd01b Mon Sep 17 00:00:00 2001 From: Athman Gude Date: Tue, 9 May 2023 19:26:14 +0300 Subject: [PATCH 2/3] updated spec for provisioningInfo --- specs/provisioningInfo.md | 108 ++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 35 deletions(-) diff --git a/specs/provisioningInfo.md b/specs/provisioningInfo.md index f97607101..e34904d58 100644 --- a/specs/provisioningInfo.md +++ b/specs/provisioningInfo.md @@ -1,54 +1,92 @@ # Provisioning Info for Permissions in Graph ## Abstract -The provisioning info file is a JSON file that contains a list of permissions and the cloud environments in which they are available. +The provisioning info file is a complementary JSON file to the JSON permission files that contains a list of permissions and the cloud environments in which they are present. It can serve to instruct publishing on which environments to publish a new permission to as well as show which clouds existing permissions are present in. ## Introduction -The JSON permissions model seeks to be the authoritative source of truth for for data on permissions to API mapping. We have restricted the contents of the JSON permission files to modeling data that has to be reviewed for every change. This does not include data about the cloud environments in which API workloads intend to publish permissions to. Some of that data is only known after the permission has been published to the environment and would have to either be automatically or manually updated by the publishing team back to the permissions model file after the change review. This should not require a review of the change to the permission file. The provisioning info file is complementary to the JSON permissions model files and allows us to keep the permissions model file as the authoritative source of truth for permissions modeling data while allowing us to maintain a separate source of truth for cloud availability data. +The JSON permissions model seeks to be the authoritative source of truth for for data on permissions to API mapping. We have restricted the contents of the JSON permission files to modeling data that has to be reviewed for every change. This does not include data about the permission in the cloud environments where it is intended to be published to. Some of that data is only known after the permission has been published to the environment and would have to either be automatically or manually updated back to the permissions model file after publishing e.g., the GUID of the permission in cloud environment. This should not require a review of the change to the permission file. The provisioning info file is complementary to the JSON permissions model files and allows us to keep the permissions model file as the authoritative source of truth for permissions modeling data while allowing us to maintain a separate source of truth for cloud availability data. -## The Provisioning Info file -The provisioning info file is a single file for all permissions. Permissions are still the primary concept with a many to many relationship between permissions and cloud environments. Permission claim values are the top level members to enable quick lookup for provisioning for a permission. Not all implemented schemes of a permission are published consistently across all environments and even when published they would happen to have different unique identifiers. The provisioning info file allows us to model the cloud availability of each scheme of a permission. +The provisioning info file is a single file for all permissions. Permissions are still the primary concept with a many to many relationship between permissions and cloud environments. Permission claim values are the top level members to enable quick lookup for provisioning for a given permission. Not all implemented permission schemes are published across all environments. The same permission would have different GUIDs in different environments and even when all schemes of a permission are published to the same environment, they would happen to have different unique identifiers. The provisioning info file allows us to model the cloud availability of a permission across different clouds for each of its schemes. + +## Notational Conventions +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. + +## Permissions JSON Object +This is the top level object in the provisioning info file. It contains a list of permission claim values and the cloud environments in which they are present. ```json -"provisioningInfo": { +"permissions": { “Foo.Read.All”: { - "requiredEnvironments": [ - { - "mooncake": { - "schemes": [ - { - "DelegatedWork": { - "isPresent": true, - "isHidden": false, - "isDisabled": false, - "id": "bed71653-0fa8-42a0-b33c-a1aab02ecda6" - } - } - ] - }, + "environments": { "global": { - "schemes": [ - { - "DelegatedWork": { - "isPresent": true, - "isHidden": false, - "isDisabled": false, - "id": "bed71653-0fa8-42a0-b33c-a1aab02ecda6" - } - } - ] + "versions": { + "v1": { + "schemes": [ + { + "DelegatedWork": { + "isPresent": true, + "isHidden": false, + "isDisabled": false, + "id": "bed71653-0fa8-42a0-b33c-a1aab02ecda6" + } + } + ] + }, + "beta": { + "schemes": [ + { + "DelegatedWork": { + "isPresent": true, + "isHidden": false, + "isDisabled": false, + "id": "bed71753-0fq8-42a2-b33c-c1acb02ecd17" + } + } + ] + }, + } } - } - ] + } } } ``` -### isHidden -The "isHidden" member is a boolean value that indicates if a permission should be publicly usable in the API. +In this example, the permission "Foo.Read.All" is present in the global environment in both v1 and beta versions. The "DelegatedWork" scheme is present in both versions. Note that the same scheme of the same permission have permission has different GUIDs in the two clouds. + +### permissions +The "permissions" member is a JSON object whose members permission objects. The key of each member is the claim identifier used for the [Permission Object](#permissionObject) + + +### Permission Object +This member is a JSON object that describes the provisioning info for a permission. + +#### environments +The "environments" member is an array of objects that identifies the deployment environments in which the permission SHOULD be supported. The key of each member is the cloud environment identifier used for the [Cloud Environment Object](#cloudEnvironmentObject) + +### Cloud Environment Object +This member is a JSON object whose members are version objects. The key of each member is the version identifier used for the [Version Object](#versionObject). + +### Version Object +This member is a JSON object whose members are scheme objects. The key of each member is the scheme identifier used for the [Scheme Object](#schemeObject). + +### Scheme Object +This member is a JSON object whose keys are permission scheme identifiers. The members of the scheme object are the provisioning info for the scheme in the cloud environment. + +#### isPresent +The "isPresent" member is a boolean value that indicates if a permission is present in the environment. + +#### isHidden +The "isHidden" member is a boolean value that indicates if a permission should be publicly usable in the API. + +#### isDisabled +The "isDisabled" member is a boolean value that indicates if a permission is disabled in the environment. + +#### id +The "id" member is the GUID of the permission in the environment. + +#### resourceAppId +The "resourceAppId" member value provides an identifier of the resource server that is used to enforce Conditional Access checks for this permission. -### requiredEnvironments -The "requiredEnvironments" member is an array of strings that identifies the deployment environments in which the permission SHOULD be supported. When this member is not present, support for all environments is implied. ### resourceAppId The "resourceAppId" member value provides an identifier of the resource server that is used to enforce Conditional Access checks for this permission. From 4ee4b32cafd9b9c29283362f35e72cfa2df943df Mon Sep 17 00:00:00 2001 From: Athman Gude Date: Wed, 10 May 2023 13:57:50 +0300 Subject: [PATCH 3/3] Update provisioningInfo.md Added `resourceAppId` attribute to example --- specs/provisioningInfo.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specs/provisioningInfo.md b/specs/provisioningInfo.md index e34904d58..5dad9b8d8 100644 --- a/specs/provisioningInfo.md +++ b/specs/provisioningInfo.md @@ -17,6 +17,7 @@ This is the top level object in the provisioning info file. It contains a list o ```json "permissions": { “Foo.Read.All”: { + "resourceAppId": "00000003-0000-0000-c000-000000000000", "environments": { "global": { "versions": {