What is Sentinel?

Sentinel is the RBAC system of Tranxactor. RBAC means "Role-Based Access Control". Sentinel controls who can log in to the Back Office. It also controls what each person can see and do there. This page tells you how. You need approximately five minutes.

You do not give access to each person one by one. You give each person a role, and the role sets what the person can see and do.

PersonSam

Role (User Type)Display

AccessLook up members, Member notes

In Sentinel, the role is the User Type. For example, Xena gives Sam the User Type "Display". Sam can then look up members, but Sam cannot issue vouchers.

Two parts

Part 1 is Sentinel. Sentinel sets and keeps the access. Part 2 is the Back Office. The Back Office uses this access.

Part 1 · Sentinel
Admin App
System Users set access here. For example, Xena gives Sam a Membership.
Part 1 · Sentinel
Sentinel API
Sentinel keeps the access of each User. It checks this access at each request.
Part 2 · Back Office
Back Office
The Back Office asks Sentinel for the access of the User. It shows only those menus.

Part 1

Sentinel: how it works

System Users set access in the Admin App. The Sentinel API keeps this access and checks it.

1.1

Think of an office building

Each part of Sentinel is like a part of an office building.

The owner of the building
In Sentinel: Tenant · HDA
An Organisation that rents a floor
In Sentinel: Client · Farmers
The lease. It lists the rooms that the Organisation can use.
In Sentinel: Entitlement · Farmers can use the member rooms
A type of keycard, for example "Reception card"
In Sentinel: User Type · Display
The keycard of one person at one Organisation
In Sentinel: Membership · Sam has a Display card at Farmers
The office manager. The manager makes the keycard types, gives keycards to people and takes keycards back.
In Sentinel: client_admin · Xena at Farmers
A desk clerk. The clerk gives keycards to people, changes them and takes them back. The clerk cannot change a keycard type.
In Sentinel: client_manager · Ben at Farmers
One room
In Sentinel: Permission Node · member:lookup (look up members)
The guard at each door
In Sentinel: Sentinel · Sentinel checks Sam at each click
The security office. Staff make the keycards here.
In Sentinel: Admin App · This app

1.2

Who sets up access

Three people set up access, in this order. Each person can give only the access that they got.

Step 1
Jo · tenant_admin at HDA
Writes the lease
Jo adds Farmers as a Client. Jo sets the Entitlement of Farmers. Jo makes Xena the client_admin of Farmers.
Step 2
Xena · client_admin at Farmers
Makes the keycards
Xena makes the User Type "Display". Xena gives Sam a Membership with this User Type. Xena cannot give more than the Entitlement.
Ben · client_manager at Farmers
Gives out the keycards
A Client can also have a client_manager. For example, Ben is the client_manager of Farmers. Ben can give, change and end Memberships at Farmers. Ben can also send Invitations. But Ben cannot change the User Type "Display", and Ben does not see the User Types page.
Step 3
Sam · User at Farmers
Uses the keycard
Sam logs in to the Back Office and does the daily work. Sam cannot change access.

1.3

The one rule: both lists must have it

Two lists control what Sam can do. Sam can use an item only when both lists have it.

Farmers' list is the Entitlement of Farmers. HDA writes it. It is the maximum for all people at Farmers. In the building, it is the lease.

Sam's list is the User Type "Display". Xena writes it and gives it to Sam. In the building, it is the keycard.

Sam gets only the middle part, where the two circles meet.

Example: check each item

Item	Farmers' list	Sam's list	Can Sam use it?
Look up members	Yes	Yes	YesBoth lists have it.
Member notes	Yes	Yes	YesBoth lists have it.
Sales reports	Yes	No	NoXena did not put it in "Display".
Issue vouchers	No	Yes	NoHDA did not give it to Farmers.

Why two lists? HDA uses Farmers' list to set a limit for the full Client. Xena uses Sam's list to set a limit for one person. Thus, Xena can never give Sam more than HDA gave to Farmers.

Part 2

The Back Office: how it uses Sentinel

The Back Office does not keep access. It asks Sentinel for the access of the User. Then it shows only what the User can use.

2.1

What happens when Sam logs in

These steps occur each time. The code under each step shows the Sentinel call, for developers.

Step 1
Open the login page
Sam opens the login page of the Back Office for Farmers. The page gets its login settings from Sentinel: the Identity Provider that Farmers trusts. This is a Cognito user pool.
GET /auth/config?client=farmers
Step 2
Log in with Cognito
Sam types an email and a password. Cognito checks them, not Sentinel. Then Cognito gives the Back Office a token.
Cognito sign-in
Step 3
Select the Membership
The Back Office sends the token with each request. Sam can have more than one Membership. In that case, Sam selects one.
GET /me/memberships
Step 4
Get the access
The Back Office asks Sentinel what Sam can do. Sentinel sends only the Permission Nodes in the User Type and in the Entitlement.
GET /access/me
Step 5
Show the menus
The Back Office shows only the menus and buttons for these Permission Nodes.
Step 6
Check each request
Sentinel checks again at each request. If Sam does not have the Permission Node, Sentinel refuses the request.
403 Forbidden

Sentinel does not only hide menus. It also checks each request on the server. Thus, a hidden menu does not give a way around the rules. When a client_admin or a client_manager changes a Membership, the change starts at the next request. Nobody must install a new version of the Back Office.

2.2

Rules for the Back Office

Obey these rules when the Back Office uses Sentinel.

Ask Sentinel for the access of the User after each login.
Show only the menus and buttons for the Permission Nodes that Sentinel sends.
Let the User select a Membership when the User has more than one.
Show a clear message when Sentinel refuses a request.

Do not

Do not change access in the Back Office. Use the Admin App.
Do not keep a list of permissions in the Back Office code.
Do not give full access to a User who has no User Type.
Do not use hidden menus as the only protection. Sentinel checks each request.

Words you will hear

Use this list when you do not know a word.

Tenant: An Organisation that owns a set of Clients. Each Tenant keeps its data apart from the other Tenants. Example: HDA.
Client: An Organisation inside one Tenant. Its staff use the Back Office. Example: Farmers, Oporto.
Entitlement: The maximum access that a Tenant gives one Client. No User Type at that Client can go above it. Example: Farmers can use all member screens.
User Type: A named set of Permission Nodes for one Client. Example: Display, Super User.
Membership: A link that gives one User one User Type at one Client. It has a start date. It can also have an end date. Example: Sam is "Display" at Farmers.
Permission Node: One thing that a person can see or do. Its name has the form module:item. Example: member:lookup.
User: A person who works in the Back Office. Example: Sam.
System User: A person who works in the Admin App. Example: Jo, Xena, Ben.
tenant_admin: The User Type of a System User at the Tenant. This person adds Clients, sets their Entitlement and gives the admin roles at each Client. Example: Jo at HDA.
client_admin: The User Type of a System User at one Client. This person makes and changes User Types, and gives, changes and ends Memberships. This person cannot give an admin role. Example: Xena at Farmers.
client_manager: The User Type of a System User at one Client. This person gives, changes and ends Memberships. This person cannot change a User Type or give an admin role. Example: Ben at Farmers.
Client Name: The short name that a User types at the Back Office login. Example: farmers.
Identity Provider: The service that checks who a User is at login. Sentinel does not keep passwords. Example: The Cognito user pool of HDA.
Back Office: The app where Client staff do their daily work. It shows access. It does not change access. Example: Sam looks up a member.
Admin App: This app. System Users use it to change access. Example: Xena gives Sam a Membership.