Entitlements API (Open Data for Industries)

{groupType}.{serviceName|resourceName}.{permission}@{data-partition-id}.{domain}.com

Valid data partition user account

The Entitlements API verifies user account member identity in the JSON Web Token (JWT) of the authorization header against specified data-partition-id. The data-partition-id is also provided in a header.

Valid data partition service account

The Entitlements API verifies service account member identity in the JWT of the authorization header against specified data-partition-id. The data-partition-id is also provided in a header.

User and service account authorization

Open Data for Industries uses service group authorization to determine whether the user or service account that is calling another service has the proper permissions to start it. User or service account must provide a JWT to identify themselves to the API that they are calling. The JW token must be provided in the Authorization header of the API call. If a service is calling another service, the calling service must provide a valid OAuth token to identify itself to the called API.

In each data partition where a service account is provisioned for access, you must associate the service account with the service groups.

To authorize access to an identity, call the GET /api/entitlements/v2/groups by providing:

1. A JSON Web Token in the authorization header.
2. The required data partition identifier in the data_partition_id attribute in the header.

For more information, see List groups in the Open Data for Industries API reference.

The Entitlements API returns a list of all the groups that the user or service account can access, if the following requirements are met.

• The service account is a member of the specified data partition.
• The service account is a member of service.entitlements.user group in the specified data partition.

If one of these conditions is not met, the Entitlements API returns an Unauthorized error.

If all the conditions are met, the Entitlements API inspects the list of groups to determine whether the requested group; for example, service.my_service.user, is on the list. Depending on result, the API authorizes access.

Before you authorize access for any resource through the Entitlements API, you must:

• Ensure that you have the access token and it is part of the request's header when you are calling any of the Open Data for Industries APIs.
• Ensure that the user or service account is a member of the specified data partition.

  Add the user or the service account email for the service, which uses the Open Data for Industries APIs in a specific data partition, to the users@{data-partition-id}.{domain} group of the specified data partition. For example, storage_viewer@{data-partition-id}.{domain} must be added to users@{data-partition-id}.{domain}.

• Ensure that the user or service account can use the Entitlements API.

  Add the user or the service account email for the service, which uses the Entitlements API to authorize the service in a specific data partition, to the users of the Entitlements API. The group is named service.entitlements.user. For example, storage_viewer@{data-partition-id}.{domain} must be added to service.entitlements.user@{data-partition-id}.{domain}.

To authorize calls to the Open Data for Industries APIs

1. In each data partition where a service is used, create a group with the permissions or roles that the service supports.

   For example, if you create a service that is called my_service, for the user and admin roles, you must create the service.my_service.user and service.my_service.admin groups for all relevant data partitions.

2. Add all users that are authorized to call a specific API to the group that has the role that you want on the service.

   For example, to grant a user role to the user joe@customer.com for the service my_service in the data partition my_data_partition, add joe@customer.com to service.my_service.user@my_data_partition.{domain}.

Data authorization

After the user or service account is authorized to access the Storage API in Open Data for Industries, the data authorization uses the associated group permissions on the data. The Access Control List (ACL) that is provided in the record to be ingested is directly applied on MinIO objects. Thus, the Storage API uses the user authorization mechanism to determine whether the user has access to the record.

Endpoint sample command

curl --location --request POST $cpdBaseUrl/osdu-entitlements-v2/api/entitlements/v2/tenant-provisioning \
--header 'data-partition-id: <<data_partition_id>> \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--data-raw ""

Note:

• The API can be applied multiple times without any effect on the state of the system.
• The API needs to be ran for newly provisioned partitions before the partition can be used.
• It is not allowed to delete the groups and the relations that are created between them as part of the bootstrap process. However, new associations can be created by using the Entitlements API endpoints.

POST /api/entitlements/v2/groups

Creates the group within the data partition that is provided in the data partition ID request header. This endpoint is used to create service and data groups.

This endpoint creates a group with the following email mnemonics: {group_name}@{data-partition-id}.{domain}.

{{data-partition-id}}

Placed or provided in the request header.

{{domain}}

The domain of the Open Data for Industries application, which is configured during installation. It can be retrieved from config maps.

{{JWT}}

Received as authorization token in the header. The user of the token is made OWNER of the group.

Note: The user or service whose token is used, must belong to service.entitlements.admin@{data-partition-id}.{domain}.com group.

{{group_name}}

The name of the group, which is following the group nomenclature that is defined for Open Data for Industries. The only exception is the part, which includes ‘@’, and the part after it.

For example, you need to provide only storage.well.editors from storage.well.editors@{data-partition-id}.{domain}.

curl --request POST --url 'https://{{cpd_cluster_url}}/{{entitlement_service_context}}/api/entitlements/v2/groups' \
  --header 'authorization: Bearer {{JWT}}' \
  --header 'content-type: application/json' \
  --header 'data-partition-id: {{data-partition-id}}' \
  --data '{
             "name": "{{group_name}}",
             "description": "This is a user or service group with permission defined."
         }'

GET /api/entitlements/v2/groups

Lists all the groups for data partition, which are provided as data partition ID in the request header parameter.

The result is a flat list of all the groups that are associated with the partition identity.

{{data-partition-id}}

Placed or provided in the request header.

{{JWT}}

Received as authorization token in the header. The user of the token is made an OWNER of the group.

curl --request GET \
  --url 'https://{{cpd_cluster_url}}/{{entitlement_service_context}}/api/entitlements/v2/groups' \
  --header 'authorization: Bearer {{JWT}}' \
  --header 'content-type: application/json' \
  --header 'data-partition-id: {{data-partition-id}}'

POST /api/entitlements/v2/groups/{{group_email}}/members

Adds members to a group. Used to associate users or groups to groups or child groups.

The member added can either be a user or a group. The group email value is {group_name}@{data-partition-id}.{domain}.

{{data-partition-id}}

Placed or provided in the request header.

{{domain}}

The domain of the Open Data for Industries application, which is configured during installation. It can be retrieved from config maps.

{{JWT}}

Received as authorization token in header.

Note: The user or service whose token is used, must belong to service.entitlements.admin@{data-partition-id}.{domain}.com group.

{{group_email}}

The name of the group. It follows the group nomenclature, which is defined for Open Data for Industries. The group email has a structure such as {group_name}@{data-partition-id}.{domain}.

{{group_member_email}}

The member email identity, which is to be associated with the group.

{{group_member_role}}

Member role can be either OWNER, or MEMBER.

curl --request POST   --url  'https://{{cpd_cluster_url}}/{{entitlement_service_context}}/api/entitlements/v2/groups/{{group_email}}/members' \
  --header 'authorization: Bearer {{JWT}}' \
  --header 'content-type: application/json' \
  --header 'data-partition-id: {{data-partition-id}}' \
  --data '{
            "email": "{{group_member_email}}",
            "role": "{{group_member_role}} "
          }'

GET /api/entitlements/v2/groups/{{group_email}}/members

Retrieves members that belong to a group_email within the data partition, which is provided in the data-partition-id request header.

Associate users or groups to groups or child groups

{{data-partition-id}}

Placed or provided in the request header.

{{JWT}}

Received as authorization token in header.

Note: The user or service whose token is used, must belong to users.datalake.admins@{data-partition-id}.{domain}.com group, or is the OWNER of the {{group_email}}.

{{group_email}}

The name of the group. It follows the group nomenclature, which is defined for Open Data for Industries. The group email has a structure such as {group_name}@{data-partition-id}.{domain}

{{role}}

Query parameter role can be specified to filter group members by role of OWNER or MEMBER.

{{includeType}}

Retrieve whether a member is of a type USER or GROUP.

curl --request GET   --url 'https://{{cpd_cluster_url}}/{{entitlement_service_context}}/api/entitlements/v2/groups/{{group_email}}/members?includeType=false&role=OWNER' \
  --header 'authorization: Bearer {{JWT}}' \
  --header 'content-type: application/json' \
  --header 'data-partition-id: {{data-partition-id}}'

DELETE /api/entitlements/v2/groups/{{group_email}}/members/{{group_member_email}}

Deletes or removes a member, which is identified in the path parameter ‘group_member_email’ from group ‘group_email’ within the data partition. The deleted member can either be a user, or a group.

Used to disassociate users or groups from groups or child groups.

{{data-partition-id}}

Placed or provided in the request header.

{{JWT}}

Received as authorization token in header.

Note: The user or service whose token is used, must belong to service.entitlements.user@{data-partition-id}.{domain}.com group, or is the OWNER of the {{group_email}}.

{{group_email}}

The name of the group. It follows the group nomenclature, which is defined for Open Data for Industries. The group email has a structure such as {group_name}@{data-partition-id}.{domain}.

{{group_member_email}}

The member email identity, which is disassociated with the group.

curl --request DELETE   --url 'https://{{cpd_cluster_url}}/{{entitlement_service_context}}/api/entitlements/v2/groups/{{group_email}}/members/{{group_member_email}}' \
  --header 'authorization: Bearer {{JWT}}' \
  --header 'content-type: application/json' \
  --header 'data-partition-id: {{data-partition-id}}'

DELETE /api/entitlements/v2/groups/{{group_email}}

Deletes the Entitlements group, which is identified in the path parameter ‘group_email’ within the data partition, provided in data-partition-id request header parameter.

{{data-partition-id}}

Placed or provided in the request header.

{{JWT}}

Received as authorization token in header.

Note: The user or service whose token is used, must belong to service.entitlements.user@{data-partition-id}.{domain}.com group, or is the OWNER of the {{group_email}}.

{{group_email}}

The name of the group. It follows the group nomenclature, which is defined for Open Data for Industries. The group email has a structure such as {group_name}@{data-partition-id}.{domain}.

curl --request DELETE   --url 'https://{{cpd_cluster_url}}/{{entitlement_service_context}}/api/entitlements/v2/groups/{{group_email}} \
  --header 'authorization: Bearer {{JWT}}' \
  --header 'content-type: application/json' \
  --header 'data-partition-id: {{data-partition-id}}'