Merge pull request #258965 from shikhagarg1/main

Make informational changes in the managing users page

Author: Stacyrch140

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

@@ -10,57 +10,72 @@ ms.custom: template-how-to
 ---
 
 # How to manage users
-In this article, you'll know how to manage users in Azure Data Manager for Energy. It uses the [entitlements API](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/tree/master/) and acts as a group-based authorization system for data partitions within Azure Data Manager for Energy instance. For more information about Azure Data Manager for Energy entitlements, see [entitlement services](concepts-entitlements.md).
+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).
 
 
 ## 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. 
 
-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).
-
-You will need to pass parameters for generating the access token, which you'll need to make valid calls to the Entitlements API of your Azure Data Manager for Energy instance. You will also need these parameters for different user management requests to the Entitlements API. Hence Keep the following values handy for these actions.
-
+## Fetch Parameters
 #### Find `tenant-id`
-Navigate to the Microsoft Entra account for your organization. One way to do so is by searching for "Microsoft Entra ID" in the Azure portal's search bar. Once there, locate `tenant-id` under the basic information section in the *Overview* tab. Copy the `tenant-id` and paste in an editor to be used later.  
+1. Navigate to the Microsoft Entra account for your organization. You can search for "Microsoft Entra ID" in the Azure portal's search bar.
+2. Locate `tenant-id` under the basic information section in the *Overview* tab.
+3. Copy the `tenant-id` and paste it into an editor to be used later.  
 
 :::image type="content" source="media/how-to-manage-users/azure-active-directory.png" alt-text="Screenshot of search for Microsoft Entra I D.":::
 
 :::image type="content" source="media/how-to-manage-users/tenant-id.png" alt-text="Screenshot of finding the tenant-id.":::
 
 #### Find `client-id`
-Often called `app-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). You'll find the `client-id` in the *Essentials* pane of Azure Data Manager for Energy *Overview* page. Copy the `client-id` and paste in an editor to be used later. 
+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`.
+
+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.
+3. Currently, one Azure Data Manager for Energy instance allows one app-id to be as associated with one instance.
 
 > [!IMPORTANT]
-> The 'client-id' that is passed as values in the entitlement API calls needs to be the same which was used for provisioning of your Azure Data Manager for Energy instance.
+> The 'client-id' that is passed as values in the entitlement API calls needs to be the same that was used for provisioning your Azure Data Manager for the Energy instance.
 
 :::image type="content" source="media/how-to-manage-users/client-id-or-app-id.png" alt-text="Screenshot of finding the client-id for your registered App.":::
 
 #### Find `client-secret`
-Sometimes called an application password, a `client-secret` is a string value your app can use in place of a certificate to identity itself. Navigate to *App Registrations*. Once there, open 'Certificates & secrets' under the *Manage* section. Create a `client-secret` for the `client-id` that you used to create your Azure Data Manager for Energy instance, you can add one now by clicking on *New Client Secret*. Record the secret's `value` for use in your client application code. 
+A `client-secret` is a string value your app can use in place of a certificate to identify itself. It is sometimes referred to as an application password. 
+
+1. Navigate to *App Registrations*.
+2. Open 'Certificates & secrets' under the *Manage* section.
+3. Create a `client-secret` for the `client-id` that you used to create your Azure Data Manager for Energy instance.
+4. Add one now by clicking on *New Client Secret*.
+5. Record the secret's `value` for later use in your client application code.
+6. The Service Principal [SPN] of the app id and client secret has the Infra Admin access to the instance.
 
 > [!CAUTION]
-> Don't forget to record the secret's value for use in your client application code. This secret value is never displayed again after you leave this page at the time of creation of 'client secret'.
+> Don't forget to record the secret's value. This secret value is never displayed again after you leave this page of 'client secret' creation.
 
 :::image type="content" source="media/how-to-manage-users/client-secret.png" alt-text="Screenshot of finding the client secret.":::
 
-#### Find the `url`for your Azure Data Manager for Energy instance
-Navigate to your Azure Data Manager for Energy *Overview* page on Azure portal. Copy the URI from the essentials pane. 
+#### Find the `URL` for your Azure Data Manager for Energy instance
+1. Navigate to your Azure Data Manager for Energy *Overview* page on the Azure portal.
+2. Copy the URI from the essentials pane. 
 
-:::image type="content" source="media/how-to-manage-users/endpoint-url.png" alt-text="Screenshot of finding the url from Azure Data Manager for Energy instance.":::
+:::image type="content" source="media/how-to-manage-users/endpoint-url.png" alt-text="Screenshot of finding the URL from Azure Data Manager for Energy instance.":::
 
-#### Find the `data-partition-id` for your group
-You have two ways to get the list of data-partitions in your Azure Data Manager for Energy instance. 
-- One option is to navigate *Data Partitions* menu item under the Advanced section of your Azure Data Manager for Energy UI.
+#### Find the `data-partition-id` 
+1. You have two ways to get the list of data partitions in your Azure Data Manager for Energy instance. '
+2. One option is to navigate the *Data Partitions* menu item under the Advanced section of your Azure Data Manager for Energy UI.
 
 :::image type="content" source="media/how-to-manage-users/data-partition-id.png" alt-text="Screenshot of finding the data-partition-id from the Azure Data Manager for Energy instance.":::
 
-- Another option is by clicking on the *view* below the *data partitions* field in the essentials pane of your Azure Data Manager for Energy *Overview* page. 
+3. Another option is to click on the *view* below the *data partitions* field in the essentials pane of your Azure Data Manager for Energy *Overview* page. 
 
 :::image type="content" source="media/how-to-manage-users/data-partition-id-second-option.png" alt-text="Screenshot of finding the data-partition-id from the Azure Data Manager for Energy instance overview page.":::
 
 :::image type="content" source="media/how-to-manage-users/data-partition-id-second-option-step-2.png" alt-text="Screenshot of finding the data-partition-id from the Azure Data Manager for Energy instance overview page with the data partitions.":::
 ## Generate access token
 
-You need to generate access token to use entitlements API. Run the below curl command in Azure Cloud Bash after replacing the placeholder values with the corresponding values found earlier in the pre-requisites step.
+1. Run the below curl command in Azure Cloud Bash after replacing the placeholder values with the corresponding values found earlier in the above steps.
 
 **Request format**
 
@@ -84,31 +99,32 @@ curl --location --request POST 'https://login.microsoftonline.com/<tenant-id>/oa
         "access_token": "abcdefgh123456............."
     }
 ```
-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 API of your Azure Data Manager for Energy instance. 
-
-## User management activities
+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. 
 
-You can manage users' access to your Azure Data Manager for Energy instance or data partitions. As a prerequisite for this step, you need to find the 'object-id' (OID) of the user(s) first. If you are managing an application's access to your instance or data partition, then you must find and use the application ID (or client ID) instead of the OID.
+## Fetch OID
+`object-id` (OID) is the Microsoft Entra user Object ID.
 
-You'll need to 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. `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. 
 
 :::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 
+## Get the list of all available groups 
 
-Run the below curl command in Azure Cloud Bash to get all the groups that are available for your Azure Data Manager for Energy instance and its data partitions.
+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.
 
 ```bash
     curl --location --request GET "https://<URI>/api/entitlements/v2/groups/" \
     --header 'data-partition-id: <data-partition>' \
     --header 'Authorization: Bearer <access_token>'
 ```
 
-### Add user(s) to a users group
+## Add user(s) to a OSDU group
 
-Run the below curl command in Azure Cloud Bash to add user(s) to the "Users" group using Entitlement service.
+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.
 
 ```bash
     curl --location --request POST 'https://<URI>/api/entitlements/v2/groups/users@<data-partition-id>.dataservices.energy/members' \
@@ -121,8 +137,6 @@ Run the below curl command in Azure Cloud Bash to add user(s) to the "Users" gro
                 }'
 ```
 
-The value to be sent for the param **"email"** is the **Object_ID (OID)** of the user and not the user's email
-
 **Sample request**
 
 Consider an Azure Data Manager for Energy instance named "medstest" with a data partition named "dp1"
@@ -146,10 +160,14 @@ Consider an Azure Data Manager for Energy instance named "medstest" with a data
         "role": "MEMBER"
     }
 ```
+> [!IMPORTANT]
+> 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
 
-Run the below curl command in Azure Cloud Bash to add user(s) to an entitlement group using Entitlement service.
+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.
 
 ```bash
     curl --location --request POST 'https://<URI>/api/entitlements/v2/groups/service.search.user@<data-partition-id>.dataservices.energy/members' \
@@ -161,11 +179,11 @@ Run the below curl command in Azure Cloud Bash to add user(s) to an entitlement
                 "role": "MEMBER"
     }'
 ```
-The value to be sent for the param **"email"** is the **Object_ID (OID)** of the user and not the user's email
+
 
 **Sample request**
 
-Consider an Azure Data Manager for Energy instance named "medstest" with a data partition named "dp1"
+Consider an Azure Data Manager for Energy instance named "medstest" with a data partition named "dp1".
 
 ```bash
     curl --location --request POST 'https://medstest.energy.azure.com/api/entitlements/v2/groups/[email protected]/members' \
@@ -187,9 +205,9 @@ 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
 
-Run the below curl command in Azure Cloud Bash to get all the groups associated with the user.
+1. Run the below curl command in Azure Cloud Bash to get all the groups associated with the user.
 
 ```bash
     curl --location --request GET 'https://<URI>/api/entitlements/v2/members/<OBJECT_ID>/groups?type=none' \
@@ -227,11 +245,10 @@ Consider an Azure Data Manager for Energy instance named "medstest" with a data
     }
 ```
 
-### Delete entitlement groups of a given user
-
-Run the below curl command in Azure Cloud Bash to delete a given user to your Azure Data Manager for Energy instance data partition.
+## Delete entitlement groups of a given user
 
-As stated above, **DO NOT** delete the OWNER of a group unless you have another OWNER that can manage users in that group.
+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.
 
 ```bash
     curl --location --request DELETE 'https://<URI>/api/entitlements/v2/members/<OBJECT_ID>' \
@@ -256,7 +273,7 @@ No output for a successful response
 
 ## Next steps
 <!-- Add a context sentence for the following links -->
-Create a legal tag for your Azure Data Manager for Energy instance's data partition.
+Create a legal tag for your data partition.
 > [!div class="nextstepaction"]
 > [How to manage legal tags](how-to-manage-legal-tags.md)