Manage users in Azure Data Manager for Energy

In this article, you learn how to manage users and their memberships in OSDU groups in Azure Data Manager for Energy. Entitlements APIs 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 group concepts, see Entitlements.

Prerequisites

• Create an Azure Data Manager for Energy instance. See How to create Azure Data Manager for Energy instance.
• Get various parameters of your instance, such as client-id and client-secret. See How to generate auth token.
• Generate the service principal access token that's needed to call the Entitlement APIs. See How to generate auth token.
• Keep all the parameter values handy. They're needed to run different user management requests via the Entitlements API.

Fetch object-id

The Azure object ID (OID) is the Microsoft Entra user OID.

1. Find the OID of the users first. If you're managing an application's access, you must find and use the application ID (or client ID) instead of the OID.

2. Input the 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. You can not use user's email ID in the parameter and must use object ID.

   

   

First-time addition of users in a new data partition

1. To add the first admin to a new data partition of an Azure Data Manager for Energy instance, use the access token of the OID that was used to provision the instance.

2. Get the client-id access token by using Generate client-id access token.

   If you try to directly use your own access token for adding entitlements, it results in a 401 error. The client-id access token must be used to add the first set of users in the system. Those users (with admin access) can then manage more users with their own access token.

3. Use the client-id access token to do the following steps by using the commands outlined in the following sections:

   1. Add the user to the users@<data-partition-id>.<domain> OSDU group with the OWNER role.
   2. Add the user to the users.datalake.ops@<data-partition-id>.<domain> OSDU group with the OWNER role to give access of all the service groups.

4. The user becomes the admin of the data partition. The admin can then add or remove more users to the required entitlement groups:

   1. Get the admin's auth token by using Generate user access token with the same client-id and client-secret values.
   2. Get the OSDU group, such as service.legal.editor@<data-partition-id>.<domain>, to which you want to add more users by using the admin's access token.
   3. Add more users to that OSDU group by using the admin's access token.

5. users.data.root is the default and permanent OWNER of all the data records when the records get created automatically in the system. Hence, if the user, who created the record and is the OWNER of the record, leaves the organization, the members of users.data.root always have the access of all the data records. For more details, check out Data Root Group.

6. As you add more members to a given OSDU group, there is a limit of 5000 membership for a given identity as defined by the OSDU community.

To know more about the OSDU bootstrap groups, check out here.

Get the list of all the groups you have access to in a data partition

Run the following curl command in Azure Cloud Shell to get all the groups that are available for you or that you have access to in the specific data partition of the Azure Data Manager for Energy instance.

    curl --location --request GET "https://<adme-url>/api/entitlements/v2/groups/" \
    --header 'data-partition-id: <data-partition>' \
    --header 'Authorization: Bearer <access_token>'

Add members to an OSDU group in a data partition

1. Run the following curl command in Azure Cloud Shell to add the users to the users group by using the entitlement service.

2. The value to be sent for the parameter email is the OID of the user and not the user's email address.

       curl --location --request POST 'https://<adme-url>/api/entitlements/v2/groups/<group-name>@<data-partition-id>.<domain>/members' \
       --header 'data-partition-id: <data-partition-id>' \
       --header 'Authorization: Bearer <access_token>' \
       --header 'Content-Type: application/json' \
       --data-raw '{
                       "email": "<Object_ID_1>",
                       "role": "MEMBER"
                   },
                  {
                       "email": "<Object_ID_2>",
                       "role": "MEMBER"
                   }
                  '
   

   Sample request for users OSDU group

   Consider an Azure Data Manager for Energy instance named medstest with a data partition named dp1.

       curl --location --request POST 'https://medstest.energy.azure.com/api/entitlements/v2/groups/users@medstest-dp1.dataservices.energy/members' \
       --header 'data-partition-id: medstest-dp1' \
       --header 'Authorization: Bearer abcdefgh123456.............' \
       --header 'Content-Type: application/json' \
       --data-raw '{
                       "email": "90e0d063-2f8e-4244-860a-XXXXXXXXXX",
                       "role": "MEMBER"
                   }'
   

   Sample response

       {
           "email": "90e0d063-2f8e-4244-860a-XXXXXXXXXX",
           "role": "MEMBER"
       }
   

   Sample request for legal service editor OSDU group

       curl --location --request POST 'https://medstest.energy.azure.com/api/entitlements/v2/groups/service.legal.editor@medstest-dp1.dataservices.energy/members' \
       --header 'data-partition-id: medstest-dp1' \
       --header 'Authorization: Bearer abcdefgh123456.............' \
       --header 'Content-Type: application/json' \
       --data-raw '{
                       "email": "90e0d063-2f8e-4244-860a-XXXXXXXXXX",
                       "role": "MEMBER"
                   }'
   

   Important

   The app ID is the default OWNER of all the groups.

   

Get OSDU groups for a given user in a data partition

1. Run the following curl command in Azure Cloud Shell to get all the groups associated with the user.

       curl --location --request GET 'https://<adme-url>/api/entitlements/v2/members/<obejct-id>/groups?type=none' \
       --header 'data-partition-id: <data-partition-id>' \
       --header 'Authorization: Bearer <access_token>'
   

   Sample request

   Consider an Azure Data Manager for Energy instance named medstest with a data partition named dp1.

       curl --location --request GET 'https://medstest.energy.azure.com/api/entitlements/v2/members/90e0d063-2f8e-4244-860a-XXXXXXXXXX/groups?type=none' \
       --header 'data-partition-id: medstest-dp1' \
       --header 'Authorization: Bearer abcdefgh123456.............'
   

   Sample response

       {
       "desId": "90e0d063-2f8e-4244-860a-XXXXXXXXXX",
       "memberEmail": "90e0d063-2f8e-4244-860a-XXXXXXXXXX",
       "groups": [
           {
           "name": "users",
           "description": "Datalake users",
           "email": "users@medstest-dp1.dataservices.energy"
           },
           {
           "name": "service.search.user",
           "description": "Datalake Search users",
           "email": "service.search.user@medstest-dp1.dataservices.energy"
           }
       ]
       }
   

Remove a member from a group in a data partition

1. Run the following curl command in Azure Cloud Shell to remove a specific member from a group.

2. If the API tries to remove a member from users@ group but the member is already part of other groups, then the API request will fail. To remove member from users@ group and thus from the data partition, you can use Delete command.

       curl --location --request DELETE 'https://<adme-url>/api/entitlements/v2/groups/<group-id>/members/<object-id>' \
       --header 'data-partition-id: <data-partition-id>' \
       --header 'Authorization: Bearer <access_token>'
   

Delete a specific user from all the groups in a data partition

1. Run the following curl command in Azure Cloud Shell to delete a specific user from a specific data partition.

2. Do not delete the OWNER of a group unless you have another OWNER who can manage users in that group. Though users.data.root is the default and permanent owner of all the data records.

       curl --location --request DELETE 'https://<adme-url>/api/entitlements/v2/members/<object-id>' \
       --header 'data-partition-id: <data-partition-id>' \
       --header 'Authorization: Bearer <access_token>'
   

   Sample request

   Consider an Azure Data Manager for Energy instance named medstest with a data partition named dp1.

       curl --location --request DELETE 'https://medstest.energy.azure.com/api/entitlements/v2/members/90e0d063-2f8e-4244-860a-XXXXXXXXXX' \
       --header 'data-partition-id: medstest-dp1' \
       --header 'Authorization: Bearer abcdefgh123456.............'
   

   Sample response

   No output for a successful response.

Next steps

After you add users to the groups, you can:

• Manage legal tags
• Manage ACLs

You can also ingest data into your Azure Data Manager for Energy instance:

• Tutorial on CSV parser ingestion
• Tutorial on manifest ingestion