Skip to content

OSDU Policy - User Details API Documentation

1. Overview

This document describes the User Details API feature for Policy Service. This optional feature enhances the Open Policy Agent (OPA) framework within OSDU by providing a mechanism to store temporary, arbitrary attributes for a user.

These attributes enable dynamic, fine-grained access policies. This is primarily intended for M2M (machine-to-machine) applications to maintain real-time user information with a short Time-To-Live (TTL). For example, an external application could temporarily assign a country code to a user, allowing them access to data only within a specific geographical region. This allow use of more real time attributes which in some cases couldn't be added to user token.

2. Architecture

The feature extends the Policy Service with new endpoints to manage user attributes. An administrator or an application with the service.policy.admin role can call the APIs to store, retrieve, or remove user's attributes. The data is saved to the configured backend. Currently, Redis and DynamoDB are supported.

Unlike other policy inputs, these user details are not pre-loaded into the OPA input document. Instead, the Rego policies themselves are responsible for actively fetching these details by making an http.send call to the Policy Service's /api/policy/v1/user endpoint during evaluation. This allows using those attributes in policies used by services which calls OPA directly (without a call to Policy Service)

3. Configuration & Setup

3.1. Enabling the Feature

The User Details API is enabled by default, To explicitly disable the feature, the following environment variable must be set: ENABLE_USER_API_SUPPORT=false This feature requires backend storage connection details (endpoint, auth, etc.). By setting CACHE_EXPIRE_TIME variable you can control default expiration time in seconds for stored attributes. If not set, it defaults to 900 seconds.

4. API Reference

4.1. PUT /api/policy/v1/user/{user_id}

Adds or updates the attributes for a specific user. Requires membership in the service.policy.admin group.

Parameters:

  • user_detail (object, required): A JSON object of key-value pairs to store. If the country_code key is present, its value will be validated as a two-letter ISO country code.
  • ttl (integer, optional): The Time-To-Live for the record in seconds. If not provided, the global CACHE_EXPIRE_TIME setting (or its default of 900s) will be used.
Details 
curl --location --request PUT 'https://{osdu-host}/api/policy/v1/user/data.scientist@osdu.com' \
--header 'data-partition-id: {partition}' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_detail": {
        "country_code": "CA"
    },
    "ttl": 600
}'

4.2. GET /api/policy/v1/user/{user_id}

Retrieves the attributes for a specific user. Requires membership in the service.policy.admin group.

Details 
curl --location --request GET 'https://{osdu-host}/api/policy/v1/user/data.scientist@osdu.com' \
--header 'data-partition-id: {partition}' \
--header 'Authorization: Bearer {AUTH_TOKEN}'
**Example Response Body:** 
{
  "user_detail": {
    "country_code": "CA"
  },
  "ttl": 398
}

4.3. DELETE /api/policy/v1/user/{user_id}

Deletes all attributes for a specific user. Requires membership in the service.policy.admin group.

Details 
curl --location --request DELETE 'https://{osdu-host}/api/policy/v1/user/data.scientist@osdu.com' \
--header 'data-partition-id: {partition}' \
--header 'Authorization: Bearer {AUTH_TOKEN}'

4.4. GET /api/policy/v1/user

Retrieves the details for the currently authenticated user. This is the endpoint called by OPA policies. Allows a user (or a policy acting on their behalf) to retrieve their own stored attributes.

Details 
# The user's token determines which user's details are returned.
curl --location --request GET 'https://{osdu-host}/api/policy/v1/user' \
--header 'data-partition-id: {partition}' \
--header 'Authorization: Bearer {USER_AUTH_TOKEN}'
**Example Response Body:** 
{
  "user_detail": {
    "country_code": "CA"
  },
  "ttl": 398
}

5. API Usage

Typically this API will be used by application maintaining a user's attributes and OPA Agent.

The application must have a valid OSDU authentication token (AUTH_TOKEN) for a principal in the service.policy.admin group.

In this example, an application sets the user's country_code. The TTL is not specified, so it will use the default for your instance. In next section it is described how to write rules using this data.

Details 
curl --location --request PUT 'https://{osdu-host}/api/policy/v1/user/data.scientist@osdu.com' \
--header 'data-partition-id: {partition}' \
--header 'Authorization: Bearer {AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_detail": {
        "country_code": "CA"
    }
}'

6. Writing Policies using this feature

Policies can leverage this feature by calling the User Details API during evaluation. This is best accomplished using a shared helper module.

6.1. Helper Module for Fetching User Attributes

This standard module can be included in your OPA instance to handle the API call. It retrieves the user details and makes them available for other policies to import.

package osdu.partition.osdu.userattributes

import rego.v1
import input

headers := {
    "Content-Type": "application/json",
    "data-partition-id": input.datapartitionid,
    "Authorization": sprintf("Bearer %v", [input.token]),
    "x-user-id": input.xuserid,
    "Accept": "application/json",
}

user_attributes_url := sprintf("%s%s", [opa.runtime().env.POLICY_BASE_URL, "/api/policy/v1/user"])

# The http.send call fetches the user data.
# Note: force_cache is used for performance. Adjust as needed.
attributes := http.send({
    "method": "GET",
    "url": user_attributes_url,
    "headers": headers,
    "force_cache": true,
    "force_cache_duration_seconds": 1,
})

6.2. Example Policies

With the helper module in place, you can write simple policies that enforce rules based on the fetched attributes.

Example 1: Allow Access from a Specific Country

This policy uses the helper module to allow access only to users whose country_code is "US".

package osdu.partition.osdu.locationrestriction

import rego.v1
import data.osdu.partition.osdu.userattributes

default allow := false

# Import the user details from the helper module's API response
user_details := userattributes.attributes.body.user_detail

# The 'allow' rule is true if the country_code is "US"
allow if {
    user_details.country_code == "US"
}

Example 2: Deny Access from a List of Blocked Countries

This policy denies access if the user's country_code is in a predefined blocklist.

```rego package osdu.partition.osdu.locationrestriction.deny

import rego.v1 import data.osdu.partition.osdu.userattributes

default allow := false

Define a set of countries from which access is blocked.

blocked_countries := {"KP", "IR", "CU", "SY"}

Import the user details from the helper module's API response

user_details := userattributes.attributes.body.user_detail

'allow' becomes true only if the user's country is NOT in the blocklist.

allow if { user_country := user_details.country_code not blocked_countries[user_country] }