Token Exchange: An Open-Source Story

FollowingFollow

Software engineer addicted to solving complex challenges in the simplest ways. There's a 90% chance I'm wearing Nike in my feet every day.

Why does Open Source matter?

There are an infinite number of problems in the world of technology. Simultaneously, we also have an infinite number of solutions for those problems.

Giving our community access to Open Source allows them to contribute to projects that reflect problems others have faced and that we will most likely face in the future. The Open Source benefits clearly outweigh the downsides.

The three main pillars of the Open Source Program

The Open Source Program at FARFETCH was founded with three main pillars:

Do not try to reinvent the wheel.

This is the first pillar of the Open Source program: if you can, Open Source your wheel. Open Source projects offer the opportunity to invest time in new and unsolved problems, instead of focusing efforts on problems to which we already have the solutions.

Feedback from your peers will help you improve your project.

When you Open Source a project, that project will reach a much larger community than the one it reaches within an organisation, meaning we will gain access to more diverse feedback. As a result, our projects will be able to develop in a meaningful way when we open them to the community and receive feedback from peers.

Give back to the community.

Whilst we benefit from having a much larger audience improving our projects, our input also benefits the community as they will have access to the knowledge we’ve acquired from solving previous problems, saving everyone time and energy when they are faced with a similar situation.

The birth of the Token Exchange Framework

Since the initial release of the Open Source Program Initiative, the FFID Cluster was craving to be able to contribute to an Open Source project. The FFID Cluster is responsible for the FARFETCH Authorization Server, which is built on top of IdentityServer4 (an open-source OpenID Connect and OAuth 2.0 framework for ASP.NET Core). Since we were already taking our share from an Open Source Project, we also wanted to contribute to the community.

The opportunity to contribute arrived with the Token Exchange Framework. TokenExchange is a .NET Framework that implements the RFC 8693, OAuth 2.0 Token Exchange. This framework consists of a NuGet package designed to be installed and used together with an authentication server using Identity Server 4: it extends it and implements the RFC in a very simple way.

FARFETCH Platform has evolved over the years and is now a geo-distributed service-oriented architecture. In this type of architecture, we have multiple services communicating with each other, and this communication must be audited and authorised. One of the biggest challenges in a service-oriented architecture is preserving the information during the multiple hops that take place between the services in a single request.

Let's imagine you are a user and you enter an application: you start to login and then you access your addresses page. What usually happens behind the scenes is that the original token is propagated through the multiple applications needed to fulfil the address's request. The diagram below shows this token propagation.

The Poor Man’s delegation, as shown in this diagram, is the most used solution for this problem, where a token is passed subsequently between the multiple services. This is a very common strategy in service-oriented architectures. But it's not the best one, since the path that this token walkthrough from the application and the Address Service is not reflected between all of the hops the token does between the services.

This is where the Token Exchange RFC 8693 comes to the rescue. In simple terms, this RFC defines the protocol specification for Token Exchange - which is an extension of the OAuth 2.0 protocol - enabling clients to request and exchange tokens on behalf of another entity, preserving the information contained in the initial token.

Since our authorization server is built on top of IdentityServer4, we realised this was an excellent opportunity to contribute to the community with the Open Source Program initiative. From the beginning, we planned everything in a way that would enable us to Open Source our Token Exchange implementation.

The Token Exchange process: Diving into some crucial identity concepts

Identity claims

Each JWT Token, issued by the FARFETCH Authorization Server, contains information about the subject. This information identifies multiple aspects of the token owner and it is persisted as Identity Claims. These claims will give us information about the owner of the token.

In the context of Token Exchange, one of the most important things is that we must always know who is making a request and from which application.

The sub claim represents the identifier of the token owner to which that token was issued;
The client_id identifies the application to which that token was issued to.

Since these claims identify who and which client application is making a request, it is crucial that we preserve this information between all the hops a request does between services.

So, in a nutshell, the Token Exchange framework allows us to exchange tokens for new ones that preserve the information of the original token owner through claims. Therefore, avoiding the Poor man's delegation downsides, and increasing our view of the delegation chain that happens between the multiple hops one requests can do in a service-oriented architecture.

The Token Exchange Request Flow

Now, let’s dive into the Token Exchange Request flow to better understand how it works.

This flow starts when a User logs into an Application and goes to its addresses page and for that, it needs to be authenticated.
After being authenticated the Client Application that will operate on behalf of the User must call the API Gateway with the User’s token to get the User’s addresses.
When this request reaches the API Gateway, the Gateway must call the owner of the addresses, the Address Service. But before communicating with it, the Gateway will also have to authenticate itself and inform that it is operating on behalf of the User.
In order to maintain all the information preserved, the Gateway must take the token issued for the User and exchange it for a new one, issued on the behalf of the original Application.
The actual sender of the request is the Gateway so the API Gateway makes a token exchange request to the FARFETCH Authorization Server.

This Token Exchange request structure is the following:

POST /connect/token

grant_type=urn:ietf:params:oauth:grant-type:token-exchange

&client_id=<CLIENT_ID>

&client_secret=<CLIENT_SECRET>

&scope=scope1 scope2

&subject_token=<SUBJECT_TOKEN>

&subject_token_type=urn:ietf:params:oauth:token-type:access_token

&actor_token=<ACTOR_TOKEN>

&actor_token_type=urn:ietf:params:oauth:token-type:access_token

The act claim concept

Alongside the standard claims (as seen above) our newly exchanged token will have a new claim: the act claim. This claim is where all the Token Exchanges revolve around: it identifies that a delegation has occurred, and identifies the acting party to whom authority has been delegated. This claim looks like this:

{

"client_id": "web_app",

"sub": 12345,

...

"act": {

"client_id": "my_gateway"

}

The exchange token client_id and sub-claims identify the original User and Application, but also that a token exchange was performed by the API Gateway. As a result, we don’t lose any information between these request hops (like it would happen with other strategies such as the Poor man's delegation).

Now, our API Gateway has a token that can be safely used on behalf of the User and the original Application to get access to the User’s Addresses, maintaining a clear view of the delegation that happened along the way.

The following diagram, although very similar to the one shown above, contains all of the steps that must be taken in order to get access to an address with the Token Exchange strategy and how all the data is preserved through the journey -from the User to the internal boundary services.

As you might have noticed, these aren’t straightforward concepts and we must always ensure we manage our customers’ data in a sensitive and secure manner. . It is of the utmost importance that we ensure that, through all the paths the user data travels, we are aware of what's happening and are able to audit everything.

Giving back to the community.

The Token Exchange Framework implements the token exchange grant type defined in the RFC that strictly follows the RFC specification in order to be compliant with the OAUTH 2.0 protocol. Using it one would have all this dance between token exchange already implemented and ready to go with some simple configurations on its Authorization Server.

In the end, we were able to formally deliver this framework on FARFETCH GitHub, contributing to the community with a battle-tested solution for Token Exchange use cases that can be integrated with any Authorization Server that uses IdentityServer4. Don’t forget to also check the other awesome projects on FARFETCH GitHub!

Our Token Exchange Framework story started with a real-world problem that we didn’t have a solution for and the desire to give back to the community, particularly when we benefit from Open Source projects like IdentityServer4. Having this opportunity is huge and it’s extremely rewarding being able to contribute with Open Source projects that will have an impact on others, particularly on those that use IdentityServer and now have a plug-in solution for Token Exchange in their Authorization Servers.

One of the challenges that appear when working on a large scale with hundreds of applications communicating with each other is preserving the information and being able to have a clear view on what’s happening at any moment. The Token Exchange greatly assists with this as we can ensure that the chain of communication is preserved in all our gateways and we know the path our tokens take inside the platform.

If you find these kinds of topics interesting feel free to contribute to the project and challenge us to improve. We have open positions in our teams, if you are looking for new challenges and want to take the next step in your career, check them out at FARFETCH Careers. You can be the next one doing what's never been done.