How do I Implement Access Control?

You can restrict users’ access to data stored in TrueVault with granular Group Policies. This is a critical component of the security of your application, and we recommend enforcing minimal access for every user. Read more in our Access Control Best Practices guide.

Policies

Policies are composed of two components:

1. Resources: A list of resource specifiers that describe which Documents, Vaults, BLOBs, Users, or Groups the Policy grants access to.
2. Actions: A list of actions the policy authorizes for the specified resources.

For example, a resource could be all documents in my “patient records” vault. Actions could grant full access (Create, Read, Update, Delete) or be more restrictive and only allow read-only access. Using TrueVault policy syntax, these policies would be expressed by the following (assuming the patient records vault had id 00000000-0000-0000-0000-00000000000)

Full Access Policy

{
    "Resources":[
        "Vault::00000000-0000-0000-0000-000000000000::Document::"
        "Vault::00000000-0000-0000-0000-000000000000::Document::.*",
    ],
    "Activities":"CRUD"
}

Read Only Policy

{
    "Resources":[
        "Vault::00000000-0000-0000-0000-000000000000::Document::.*",
    ],
    "Activities":"R"
}

Each policy statement can have many resources and activities associated with it. Check out some example policies or dig into the policy access grid to get more details.

Ownership

Some policies define explicit resources: Documents in this vault, this specific Document ID, all Users, etc. This can be useful, but can be verbose in some cases. To simplify your policies, we built ownership for a common use case: users can read and modify their own data. In this model, you assign an owner to each record and can create one group for all users that allows them to read/modify their own data, but nobody else’s. Read more in our ownership guide.

Groups

Groups are the glue that bring users and policies together. A group can have many policies in it. A user can belong to many groups, and a group can have many users in it.

For example, if you’re building a healthcare product you might have a few roles: patients, doctors, staff. You could create one group for each role: a patient’s group that uses ownership to limit acccess, a doctor’s group that allows access to all patient’s data, and an staff group that allows access to billing data but not health records. In this case, you may think the doctor’s group is a little too permissive, and we’d agree. Do doctor’s need to see every patient, or only the one’s their assigned to? If you can minimize their access, do so (read more on our Access Control Best Practices guide).

To limit each doctor’s access, you could create a group-per-patient that allows access to that patient’s records. Then you could add a doctor to a patient’s group when they’re assigned to that patient.

Let’s look at the groups we’ve discussed in detail. If you were creating these groups through the api then you would want to specify the policies as a JSON Object. For the sake of this example, assume you have a “Patient Health Data” vault with id 00000000-0000-0000-0000-000000000000 and a “Patient Billing Data” vault with id 11111111-1111-1111-1111-111111111111. Each group takes an array of policies when you create it, like the following.

Patient’s Group Policy

In this group, patients can Create, Read, Update, and Delete their own data.

[ 
    {
        "Resources":[
            "Vault::00000000-0000-0000-0000-000000000000::Document::$[Owner=self]"
            "Vault::11111111-1111-1111-1111-111111111111::Document::$[Owner=self]"
        ],
        "Activities":"CRUD"
    }
]

Staff Group Policy

Staff can view and update billing data, but cannot create see health data, create new patients, or delete anything.

[ 
    {
        "Resources":[
            "Vault::11111111-1111-1111-1111-111111111111::Document::.*"
        ],
        "Activities":"RU"
    }
]

Doctor’s Group for Patient:

Doctor’s in this group can see and modify all the data for a specific patient. For this example, say the patient has the id aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa.

[ 
    {
        "Resources":[
            "Vault::00000000-0000-0000-0000-000000000000::Document::$[Owner=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa]"
            "Vault::11111111-1111-1111-1111-111111111111::Document::$[Owner=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa]"
        ],
        "Activities":"CRUD"
    }
]