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 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.
Prerequisites
Create an Azure Data Manager for Energy instance using the tutorial at How to create Azure Data Manager for Energy instance.
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.
Find tenant-id
Navigate to the Azure Active Directory account for your organization. One way to do so is by searching for "Azure Active Directory" 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.
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. 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.
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.
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.
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'.
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 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.
- 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.
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.
Request format
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>'
Sample response
{
"token_type": "Bearer",
"expires_in": 86399,
"ext_expires_in": 86399,
"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
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.
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 Azure Active Directory User Object ID.
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.
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
Run the below curl command in Azure Cloud Bash to add user(s) to the "Users" group using Entitlement service.
curl --location --request POST 'https://<URI>/api/entitlements/v2/groups/users@<data-partition-id>.dataservices.energy/members' \
--header 'data-partition-id: <data-partition-id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "<Object_ID>",
"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"
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"
}
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.
curl --location --request POST 'https://<URI>/api/entitlements/v2/groups/service.search.user@<data-partition-id>.dataservices.energy/members' \
--header 'data-partition-id: <data-partition-id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "<Object_ID>",
"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"
curl --location --request POST 'https://medstest.energy.azure.com/api/entitlements/v2/groups/service.search.user@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"
}
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.
curl --location --request GET 'https://<URI>/api/entitlements/v2/members/<OBJECT_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"
}
]
}
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.
As stated above, DO NOT delete the OWNER of a group unless you have another OWNER that can manage users in that group.
curl --location --request DELETE 'https://<URI>/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
Create a legal tag for your Azure Data Manager for Energy instance's data partition.
Begin your journey by ingesting data into your Azure Data Manager for Energy instance.
Feedback
Submit and view feedback for