Managing Access to an Asset With ABAC

Sharing Access within your Tenant

Caution: You will only have access to the Access Policies screen if you are a Root User in your Organization.

Attribute-Based Access Control (ABAC) policies can be used to control access to Assets, their Attributes, and Events within a single Organization.

Specifically, ABAC policies are created by Root Users to share information with Non-Root Users in the same Tenancy.

ABAC policies can be granular, with users allowed to see only single Attributes at a time, if wished.

It is possible to control policies based on types of Assets, their Location, and whether Users can read or write any information in an Asset.

By default, no Non-Root Users will see any existing Assets and Events unless a Root User explicitly creates an ABAC policy to allow it.

Creating an ABAC Policy

Consider the Shipping Container Asset we created. There may be many people within an organization who need access to specific Attributes of the container.

We shall create a policy for someone who needs to share some standard dimensions of the Shipping Container, inspect the cargo, and create Inspect Events.

  1. Create your Access Policy.

Navigate to the Access Policies section on the Sidebar of the RKVST Dashboard.

Managing Policies

Create an empty file, in later steps we will add the correct JSON.

{

}
  1. You may wish to view your existing policies before creating a new one.

Here you will see any existing policies and can select Add Policy.

Adding a Policy

You may view your existing policies before creating your new policy by executing the following curl command. See instructions for creating your BEARER_TOKEN_FILE here.

curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/iam/v1/access_policies
  1. Set the asset filters for your policy.

When adding a Policy, you will see this form:

Policy Web Form

Here you can apply policy filters to the correct Assets. In this case, we shall apply the policy to any Asset in the UK Factory Location created earlier, as well as the type of Asset (Shipping Container).

Filtering for specific Assets and Locations

Filters can use and or or to categorize assets. You may also use filters on attribute values, such as = and != for equal and not equal, respectively. These can be used for specific attribute values, or to check if the value exists at all. For example, to filter for Assets not associated with a location, you could use:

"attributes.arc_home_location_identity!=*"

The * is a wildcard that could represent any value. This will match not only on string values, but list and map values as well.

Following our Shipping Container example, this is how we would set our Asset filters:

{
    "display_name": "Bill Inspect Policy",
    "filters": [
        { "or": [
            "attributes.arc_home_location_identity=locations/<location-id>"
        ]},
        { "or": [
            "attributes.arc_display_type=Shipping Container"
        ]}
    ]
}

See here for instructions on finding your location ID.

  1. Next, enter the desired Permissions to set Users’ Asset and Event attribute access.

We select the Permissions Tab to set Users’ Asset and Event attribute access policy.

Default view of Policy Permissions

In this example, the User actor implies an ABAC policy, identified by email. Type the relevant email address and hit Enter; you may also see a dropdown list of users within your tenancy.

Adding a specific User to a Policy

There are a few ways you may add a User to your Access Policy using JSON. One way is to use the email address associated with their RKVST account. To do so, add the desired user_attributes to the access_permissions section.

 "access_permissions": [
        {
            "asset_attributes_read": ["arc_display_name", "arc_description", "arc_home_location_identity", "Length", "Weight"],
            "user_attributes": [
               {"or": ["email=user@email.com"]}
            ]
        }
    ]

You may also grant permissions to an App Registration within your tenancy. App Registrations are non-root by default; best practice is to use ABAC policies to preserve Principle of Least Privilege.

 "access_permissions": [
        {
            "asset_attributes_read": ["arc_display_name", "arc_description", "arc_home_location_identity", "Length", "Weight"],
            "user_attributes": [
               {"or": ["subject=<client-id>"]}
            ]
        }
    ]
Note: This is different from adding subjects as a key in your access_permissions, for example, when adding an external Subject ID to an OBAC policy. The user attribute subject refers to the Client ID associated with an App Registration.

Additionally, you may set permissions based on the Custom Claims of an App Registration using JSON Web Tokens (JWTs). To do so, you must include the prefix jwt_ followed by the desired claim as one of the user_attributes in the policy. For example, the key jwt_app_reg_role to match on claim app_reg_role.

 "access_permissions": [
        {
            "asset_attributes_read": ["arc_display_name", "arc_description", "arc_home_location_identity", "Length", "Weight"],
            "user_attributes": [
               {"or": ["jwt_app_reg_role=tracker"]}
            ]
        }
    ]
  1. Once all relevant details are complete, add the Permission Group to the policy. You may add multiple permission groups per policy if you wish.

    Enter desired permissions and select Add Permission Group.

    Permitted Attributes on an Asset

    Add the desired permissions and the desired user_attributes.

    {
        "display_name": "Bill Inspect Policy",
        "filters": [
            { "or": [
                "attributes.arc_home_location_identity=locations/<location-id>"
            ]},
            { "or": [
                "attributes.arc_display_type=Shipping Container"
            ]}
        ],
        "access_permissions": [
            {
                "asset_attributes_read": ["arc_display_name", "arc_description", "arc_home_location_identity", "Length", "Weight"],
                "user_attributes": [
                    {"or": ["email=bill@rkvst.com"]}
                ]
            }
        ]
    }
    

Note we have included RKVST-sigificant attributes: arc_display_name, arc_description, and arc_home_location_identity.

arc_* attributes have special significance in RKVST; in this case, respectively, allowing visibility to the Name, Description, and Location of the Asset. Other arc_* attributes are also available.

  1. Once complete, finish creating the Access Policy.

Select Create Policy.

Submitting a Policy

Use the curl command to run your JSON file! See instructions for creating your BEARER_TOKEN_FILE here.

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/iam/v1/access_policies
  1. Check the Asset is appropriately shared.

Bill should only be allowed to see the Asset’s Name, Location, Length, and Weight Attributes.

Bill's view as a Non-Root User

For comparison with our Root User, Jill:

Jill's view as a Root User

We can see that Bill can only view the Attributes specified in the policy. He can also see the Event where we updated the Location.

Our Root User, Jill, can see every detail associated with the Asset.

Edit this page on GitHub