Merge pull request #263073 from paulth1/energy-data-services

[AQ] edit pass: Energy data services

Author: ShawnJackson

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

@@ -1,6 +1,6 @@
 ---
 title: Authentication concepts in Microsoft Azure Data Manager for Energy 
-description:  This article describes the various concepts regarding the authentication in Azure Data Manager for Energy.
+description: This article describes various concepts of authentication in Azure Data Manager for Energy.
 author: shikhagarg1
 ms.author: shikhagarg
 ms.service: energy-data-services
@@ -9,21 +9,26 @@ ms.date: 02/10/2023
 ms.custom: template-concept
 ---
 
-# Authentication concepts in Azure Data Manager for Energy 
-Authentication confirms the identity of the users. The access flows can be user triggered, system triggered, or system API communication. In this article, you learn about service principals and authorization token.
+# Authentication concepts in Azure Data Manager for Energy
+
+Authentication confirms the identity of users. The access flows can be user triggered, system triggered, or system API communication. In this article, you learn about service principals and authorization tokens.
 
 ## Service principals
-In the Azure Data Manager for Energy instance, 
-1. No Service Principals are created. 
-2. The app-id is used for API access. The same app-id is used to provision ADME instance.
-3. The app-id doesn't have access to infrastructure resources. 
-4. The app-id also gets added as OWNER to all OSDU groups by default. 
-5. For service-to-service (S2S) communication, ADME uses MSI (Microsoft Service Identity).
-
-In the OSDU instance, 
-1. Terraform scripts create two Service Principals: 
-   1. The first Service Principal is used for API access. It can also manage infrastructure resources. 
-   2. The second Service Principal is used for service-to-service (S2S) communications. 
-
-## Generate authorization token
-You can generate the authorization token using the steps outlined in [Generate auth token](how-to-generate-auth-token.md). 
+
+In an Azure Data Manager for Energy instance:
+
+- No service principals are created.
+- The app ID is used for API access. The same app ID is used to provision an Azure Data Manager for Energy instance.
+- The app ID doesn't have access to infrastructure resources.
+- The app ID also gets added as OWNER to all OSDU groups by default.
+- For service-to-service communication, Azure Data Manager for Energy uses Managed Service Identity.
+
+In an OSDU instance:
+
+- Terraform scripts create two service principals:
+   - The first service principal is used for API access. It can also manage infrastructure resources.
+   - The second service principal is used for service-to-service communications.
+
+## Generate an authorization token
+
+To generate the authorization token, follow the steps in [Generate auth token](how-to-generate-auth-token.md).

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

@@ -1,6 +1,6 @@
 ---
-title: Entitlement concepts in Microsoft Azure Data Manager for Energy 
-description:  This article describes the various concepts regarding the entitlement service in Azure Data Manager for Energy.
+title: Entitlement concepts in Azure Data Manager for Energy 
+description: This article describes various concepts of the entitlement service in Azure Data Manager for Energy.
 author: shikhagarg1
 ms.author: shikhagarg
 ms.service: energy-data-services
@@ -11,55 +11,59 @@ ms.custom: template-concept
 
 # Entitlement service
 
-Access management is a critical function for any service or resource. The entitlement service lets you control who can use your Azure Data Manager for Energy, what they can see or change, and which services or data they can use.
+Access management is a critical function for any service or resource. The entitlement service lets you control who can use your Azure Data Manager for Energy instance, what they can see or change, and which services or data they can use.
 
 ## OSDU groups structure and naming
 
-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. All group identifiers (emails) are of form `{groupType}.{serviceName|resourceName}.{permission}@{partition}.{domain}`.
+The entitlement 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 or data sources for a specific data partition in your Azure Data Manager for Energy instance. Users added to a specific group obtain the associated permissions. All group identifiers (emails) are of the form `{groupType}.{serviceName|resourceName}.{permission}@{partition}.{domain}`.
 
-Please note that different groups and associated user entitlements need to be set for every **new data partition** even in the same Azure Data Manager for Energy instance.
+Different groups and associated user entitlements must be set for every *new data partition*, even in the same Azure Data Manager for Energy instance.
 
-The entitlements service enables three use cases for authorization:
+The entitlement service enables three use cases for authorization:
 
-1. **Data groups** are used to enable authorization for data.
-   1. The data groups start with the word "data." such as data.welldb.viewers and data.welldb.owners.
-   2. Individual users are added to the data groups which are added in the ACL of individual data records to enable `viewer` and `owner` access of the data once the data has been loaded in the system.
-   3. To `upload` the data, you need to have entitlements of various OSDU services which are used during ingestion process. The combination of OSDU services depends on the method of ingestion. E.g., for manifest ingestion, refer [this](concepts-manifest-ingestion.md) to understand the OSDU services APIs used. The user **need not be part of the ACL** to upload the data.
-
-2. **Service groups** are used to enable authorization for services.
-   1. The service groups start with the word "service." such as service.storage.user and service.storage.admin. 
-   2. The service groups are **predefined** when OSDU services are provisioned in each data partition of Azure Data Manager for Energy instance.
-   3. These groups enable `viewer`, `editor`, and `admin` access to call the OSDU APIs corresponding to the OSDU services.
-
-3. **User groups** are used for hierarchical grouping of user and service groups.
-   1. The service groups start with the word "users." such as users.datalake.viewers and users.datalake.editors. 
-   2. Some user groups are created by default when a data partition is provisioned. Details of these groups and their hierarchy scope are in [Bootstrapped OSDU Entitlements Groups](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/blob/master/docs/osdu-entitlement-roles.md).
-   3. There's one exception of this group naming rule for "users" group. It gets created when a new data partition is provisioned and its name follows the pattern of `users@{partition}.{domain}`. It has the list of all the users with any type of access in a given data partition. Before adding a new user to any entitlement groups, you need to add the new user to the `users@{partition}.{domain}` group as well.
+- **Data groups** are used to enable authorization for data.
+   - The data groups start with the word "data," such as `data.welldb.viewers` and `data.welldb.owners`.
+   - Individual users are added to the data groups, which are added in the ACL of individual data records to enable `viewer` and `owner` access of the data after the data is loaded in the system.
+   - To `upload` the data, you need to have entitlements of various OSDU services, which are used during the ingestion process. The combination of OSDU services depends on the method of ingestion. For example, for manifest ingestion, see [Manifest-based ingestion concepts](concepts-manifest-ingestion.md) to understand the OSDU services that APIs used. The user *doesn't need to be part of the ACL* to upload the data.
+- **Service groups** are used to enable authorization for services.
+   - The service groups start with the word "service," such as `service.storage.user` and `service.storage.admin`.
+   - The service groups are *predefined* when OSDU services are provisioned in each data partition of the Azure Data Manager for Energy instance.
+   - These groups enable `viewer`, `editor`, and `admin` access to call the OSDU APIs corresponding to the OSDU services.
+- **User groups** are used for hierarchical grouping of user and service groups.
+   - The service groups start with the word "users," such as `users.datalake.viewers` and `users.datalake.editors`.
+   - Some user groups are created by default when a data partition is provisioned. For information on these groups and their hierarchy scope, see [Bootstrapped OSDU entitlement groups](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-azure-provisioning/-/blob/master/docs/osdu-entitlement-roles.md).
+   - There's one exception of this group naming rule for the "users" group. It gets created when a new data partition is provisioned and its name follows the pattern of `users@{partition}.{domain}`. It has the list of all the users with any type of access in a specific data partition. Before you add a new user to any entitlement groups, you also need to add the new user to the `users@{partition}.{domain}` group.
 
-Individual users can be added to a `user group`. The `user group` is then added to a `data group`. The data group is added to the ACL of the data record. It enables abstraction for the data groups since individual users need not be added one by one to the data group and instead can be added to the `user group`. This `user group` can then be used repeatedly for multiple `data groups`. The nested structure thus helps provide scalability to manage memberships in OSDU.
+You can add individual users to a `user group`. The `user group` is then added to a `data group`. The data group is added to the ACL of the data record. It enables abstraction for the data groups because individual users don't need to be added one by one to the data group. Instead, you can add users to the `user group`. Then you can use the `user group` repeatedly for multiple `data groups`. The nested structure helps provide scalability to manage memberships in OSDU.
 
 ## Users
 
-For each OSDU group, you can either add a user as an OWNER or a MEMBER. 
-1. If you're an OWNER of an OSDU group, then you can add or remove the members of that group or delete the group.
-2. If you're a MEMBER of an OSDU group, you can view, edit, or delete the service or data depending on the scope of the OSDU group. For example, if you're a MEMBER of service.legal.editor OSDU group, you can call the APIs to change the legal service.
+For each OSDU group, you can add a user as either an OWNER or a MEMBER:
+
+- If you're an OWNER of an OSDU group, you can add or remove the members of that group or delete the group.
+- If you're a MEMBER of an OSDU group, you can view, edit, or delete the service or data depending on the scope of the OSDU group. For example, if you're a MEMBER of the `service.legal.editor` OSDU group, you can call the APIs to change the legal service.
+
 > [!NOTE]
-> Do not delete the OWNER of a group unless there is another OWNER to manage the users. 
+> Don't delete the OWNER of a group unless there's another OWNER to manage the users.
 
 ## Entitlement APIs
 
-A full list of entitlements API endpoints can be found in [OSDU entitlement service](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/blob/release/0.15/docs/tutorial/Entitlements-Service.md#entitlement-service-api). A few illustrations of how to use Entitlement APIs are available in the [How to manage users](how-to-manage-users.md).
+For a full list of Entitlement API endpoints, see [OSDU entitlement service](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/blob/release/0.15/docs/tutorial/Entitlements-Service.md#entitlement-service-api). A few illustrations of how to use Entitlement APIs are available in [Manage users](how-to-manage-users.md).
+
 > [!NOTE]
-> The OSDU documentation refers to V1 endpoints, but the scripts noted in this documentation refer to V2 endpoints, which work and have been successfully validated.
+> The OSDU documentation refers to v1 endpoints, but the scripts noted in this documentation refer to v2 endpoints, which work and have been successfully validated.
 
 OSDU™ is a trademark of The Open Group.
 
 ## Next steps
-As the next step, you can do the following:
-- [How to manager users](how-to-manage-users.md)
-- [How to manage legal tags](how-to-manage-legal-tags.md)
-- [How to manage ACLs](how-to-manage-acls.md)
 
-You can also ingest data into your Azure Data Manager for Energy instance with
+For the next step, see:
+
+- [Manage users](how-to-manage-users.md)
+- [Manage legal tags](how-to-manage-legal-tags.md)
+- [Manage ACLs](how-to-manage-acls.md)
+
+You can also ingest data into your Azure Data Manager for Energy instance:
+
 - [Tutorial on CSV parser ingestion](tutorial-csv-ingestion.md)
 - [Tutorial on manifest ingestion](tutorial-manifest-ingestion.md)