Party-Based Authorisation

We shouldn’t assume that our customer modelling can be distilled down to persons/individuals and organisations. This may seem like an obvious place to start but hard-coding these two types leads to messy workarounds being developed later. To give some examples, these are some parties that may own or act on resources that I’ve seen in the real world.

• Persons – Individual users who interact with the solution.
• Organisation – Users will often work within and on behalf of a business.
• Organisation unit – Any non-trivial business will typically be made up of hierarchies that need to be understood and modelled.
• Third party vendor – Sometimes customers will make use of third party vendors (e.g. a SaaS provider) that make calls on their behalf.
• Franchise – Sometimes a business will have a relationship with another business where that other business can access some restricted view of their information (e.g. aggregated business reporting).
• Data aggregator – Sometimes a business will package up and sell aggregated data sets and market insights.
• Regulator – Some industries have government regulators that ensure businesses remain compliant with the relevant legislation. They may be given access to reports and other information that allows them to perform this role.
• Family – Retail solutions may wish to allow family members to pool resources and share benefits.
• Service – There will often be system actors in the solution that act on data not owned by them.

By using the concept of a Party, our entitlements solution can treat them all consistently. These Party types may own resources and/or they may act on resources. Crucially, they may act on resources owned by another Party. We can model what each Party is allowed to do on behalf of other Parties by introducing the concept of a Grant. Party and Grant provide an authorisation abstraction that can support complex permission relationships without knowledge of complex real-world types and hierarchies.

A Clean Boundary of Responsibility

We’ve talked about a few types up to this point. We now have:

• Identity – Information allowing an actor to be uniquely authenticated as well as coarse-grained permissions in the form of Scopes.
• Resource – A type of data exposed by the API of the system.
• Party – An abstract type that is the parent of all owners and actors (e.g. person and organisation). Using object oriented terminology, a person “is a” Party and an organisation “is a” Party.
• Grant – A definition of what operations a Party can perform on behalf of another Party.

Conceptually the following relationships are used to perform authorisation checks.

1. The actor is identified using Identity.
2. The Identity is associated with a Party that represents the actor.
3. Each actor has a set of Grants that define the set of owner Parties that the actor Party can act on behalf of.
4. The owner Parties own resources that can be operated on.

We can now describe a way to model this in a microservices environment with clean boundaries of responsibility. Let’s look at a typical architecture.

The components listed here are:

• User Client – This is the web or mobile application exposed to the end user.
• Identity – This is a system that implements the OAuth 2.0 and Open ID Connect specifications. It is used to authenticate the end user. It may be used to authenticate system actors. The initial sign-up process is also typically implemented or at least supported by the Identity solution.
• Gateway – An API gateway that routes incoming requests, validates access tokens, and performs coarse grained authorisation checks based on scopes. Many other features such as rate limiting, web application firewalls, observability, etc. are also required but not discussed here.
• Customer Service – Responsible for managing information about customers. This will typically expose self service features such as managing user profiles and organisation structures. In the real world it is rarely encapsulated into a single component but will be described as such for simplicity.
• Business Service – This represents the various business domain services that provide the functionality offered by the solution. There will be many of these.
• Entitlements – This encapsulates the common functionality for fine-grained authorisation that we want to expose to all business services. There is typically some synchronisation and/or consistency between fine-grained entitlements and coarse-grained scopes assigned to users.

Let’s now map responsibility for each of our types onto these components:

• Identity – This is managed by the Identity component. Identity records should strive to be minimal and not duplicate all customer data.
• Resource – All business entities are managed within the various business domain services. Each resource has an owning Party which can be of any customer type.
• Party – The Entitlements component manages all Party records. These are a projection of data mastered by the Customer component. We’ll touch on this more when we dig into data relationships. The key point is that we want to allow Customer modelling to evolve without impacting the authorisation-specific abstraction provided to business domains.
• Grant – The Entitlements component manages all Grant records. Similar to Party, these are a projection of relationships between customer types in the Customer component. Where a Customer understands the specific types of Parties and their unique relationships, a Grant is concerned only with what one Party can do on behalf of another Party. It has no knowledge of customer types or hierarchy, only permissions.

The division of responsibilities is clean. From a data perspective each component is responsible for:

• Identity – Identity record with credentials allowing a user to login.
• Customer Service – Customer records and their relationships. Very business specific.
• Entitlements – Abstracted Party records and Grants that capture what operations each Party can perform on behalf of another.
• Business Services – Business domain specific records and their relationship to a generic Party owner.

No knowledge of individual resources is visible to any IAM related components. No understanding of customer modelling is required by business components. There may be exceptions to this but from experience they can be dealt with on a case by case basis.

Real World Data Modelling

It can be difficult to understand the distinction between customer modelling and permission modelling so let’s describe a concrete example.

In this simplistic example we’re assuming that our customers can be modelled as follows:

• Person – An individual user who interacts with the solution.
• Organisation – Individuals work on behalf of organisations.
• Employee – Represents a relationship between a Person and an Organisation. Note that a Person may work for multiple Organisations.

Let’s now look at how these are projected into our Entitlements component.

• Each Person and Organisation maps into a Party record. We have introduced the concept of Source to record the origin of each record, this enables subsequent synchronisation to be performed in an incremental fashion.
• All records mastered in the Entitlements component such as Source and Scope have a “code” field which is a stable identifier that can be referred to in code. For example, a synchronisation job keeping Party records up to date with Person changes can discriminate by a Source type with code=person.
• Each Employee maps into a Grant record allowing that Person to act on behalf of their employing Organisation. Similar to Party, Grant is associated with a Source to assist with synchronisation. More complex modelling might involve different types of employees mapping to different types of Grant with varying privileges.
• We’ve introduced a Role entity. This allows a set of Scopes to be grouped together and allows a single Grant to represent many permissions. It also allows the set of Scopes associated with a type of Grant to be evolved over time without updating the individual Grant records themselves.
• The Role, Scope and Source entities are effectively configuration data and updated during deployments.
• The Party and Grant entities are projections however the id field is generated. This gives us a stable identifier format that is independent of the source system. Source systems are often legacy based and we don’t have control over the identifier they use. We maintain a mapping back to the original source system entity with a sourceId attribute.

Key callouts:

• Parties and their relationships are modelled in the Entitlements component. It is not necessary for business services to understand customer relationships. This allows new customer relationships and even party types to be introduced over time with much reduced likelihood of impact to services. In other words, we reduce coupling between business domains and customer modelling.
• Parties may have an associated Identity. Several types of Party will have identity (e.g. end user and system) but many others (e.g. organisation) will not. It’s possible (but not ideal) for a Party to have multiple forms of Identity which can be useful when migrating between identity platforms.
• The Entitlements component doesn’t have knowledge of individual resources. It may have implicit knowledge of resource types in its Scope definitions but these will often be grouped at a higher level for permission purposes (i.e. use OAuth 2.0 scopes modelling as a guide here).
• For this example, the scopes on the Identity record are assumed to be identical to the scopes assigned to the corresponding Person and would therefore be kept in sync when permissions are modified. More complex solutions may choose to create a mapping between the two and have coarser grained scopes.
• Because all business domains depend on the Entitlements component, it is critical to the availability of the solution. Paring it back to a minimal set of functionality allows it to be carefully tested and optimised. Additionally, more complex deployment models distributing the data and compute closer to business components can be explored.

A Party-based Authorisation API

We can now return to our Authorisation API and make changes that simplify the implementation. Because the Entitlements service doesn’t know about individual resources it cannot implement the Authorisation API as we described it earlier. Instead of accepting resource ID as an argument, the owning party of the resource must be supplied instead. So we now have:

• The actor – The party making the request.
• The operation – The action that is to be performed on the resource.
• The owner – The party who owns the resource.

The Entitlements component understands the relationships between an actor Party and an owning Party via Grants and Roles and can support this API. This change results in clean separation between the responsibilities of a business domain and an entitlements service. The business domain is responsible for modelling resource-to-owner relationships and the entitlement service is responsible for party-to-party relationships.

How business domains determine the owner of an individual resource is up to the implementation. An owner attribute may be modelled on individual resources or at any point in a resource hierarchy depending on what makes sense for that business context.

We now have a solution that can support all party types without knowing them all in advance, it is data driven. This requires far less plumbing than a fully centralised model because resource types (or more typically scopes) can be registered with the entitlements service in advance but resource IDs remain known only to each individual business service. Integration is limited to components managing parties and relationships such as user registration and onboarding. Authorisation related race conditions are avoided for all resource modifications because they are not visible outside the individual business domains. Race conditions are restricted to changes in the Customer component, use cases here are usually more tolerant of short delays.

This is a much simpler model to implement than fully centralised. So, what are we giving up? The main limitation is that every single resource must have a single owner. It is not possible to attach an ACL (access control list) to individual resources. Allowing multiple Parties to access a single resource is possible by using a Party type that has members (e.g. an organisation) and associated Grants between the owning Party and actor Parties. This works well when relationship types can be defined in advance. Less flexibility is provided to end users.

It does provide a good stepping stone to a more complex model if that is required down the track. Implementing a party based model from day one and properly modelling your various customer types helps avoid most of the tactical short cuts that make ongoing enhancements painful.

Conclusion

Implementing a centralised entitlements service that models party relationships and avoids knowledge of individual resources provides a solid foundation for solving complex authorisation requirements. It has some limitations but can provide a good tradeoff between the need to release features quickly to market and avoiding the need for major rework later. It allows customer modelling and security functionality to evolve independently of individual business domains.

In the next blog we’ll start exploring the implications of a fully centralised model and the Google Zanzibar whitepaper.