Merge pull request #259593 from shikhagarg1/main

Changes to clarify the concepts of data partition

Author: prmerger-automator[bot]

articles/energy-data-services/concepts-entitlements.md

@@ -15,15 +15,15 @@ Access management is a critical function for any service or resource. The entitl
 
 ## Groups
 
-The entitlements service of Azure Data Manager for Energy allows you to create groups and manage memberships of the groups. An entitlement group defines permissions on services/data sources for your Azure Data Manager for Energy instance. Users added to a given group obtain the associated permissions.
+The entitlements service of Azure Data Manager for Energy allows you to create groups and manage memberships of the groups. An entitlement group defines permissions on services/data sources for a given data partition in your Azure Data Manager for Energy instance. Users added to a given group obtain the associated permissions. Please note that different groups and associated user entitlements need to be set for a new data partition even in the same Azure Data Manager for Energy instance.
 
 The entitlements service enables three use cases for authorization:
 
 - **Data groups** used for data authorization (for example, data.welldb.viewers, data.welldb.owners)
 - **Service groups** used for service authorization (for example, service.storage.user, service.storage.admin)
 - **User groups** used for hierarchical grouping of user and service identities (for example, users.datalake.viewers, users.datalake.editors)
 
-Some user, data, and service groups are created by default when a data partition is provisioned with details in [Bootstrapped OSDU Entitlements Groups](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/blob/master/docs/osdu-entitlement-roles.md).
+Some user, data, and service groups are created by default when a data partition is provisioned. Details of these groups and their hierarchy scope is in [Bootstrapped OSDU Entitlements Groups](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/blob/master/docs/osdu-entitlement-roles.md).
 
 ## Group naming
 

articles/energy-data-services/how-to-convert-segy-to-ovds.md

@@ -92,7 +92,7 @@ If the user isn't part of the required group, you can add the required entitleme
 
 [![Screenshot that shows the API call to get register a user as an admin in Postman.](media/how-to-convert-segy-to-vds/postman-api-add-user-to-admins.png)](media/how-to-convert-segy-to-vds/postman-api-add-user-to-admins.png#lightbox)
 
-If you haven't yet created entitlements groups, follow the directions as outlined in [How to manage users](how-to-manage-users.md). If you would like to see what groups you have, use [Get entitlements groups for a given user](how-to-manage-users.md#get-entitlements-groups-for-a-given-user). Data access isolation is achieved with this dedicated ACL (access control list) per object within a given data partition. 
+If you haven't yet created entitlements groups, follow the directions as outlined in [How to manage users](how-to-manage-users.md). If you would like to see what groups you have, use [Get entitlements groups for a given user](how-to-manage-users.md#get-entitlements-groups-for-a-given-user-in-a-data-partition). Data access isolation is achieved with this dedicated ACL (access control list) per object within a given data partition. 
 
 ### Prepare Subproject
 
@@ -229,4 +229,4 @@ OSDU™ is a trademark of The Open Group.
 ## Next steps
 <!-- Add a context sentence for the following links -->
 > [!div class="nextstepaction"]
-> [How to convert a segy to zgy file](./how-to-convert-segy-to-zgy.md)
+> [How to convert a segy to zgy file](./how-to-convert-segy-to-zgy.md)

articles/energy-data-services/how-to-convert-segy-to-zgy.md

@@ -126,7 +126,7 @@ If the user isn't part of the required group, you can add the required entitleme
 
 [![Screenshot that shows the API call to get register a user as an admin in Postman.](media/how-to-convert-segy-to-zgy/postman-api-add-user-to-admins.png)](media/how-to-convert-segy-to-zgy/postman-api-add-user-to-admins.png#lightbox)
 
-If you haven't yet created entitlements groups, follow the directions as outlined in [How to manage users](how-to-manage-users.md). If you would like to see what groups you have, use [Get entitlements groups for a given user](how-to-manage-users.md#get-entitlements-groups-for-a-given-user). Data access isolation is achieved with this dedicated ACL (access control list) per object within a given data partition. 
+If you haven't yet created entitlements groups, follow the directions as outlined in [How to manage users](how-to-manage-users.md). If you would like to see what groups you have, use [Get entitlements groups for a given user](how-to-manage-users.md#get-entitlements-groups-for-a-given-user-in-a-data-partition). Data access isolation is achieved with this dedicated ACL (access control list) per object within a given data partition. 
 
 ### Prepare Subproject
 
@@ -256,4 +256,4 @@ OSDU™ is a trademark of The Open Group.
 ## Next steps
 <!-- Add a context sentence for the following links -->
 > [!div class="nextstepaction"]
-> [How to convert SEGY to OVDS](./how-to-convert-segy-to-ovds.md)
+> [How to convert SEGY to OVDS](./how-to-convert-segy-to-ovds.md)

articles/energy-data-services/how-to-manage-users.md

@@ -10,14 +10,14 @@ ms.custom: template-how-to
 ---
 
 # How to manage users
-In this article, you'll learn how to manage users and their memberships in OSDU groups in Azure Data Manager for Energy. [Entitlements APIs](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/tree/master/) are used to add or remove users to OSDU groups and to check the entitlements when the user tries to access the OSDU services or data. For more information about OSDU groups, see [entitlement services](concepts-entitlements.md).
+In this article, you learn how to manage users and their memberships in OSDU groups in Azure Data Manager for Energy. [Entitlements APIs](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/tree/master/) are used to add or remove users to OSDU groups and to check the entitlements when the user tries to access the OSDU services or data. For more information about OSDU groups, see [entitlement services](concepts-entitlements.md).
 
 
 ## Prerequisites
 1. Create an Azure Data Manager for Energy instance using the tutorial at [How to create Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md).
 2. Generate the access token needed to call the Entitlements APIs.
 3. Get various parameters of your instance such as client-id, client-secret, etc.  
-4. Keep all these parameter values handy as they will be needed for executing different user management requests via the Entitlements API. 
+4. Keep all these parameter values handy as they are needed for executing different user management requests via the Entitlements API. 
 
 ## Fetch Parameters
 #### Find `tenant-id`
@@ -30,7 +30,7 @@ In this article, you'll learn how to manage users and their memberships in OSDU
 :::image type="content" source="media/how-to-manage-users/tenant-id.png" alt-text="Screenshot of finding the tenant-id.":::
 
 #### Find `client-id`
-It's the same value that you used to register your application during the provisioning of your [Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md). It is often referred to as `app-id`.
+It's the same value that you use to register your application during the provisioning of your [Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md). It is often referred to as `app-id`.
 
 1. Find the `client-id` in the *Essentials* pane of Azure Data Manager for Energy *Overview* page.
 2. Copy the `client-id` and paste it into an editor to be used later.
@@ -99,19 +99,33 @@ curl --location --request POST 'https://login.microsoftonline.com/<tenant-id>/oa
         "access_token": "abcdefgh123456............."
     }
 ```
-2. Copy the `access_token` value from the response. You'll need it to pass as one of the headers in all calls to the Entitlements APIs. 
+2. Copy the `access_token` value from the response. You need it to pass as one of the headers in all calls to the Entitlements APIs. 
 
 ## Fetch OID
 `object-id` (OID) is the Microsoft Entra user Object ID.
 
 1. Find the 'object-id' (OID) of the user(s) first. If you are managing an application's access, you must find and use the application ID (or client ID) instead of the OID.
-2. Input the `object-id` (OID) of the users (or the application or client ID if managing access for an application) as parameters in the calls to the Entitlements API of your Azure Data Manager for Energy Instance. 
+2. Input the `object-id` (OID) of the users (or the application or client ID if managing access for an application) as parameters in the calls to the Entitlements API of your Azure Data Manager for Energy instance. 
 
 :::image type="content" source="media/how-to-manage-users/azure-active-directory-object-id.png" alt-text="Screenshot of finding the object-id from Microsoft Entra I D.":::
 
 :::image type="content" source="media/how-to-manage-users/profile-object-id.png" alt-text="Screenshot of finding the object-id from the profile.":::
 
-## Get the list of all available groups 
+## First time addition of users in a new data partition
+In order to add entitlements to a new data partition of Azure Data Manager for Energy instance, use the SPN  token of the app that was used to provision the instance. If you try to directly use user tokens for adding entitlements, it results in 401 error. The SPN token must be used to add initial users in the system and those users (with admin access) can then manage additional users.
+
+The SPN is generated using client_credentials flow
+```bash
+curl --location --request POST 'https://login.microsoftonline.com/<tenant-id>/oauth2/token' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'grant_type=client_credentials' \
+--data-urlencode 'scope=<client-id>.default' \
+--data-urlencode 'client_id=<client-id>' \
+--data-urlencode 'client_secret=<client-secret>' \
+--data-urlencode 'resource=<client-id>'
+```
+
+## Get the list of all available groups in a data partition
 
 Run the below curl command in Azure Cloud Bash to get all the groups that are available for your Azure Data Manager for the Energy instance and its data partitions.
 
@@ -121,7 +135,7 @@ Run the below curl command in Azure Cloud Bash to get all the groups that are av
     --header 'Authorization: Bearer <access_token>'
 ```
 
-## Add user(s) to a OSDU group
+## Add user(s) to an OSDU group in a data partition
 
 1. Run the below curl command in Azure Cloud Bash to add the user(s) to the "Users" group using the Entitlement service.
 2. The value to be sent for the param **"email"** is the **Object_ID (OID)** of the user and not the user's email.
@@ -164,7 +178,7 @@ Consider an Azure Data Manager for Energy instance named "medstest" with a data
 > The app-id is the default OWNER of all the groups.
 :::image type="content" source="media/how-to-manage-users/appid.png" alt-text="Screenshot of app-d in Microsoft Entra ID.":::
 
-## Add user(s) to an entitlements group
+## Add user(s) to an entitlements group in a data partition
 
 1. Run the below curl command in Azure Cloud Bash to add the user(s) to an entitlement group using the Entitlement service.
 2. The value to be sent for the param **"email"** is the **Object_ID (OID)** of the user and not the user's email.
@@ -205,7 +219,7 @@ Consider an Azure Data Manager for Energy instance named "medstest" with a data
     }
 ```
 
-## Get entitlements groups for a given user
+## Get entitlements groups for a given user in a data partition
 
 1. Run the below curl command in Azure Cloud Bash to get all the groups associated with the user.
 
@@ -245,7 +259,7 @@ Consider an Azure Data Manager for Energy instance named "medstest" with a data
     }
 ```
 
-## Delete entitlement groups of a given user
+## Delete entitlement groups of a given user in a data partition
 
 1. Run the below curl command in Azure Cloud Bash to delete a given user from a given data partition.
 2. As stated above, **DO NOT** delete the OWNER of a group unless you have another OWNER who can manage users in that group.