DataTrails

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 an Administrator 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 Administrators to share information with Non-Administrators in the same Tenancy.

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

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-Administrators will see any existing Assets and Events unless an Administrator explicitly creates an ABAC policy to allow it.

To create an ABAC policy, first add users to your tenancy.

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 DataTrails dashboard.

    Managing Policies

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

    {

}

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

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

    Creating 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 "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/access_policies

  3. 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.

  4. Enter the desired Permissions to set user’s 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 DataTrails account. To do so, add the desired user_attributes to the access_permissions section.

    You may grant access to specific attachments by specifying the corresponding key in the access_permissions.
     "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"]}
            ]
        }
    ]

  5. 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@datatrails.ai"]}
            ]
        }
    ]
}

    Note: we have included DataTrails-significant attributes: arc_display_name, arc_description, and arc_home_location_identity arc_* attributes have special significance in DataTrails.
    In this case, respectively, allowing visibility to the Name, Description, and Location of the Asset. Other arc_* attributes are also available.

  6. Once complete, finish creating the Access Policy.

    Select Create Policy.

    Submitting a Policy

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

    curl -v -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/archivist/iam/v1/access_policies

  7. Check the Asset is appropriately shared

    Mandy should only be allowed to see the Asset’s Name, Location, Length, and Weight attributes

    Mandy's view as a Non-Administrator

    For comparison with our Administrator, Jill:

    Jill's view as a Administrator

We can see that Mandy can only view the Attributes specified in the policy. She can also see the Event where we updated the location.

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

← Verified Domain
Sharing Assets outside your Tenant →