In this example, I will use an imaginary employee expense reports app to illustrate how you can integrate with Authress from within your software. While your app may be different, you will surely recognize many of the patterns related to authorization here.
The app itself is simple - it enables employees of a company (think: your software users) to submit expense reports for reimbursement. You may have used similar tools yourself in the past. If not, imagine that as an employee you paid for office equipment out of your own pocket and now you want your money back.
Typically, it would go like this:
I’m using a microservice architecture, where the relevant service pieces are as follows:
Note that the Access Permissions block is simply a representation of my permissions model - this part will be handled by Authress.
Based on Getting started with Authress, I’m going to register my service clients. These are all the services that will interact with Authress, that is, ones that need an answer to the question “Can this user do this action?” in some form.
In case of my expense reports app, it will be the UI layer, Expense Report service, and the Approvals service:
This will allow my services to authenticate with Authress at runtime, keeping all our authorization data secure.
When designing my expense report app, I’ve determined that I need at least 3 different roles, that will represent my employee, employee manager, and finance department personas:
I’ll go ahead and define these in Authress UI, like so:
My app users will likely want to log in through a mechanism their company already established. It can be Microsoft Azure AD, Okta, or whatever SSO provider they have. Since I don’t want to deal with the complexity of integrating with all of these and I like the convenience of passing around only one type of token, I’m using an identity aggregator, in this example: Auth0.
Authress is able to resolve the user identity itself, so I’m going to make my life easier by connecting Auth0 in Management Portal.
Let’s take a look at the core flow in my expense reports app and see where Authress comes in.
To ensure that the user can access their own expense report and edit it later, I’m creating an access record with the user set to
Employee. In my app, this corresponds to actions like
You may wonder how the user gets the permission to create the expense reports in the first place. That part is covered in the next section: employee onboarding.
Let’s say the user leaves the app and later on proceeds to upload the receipts to their latest expense report. My UI will know to show the report to the user and enable the editing:
Now the report is complete, the user submits it, so that it can get the managers approval. I’m creating a new access record to capture it:
Now a manager logs in. They may have gotten an email notification, or perhaps they just do that once a week. They see a list of all the reports awaiting their approval. Here’s how my code looks like:
Upon clicking the respective button, the manager approves the user’s report. Here’s what happens behind the scenes:
A person from the finance department gets a report of all the expenses ready for reimbursement. My code responsible for generating the report includes:
Once the expenses are reimbursed, the related expense report is closed and archived. It can still be viewed by people involved, but can no longer be edited and doesn’t show up in the “awaiting approval” or “awaiting reimbursement” queues anywhere.
Notice that during this whole process, I didn’t have to worry about setting up a caching layer for user’s permissions, nor think too much about what happens if the current manager of an employee changes.
Before the core app flow outlined above is possible, I will have to add users (employees) into my app. When doing so, I need to make sure that the new user will have the right kind of permissions. Here’s how it’s done. Notice there are some permissions (like viewing expense reports or creating approvals) that aren’t assigned up front. They are instead handled through access records when a particular expense report is created - this ensures that the right people get access and no one accidentally ends up with more permissions than necessary.
It all looks good so far, but let’s think a bit about what happens when a new employee joins the company that’s using my app.
Someone who is already registered in the app will have to add that new employee, likely by clicking a button in my UI, and that will execute the above code snippet. But can anyone in the world do this? That depends on how I construct the
authressClient. Let’s take a look:
This means that whoever is currently logged into my UI needs to have the ability to assign permissions to other people. In Authress, having a permission to a resource is not the same as having the ability to grant that resource permissions. I will need to use
Delegate options. This means a few tweaks to my roles are needed - read on.
At this point I have to consider all my user personas once again. I have an employee, who can create expense reports, a manager, who can approve them, and a finance employee, who can create payouts and close the reports. In reality, one person may be all three.
When looking at new employee onboarding, I’ve discovered that whoever does the onboarding needs special permissions. It may be tempting to say that whoever is a manager, can also add new employees. This may be sufficient. But what if my users have an office assistant that deals with such things? Let’s add one more role, “Onboarding” to capture this:
Notice that our Onboarding role doesn’t have “Allow” on reports:create permission, only “Grant”. This means that whoever gets this role assigned will be able to grant this permission to other users, but won’t necessarily have the permission themselves.
With these basic cases, it should be easy for you to adapt similar patterns into your own app.
Didn't find what you were looking for?
Or send us an email at firstname.lastname@example.org