API 101: Restricting access with authorization
“You’re going to need special permission to do that”
Imagine the library in Hogwarts. There’s the normal section with all the books everyone can borrow and then there’s the restricted section, with all the juicy books about dark magic. As a normal Hogwarts student, you are free to borrow any books from the normal section, but you have to have special permission to borrow the books in the restricted section.
The same principle applies for APIs, except for maybe the dark magic part.
Since we know who you are because of authentication, we can now decide what you are allowed to do.
What data are you allowed to see, should you be able to make changes or even create new entries? This is what we use authorization to decide.
There are two main types of authorization (access control), role-based and attribute-based.
Role-based Access Control (RBAC)
Role-based access control is a coarse-grained type of authorization. It’s based on the permissions associated with the role a user has.
Like the Hogwarts library example from earlier, if your role is a student, you can read and borrow a certain type of book. But you cannot access the restricted section. Your role has to be a teacher or a special student to access those books.
This is coarse-grained because it puts the users in boxes — either you can access or you cannot based on the role you have been assigned.
That makes this type of authorization the simplest, it’s relatively easy to implement. If you use token-based authentication, you can add the role of a user in their token payload. So every time the user tries to use an endpoint, you can check that the role associated with the user has permission to use the endpoint.
get("/books?restricted=true") {
if(user.role == "TEACHER" || user.role == "SPECIAL_STUDENT") {
return restrictedBookRepository.find(requestBody.book.title) }
return 401 Unauthorized}
Attribute-based Access Control (ABAC)
Attribute-based access control is the fine-grained counterpart to role-based access control. If you need more control over who accesses what, this might be the way to go. Now we are no longer looking at permissions associated with roles, but permissions associated with attributes.
So coming back to the Hogwarts example, if you have certain attributes, such as being a Gryffindor student you are allowed to access the Gryffindor dorms. Which means we’re looking at attributes or a collection of attributes that allow you access to a resource. These attributes can come from user, application, system or environment attributes.
For example, you can only go to Hogsmeade every second Saturday, you have to be in year 2 or higher and you need permission from your guardian.
These types of permissions are called policies, which usually have the form IF/THEN/AND. So, IF it’s the second Saturday of the month AND you are a 2nd-year student or higher AND you have permission from your guardian THEN you can access Hogsmeade.
Unlike RBAC, attribute-based access control is based on requests at runtime or context-specific information. This means we need to do authentication deeper in the application since we might have to check if the user has the attributes required to access a resource. So it’s not as simple as adding a role to a token payload and checking that, we may have to query a database or an attribute checking service to see if the user has the right attributes.
Which is why attribute-based access control is much harder to implement.
General implementation tips
- Just like with authentication the KISS (keep it simple, stupid) principle still applies. No need to use ABAC if you can make do with RBAC.
- Figure out your requirements upfront. Spending a little extra time figuring out what the present and future requirements are can save you a lot of time down the road. Implementing RBAC and then finding out you need ABAC a few months later sucks.
- Use your endpoints to determine what kind of permissions your user has.
POST request → Can create resource
GET request → Can read resource
PATCH/PUT → Can update resource
DELETE → Can delete resource
That was it, for now, hope this shines some light on what authorization for APIs is about. If you want to read more, I’ve linked to some resources down below.
Thank you for reading and stay tuned for next time where we dive into pagination!
← Previous post: Solving identity issues with authentication
→ Next post: Lowering the load with pagination
Resources
What is Role-Based Access Control (RBAC)? Examples, Benefits, and More
