How to manage users
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 groups, 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.
- Generate the access token needed to call the Entitlements APIs.
- Get various parameters of your instance such as client-id, client-secret, etc.
- 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
- Navigate to the Microsoft Entra account for your organization. You can search for "Microsoft Entra ID" in the Azure portal's search bar.
- Locate
tenant-id
under the basic information section in the Overview tab. - Copy the
tenant-id
and paste it into an editor to be used later.
Find client-id
It's the same value that you use to register your application during the provisioning of your Azure Data Manager for Energy instance. It is often referred to as app-id
.
- Find the
client-id
in the Essentials pane of Azure Data Manager for Energy Overview page. - Copy the
client-id
and paste it into an editor to be used later. - 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 that was used for provisioning your Azure Data Manager for the Energy instance.
Find client-secret
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.
- Navigate to App Registrations.
- Open 'Certificates & secrets' under the Manage section.
- Create a
client-secret
for theclient-id
that you used to create your Azure Data Manager for Energy instance. - Add one now by clicking on New Client Secret.
- Record the secret's
value
for later use in your client application code. - The access token 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. This secret value is never displayed again after you leave this page of 'client secret' creation.
Find the URL
for your Azure Data Manager for Energy instance
- Navigate to your Azure Data Manager for Energy Overview page on the Azure portal.
- Copy the URI from the essentials pane.
Find the data-partition-id
- You have two ways to get the list of data partitions in your Azure Data Manager for Energy instance.
- One option is to navigate the Data Partitions menu item under the Advanced section of your Azure Data Manager for Energy UI.
- 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.
Generate service principal access token
- 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
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 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.
- 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.
- 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.
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 access token of the app that was used to provision the instance.
- Get the service principal access token using Generate service principal access token.
- If you try to directly use user tokens for adding entitlements, it results in 401 error. The service principal access token must be used to add initial users in the system and those users (with admin access) can then manage more users.
- Use the service principal access token to do these three steps using the commands outlined in the following sections.
- Add the users to the
users@<data-partition-id>.<domain>
OSDU group. - Get the OSDU group such as
service.legal.editor@<data-partition-id>.<domain>
you want to add the user to. - Add the users to that group.
- Add the users to the
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.
curl --location --request GET "https://<URI>/api/entitlements/v2/groups/" \
--header 'data-partition-id: <data-partition>' \
--header 'Authorization: Bearer <access_token>'
Add users to an OSDU group in a data partition
- Run the below curl command in Azure Cloud Bash to add the user(s) to the "Users" group using the Entitlement service.
- The value to be sent for the param
email
is theObject_ID
(OID) of the user and not the user's email.
curl --location --request POST 'https://<URI>/api/entitlements/v2/groups/<group-name>@<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"
}'
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
- 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 OSDU groups of a given user in a data partition
- Run the below curl command in Azure Cloud Bash to delete a given user from a given data partition.
- DO NOT delete the OWNER of a group unless you have another OWNER who 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 data partition.
Begin your journey by ingesting data into your Azure Data Manager for Energy instance.
Feedback
Submit and view feedback for