Create Virtual Resources and MDS Policies¶

Resources are not discovered automatically. Declare them in the Data Catalog before a policy can reference them. This is called a virtual resource.

One API call creates the virtual resource, if it does not already exist, and the matching access policy. The revoke call also creates the resource if it does not exist.

A successful call returns 200 OK with an empty body, even when nothing changed. A revoke that matches no grant, for example because the path differs in case, also returns 200 OK. To confirm the result, go to Data Browser → Data Catalog, open the resource, and check that its access permissions list the principal with the expected permission. The resource being present is not proof, because both calls create it.

Register a resource without a policy

The call on this page also grants access. To register the resource only, use the Creating Resources via API endpoint, linked under Create tag-based and other policies below.

Create the principals first

The users, groups, or roles named in the request must already exist in Privacera.

Who can call these endpoints

The caller must be a Privacera admin, or the zone admin of the security zone that governs the resource. For a resource that does not exist yet, that is the zone of its nearest existing parent.

Get the API base URL¶

Partially Managed (D2P)Self Managed

In the Portal, go to Settings → API Keys → Generate API Keys.
Enter a Purpose and an Expiry date, then copy the generated API key.
Select the info icon next to the key and copy the Ranger Admin URL.
Replace __API_KEY__ with that key and append /omni-metadata, for example https://apiserver.example.com/api/a1b2c3d4/omni-metadata:
```
https://<apiserver-host>/api/<api-key>/omni-metadata
```

The key in the URL authenticates the request, so no authorization header is needed.

Turn on Crypto UI under Settings → System Configurations. Create a token with Type MDS and the Metadata Write scope under Settings → Token Management. A zone admin of the security zone that governs the resource can use a Metadata Read token instead; anyone else gets 403 Forbidden.
Use the URL the Omni Metadata Service is exposed at on your plane. The service is not published under a fixed hostname, so ask whoever set up the ingress. A common form is omni-metadata-<namespace> on the plane's domain, for example https://omni-metadata-runtime-plane.example.com:
```
https://<omni-metadata-service-host>
```
Send the token on every request:
```
Authorization: Bearer <mds-token>
```

Set Content-Type: application/json on every request.

S3¶

Grant on the folder, not on the file

Policies apply at the folder level. For an object such as s3://<bucket>/user/data/sample/sample.txt, create the policy on the folder that contains it:

<bucket>/user/data/sample/

A grant covers the folder and everything under it, including objects added later. Use the narrowest folder.

Grant read access¶

Bash
curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <mds-token>' \
    -d '{
      "resource": {
        "serviceName": "privacera_s3",
        "serviceType": "S3",
        "resourceType": "OBJECTPATH",
        "resourcePath": "<bucket>/<prefix>/"
      },
      "grant": {
        "permission": "READ",
        "principals": {
          "users": ["<user>"],
          "groups": ["<group>"],
          "roles": ["<role>"]
        }
      }
    }' \
    <mds-base-url>/api/v2/metadata/omni-policies/enforcement/grant-access/resources

Replace the placeholders and check serviceName:

Placeholder	Description
`<mds-base-url>`	The base URL from the start of this page.
`<mds-token>`	Self-Managed only. The MDS token from the start of this page. On D2P the API key in the URL authenticates the request, so omit this header.
`<bucket>`	The S3 bucket name.
`<prefix>`	The object path inside the bucket, without a leading or trailing `/`, for example `user/data/sample`. The payload adds the trailing `/` that marks a folder.
`serviceName`	The service repository the connector enforces against: `privacera_s3` by default. If a custom service repository is configured, use its name.
`<user>`, `<group>`, `<role>`	The principals to grant to. All three keys are optional — send only the ones you need. Each principal must already exist in Privacera.

Grant write access¶

Send the same request with "permission": "WRITE".

READ and WRITE expand to these S3 access types:

Permission	Access types granted
`READ`	`read`, `mread`
`WRITE`	`read`, `write`, `delete`, `mwrite`, `admin`, `mread`

Leave accessTypes unset.

Revoke access¶

Send the same resource with a revoke object that holds only principals.

Bash
curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <mds-token>' \
    -d '{
      "resource": {
        "serviceName": "privacera_s3",
        "serviceType": "S3",
        "resourceType": "OBJECTPATH",
        "resourcePath": "<bucket>/<prefix>/"
      },
      "revoke": {
        "principals": {
          "users": ["<user>"],
          "groups": ["<group>"],
          "roles": ["<role>"]
        }
      }
    }' \
    <mds-base-url>/api/v2/metadata/omni-policies/enforcement/revoke-access/resources

Revoke removes all access, READ and WRITE, that the listed principals have on the resource. To downgrade WRITE to READ, grant READ instead. A new grant replaces the existing one.

Resource types¶

S3 resources have two levels:

Resource type	Path shape	Example
`BUCKETNAME`	`<bucket>`	`test-bucket`
`OBJECTPATH`	`<bucket>/<prefix>/`	`test-bucket/user/data/sample/`

Bucket-level grants

A grant on a bucket covers every object in it. It is refused unless the request URL ends with ?allowContainerLevelAccess=true. Prefer a folder.

Note

Object paths are case sensitive, so the path must match the object exactly.

Masking and row-level filtering do not apply to S3.

Create tag-based and other policies¶

Once a resource is in the Data Catalog:

Task	Where
Create a tag	Tags and Metadata
Register a resource without creating a policy	Creating Resources via API
Attach a tag to a resource	Applying Tags to Resources via API
Create an access policy	Policies

For a tag-based policy, tag the resources first, then set the policy Data scope to Data Tag.

Note

Tag-based policies are enforced by this connector only after Privacera Support enables tag-based enforcement for plugin services.

Verify¶

Read the path from a Spark session, once as a granted user and once as a denied user.

Python
spark.read.parquet("s3a://<bucket>/<prefix>/").show()

Then, in the portal, go to Access Management → Audits → ACCESS and confirm an Allowed or Denied record for that user and resource.

Prev topic: Connector Guide