Series of articles: defence in depth part 1 of 7
Modelling identity
Almost all the systems we build today share data over public networks. That means they are accessible to anyone. We rarely want them to be, which is why we restrict access to them.
Often we also want to be able to distinguish between different types of users and give them access to different types of information. A user at one level should also not be able to access information at another level. We also need to protect our systems from targeted, external attacks.
This means that we need to build security into several parts and levels of the system. One of our key tools to achieve this is how we manage permissions. How and where we implement them affects both the security of our system, and how easy it is for us to adjust permissions afterwards.
Securing systems using only networking and other forms of scale protection is becoming less effective in a modern architecture. To build defence in depth with strong access control, the different parts of a distributed system need to independently verify identity and rights.
The system on the left is protected with IP-based security via a firewall product. All traffic inside the firewall is "Full Trust" and has access to the complete system.
In the system on the right, each service is protected in depth in several layers. Each service applies "Zero Trust" and does not rely on any incoming traffic. The system on the right has much stronger protection through identity-based security and is much more flexible for integrations and operations.
Many of the systems we design today are based on breaking down the domain into smaller, independent services. Integrations over public networks are increasingly a requirement and the system needs to ensure strong authentication of the user of the service.
A common view of identity in the form of a centralised Identity Provider (IdP) is a prerequisite for all services to be able to make correct authorisation decisions as the number of services grows. Identity is a central and common concept, the interpretation of what identity entitles belongs to each service.
To have a secure system that is flexible over time as it changes and expands, we need a model of what users, clients and resources are in the system. This gives us the tools we need to define what is central identity and what is local authority in our particular system.
This article will walk you through how to model identity and how to use OAuth2 and OpenID Connect to build a secure API. It gives us a couple of different concepts to work with:
Users
Clients
Services (resources)
Scopes
Audiences
Let's start by drawing a picture of all the user types, clients and services that make up the system. Here is an example:
Scopes are rights that we assign to clients and it's a matter of finding the right granularity for your system. This is where your domain model comes in handy.
Audience is a grouping of the APIs that make up our system. A good start is one (1) audience per API, but we can group however we want, e.g. a single audience representing all APIs.
Now it's time to do the actual modelling. One way is to draw arrows from user to client and from client to service. This way we can identify who is using what and what granularity our model needs to support. In our example, the following might be the right model.
| product.read | Provides read access to products |
| product.manage | Provides access to read, create, delete and manage products |
| order.read | Granting read access to orders |
| order.create | Provides access to read and create new orders |
The choice of audience and scope affects how much we can restrict a valid ticket in our system by API. For example, if in our example we have a single audience for all APIs, there is no way to restrict a ticket with scope order.read to only static APIs. Audience in combination with scope should give you the granularity you need.
An Identity Provider (IdP) can allow the user to combine scopes with audience at login. It looks a bit different in different IdP products, but in principle the user gives his client the right to use a selection of scopes for a selection of audiences. For example, in our case, an administrator may give a client the right to manage products for the product API, but nothing else, which is often called User Consent.
Finally, we have the permission model, what a user is entitled to. Each API gets information about which scopes and audiences the user has authorized, her identity, and details about the login event. In the next article, we will discuss how to use this information to build a strong permission control.
Permission control for what Eva Svensson is allowed to do is implemented in each API. In article 3 we will go in depth on what you need to consider.
Joel Harsten
I often see that people forget about the access control itself. You need to be careful to restrict access to the resource so that it is not only based on a valid ticket, but also based on your rights in the system.
A documented, well thought-out identity model is the foundation of a good authorisation model and a secure system. In our experience, it can be a challenge to find a model that balances central versus local, is not too simple, not too large, and can be adapted for future needs. A well-thought-out domain model is a very good start for this work.
Tobias Ahnoff
Be careful about reusing your clients. According to the principle of "Least Privilege", each client should have minimal access to perform its tasks. If you reuse clients, you run the risk of having to give it more authority than necessary, you can make it difficult to track systems, and you run the risk of dependencies that make it difficult to rotate credentials.
A good starting point might be to never reuse clients between different bounded contexts.
As always, you need to find a balance between many clients to manage and few clients with high permissions and reduced traceability.
Read the other parts of the article series