On this page you will find a brief description of Tachyon's RBAC system and its components.
You will also learn how to configure Tachyon's RBAC to suit your needs.
One thing you should remember is that Tachyon's RBAC system has a number of "System" objects, which cannot be modified.
This page isn't intended as an in-depth explanation of what RBAC is, but rather as a demonstration how it's been implemented in Tachyon and how users can configure it programaticaly.
C# examples assume you are using Tachyon Consumer SDK and assume that you already have a correctly instantiated instance of Tachyon connector class in an object called 'connector'.
Another thing to remember is that all SDK methods return the same class called ApiCallResponse. Inside the object of that class you'll find a property called ReceivedObject. That object is the actual data received from the API. We will be omitting this detail in the examples and simply saying that the return object contains the data. So when we're saying that XYZ object will contain such-and-such data, what we mean in that the ReceivedObject contains that data, since that is always the case.
Basics of role based access control (RBAC)
Role-based access control is an access control mechanism defined around roles and privileges.
This security model pivots around the concept or a Role. Users (called principals in Tachyon) can be assigned to a Role and it is through Role that they gain permissions to perform actions.
Every element of Tachyon's security system sooner or later leads back to a Role.
RBAC objects in Tachyon
Tachyon has several types of objects that are part of its RBAC system. This section is a brief description of these objects and their purpose.
Principals are synonymous with users. They are not called users because the word 'user' is traditionally associated with a person, while a principals is, from a technical standpoint, an Active Directory account, which may be a user account or a machine account. It can also be an AD group.
Tachyon allows only principals authenticated through Windows auth and known to Tachyon itself. Then, depending on the request, permissions of the calling principal are established by looking at the roles that principals is assigned to.
By default, a fresh installation of Tachyon will have a principal representing the user account installing it.
Role is what all the permissions lead to. Principals will have to have roles assigned before they can use the system.
A permissions is an ability to perform an operation on a securable type.
A Securable type is type of an object that can have permissions assigned to it. For instance, Instructions can have permissions, as can Consumers and Management Groups. In fact, security itself is an object that principals will need permissions to in order to modify it so it will too have a securable type.
In short, if an element of Tachyon is to have security defined for it, it must have a securable type.
An Operation (or Applicable Operation as it also called) represents type of an action that can be performed on a securable type. This can be something like "Read", "Write" and alike.
Bringing it all together
So how does it all go together then? We'll see that in this sentence:
Marc (principal) through Global Questioners (role) has Questioner (Applicable Operation) permission on Instructions (Securable type)
Let's examine this sentence. As we can see, a Principal will have a specific permission on given securable type through a role said principal belongs to. This is the only way principals can obtain permissions and permissions are always for a specific operation on a given type.
To establish full permission set of a given principal you have to combine all permissions from all the roles the principal is assigned to.
You can retrieve permissions in several different ways, depending from which perspective you want to look from: a Principal, a Role or a Securable Type.
Some APIs perform checks for the calling user by pulling the user information from the HTTP request itself. Other APIs allow you to specify which object you want to get permissions for.
Getting permissions for a Principal
Getting all Permissions
Retrieve principal's permissions is done using the account name (for instance "somedomain\jane.doe") of that principal. When using the API directly, you have to encode that account name into base64 before sending it, while Consumer API SDK will do the encoding for you.
In the examples below we will use the aftermentioned "somedomain\jane.doe" account.
|Direct Consumer API call||C# code using Consumer SDK library|
Making a GET request to /Permissions/Principal/c29tZWRvbWFpblxqYW5lLmRvZQ== will yield following response:
Use Permissions object inside the Tachyon connector instance.
"permissions" object will contain the same data you can see in the JSON response on the left.