The vast proliferation of APIs has enabled applications in the digital space to become increasingly interconnected. Automations and integrations allow us to create seamless workflows that operate across many products from multiple vendors. We use apps to automate actions on our behalf, such as scheduling our social media posts. We use integrations to share our data between multiple platforms, like when we check the status of our Jira tickets in Slack.
These examples all have a golden thread: security. How do we delegate authority by allowing apps to take actions or access our data on other platforms on our behalf without giving them access to our secret passwords? In this blog series, we provide answers to this burning question from both a non-technical and technical perspective. By the end of it, you will have a far greater understanding of OAuth 2.0 and why it is changing the face of the Internet.
OAuth 2.0 as an office analogy
OAuth 2.0 is the industry standard that most modern applications implement to allow you to delegate your access to an app to other apps, without disclosing your credentials. It is largely unrelated to OAuth 1.0a, which is often used when an app accesses another app without a user being involved to grant access.
In this blog, we’ll explain the fundamental concepts and actors of OAuth 2.0 with the help of an analogy based on the access control system in an office. There are several flavours of OAuth 2.0 that apply to different circumstances. We're describing the Authorisation Code Grant Flow, the most commonly variant (sometimes known as 3-Legged OAuth, or 3LO). In our next blog, we’ll provide a more technical overview, but we’ll follow the same structure as our analogy explanation so you can easily switch between the two. To set up the analogy, allow me to introduce Foo Corp, the company that sits at the heart of our analogy.
Foo Corporation’s HQ is currently located at Bar Tower, where they lease 16 floors of prime office space including a restaurant, open-plan offices, an R&D lab, a boardroom, and CEO Mrs Foo’s top-floor office. Foo Corp doesn’t own the office, but it does own all of the intellectual property and assets which are stored on the floors that they lease. Foo Corp employees have access to the office, where they carry out their daily work.
Access the old way – the fumbly code and keypad (before OAuth 2.0)
Back in the early days, when Foo Corp first took out the lease for the office in Bar Tower, security was pretty basic. There was a keypad next to the elevator in the lobby, and Foo employees would type in the secret code to gain access to Foo Corp. If the code was correct, the elevator would take them to any of the Foo Corp office floors in the tower. The code was like a front door key shared between all the employees. While this method worked, over time as the company grew, it became apparent that it had a number of drawbacks.
Firstly, it wasn’t very secure, because the code to access the offices was shared between all the employees. If an employee ever shared it with a third party, say a client who visited regularly, the code became uncontrolled. Who knows who else the client might share it with? The code could also be lost through negligence when employees wrote it down, or even stolen by malicious competitors of Foo Corp. Enter industrial espionage. Also, if the code was leaked and had to be reset, all employees would be inconvenienced by having to learn a new code.
Secondly, anyone with the code could access any of the floors of the office, from the restaurant to the secret R&D lab, regardless of their roles. Once in, they were really in and free to have a nose around at their leisure. This means Foo Corp had to trust employees to only access the parts of the office that were role specific. As always, in theory it would work, but in practice it was impossible to enforce. There was nothing stopping Paul, the receptionist, from popping into Mrs Foo’s lavish top floor office to get a coffee from her premium machine while she was abroad on business.
Lastly, there was no way for Foo Corp to track when the various floors had been accessed and by whom. The keypad system had a basic download that could show when correct and incorrect code entries had been made. But it couldn’t determine whether someone had been on the floor that houses Mrs Foo’s office when she was away, making Paul’s coffee pilfering completely undetectable.
For this reason, in time, as the company grew, Foo Corp decided to move to a more robust and secure system that would allow it to delegate access to individual floors of the office to employees according to their very specific needs.
The modern way – key cards (OAuth 2.0)
Foo Corp has moved up a rung and is now a thriving modern business, and as such they’ve updated their security policies. All Foo Corp employees now carry a key card that only grants them access to the floors that are relevant to their specific role.
When a new employee joins the company, they check in at the security desk in the lobby. On behalf of Foo Corp, the security team checks the new starter’s ID to confirm they are who they say they are, then sets up the employee’s key card. Key cards are coded to allow access to floors which individual employees need to visit in order to carry out their role, as determined by Foo Corp. The security team is the gatekeeper who sets up the key cards, but it’s Foo Corp that decides how it delegates access to the floors in the Bar Tower office to its employees.
Now when an employee taps their key card at the panel next to the elevator, they are offered a choice of the floors available based on their role, rather than all the floors. This means that the receptionist can no longer pop into Mrs Foo’s office while she is away, as that floor is not offered to him when he taps his card.
Employees in the same roles need access to the same floors. For example, all engineers need access to the R&D lab, the restaurant and the meeting suite. To save time, the security team has set up access groups for each of the various roles. They can use access groups to quickly grant employees access to groups of floors, rather than having to specify each available floor individually.
The key card system addresses all of the drawbacks of the key code system. If a key card is lost or stolen, it can be disabled remotely by the security team. Security is improved as employees can only access the floors they need, rather than the whole office. Access to floors is enforced by the system, rather than based on trust. And finally, the system enables a finer granularity of audit, as it records when individual floors were visited rather than just when someone came in and out of the office. If key card serial numbers are assigned to employees, Foo Corp can even determine who entered each floor - unless tailgating is involved, of course!
Relating the analogy to OAuth 2.0
Now that we understand how the different concepts and actors work together in the Foo Corp analogy, let’s take a look at how they map across to OAuth 2.0 and relate to a real world example.
You’ve just installed an app called Birthday Reminders, which uses your Facebook friends’ dates of birth to send you birthday reminders. You are the Resource Owner of your contacts stored in the Resource Server, which is Facebook. The app, which is the Client, asks you to grant it access to your Facebook contacts through the Facebook Authorisation Server, and you decide to give it access only to your contacts’ names and dates of birth (the Scope of the access).
This is how it all maps out:
|OAuth 2.0||Foo Corp Analogy||Birthday Reminders|
|Resource Owner||Foo Corp||You|
|Resource Server||Bar Tower|
|Client||Employees||Birthday Reminders App|
|Authorisation Server||Security Desk||Facebook Auth Server|
|Access Token||Key Card||Access Token|
|Scopes & APIs||Office Floors||Profile, Photos, Timeline|
The Foo Corp analogy was carefully crafted to accurately reflect the high-level fundamentals of the OAuth 2.0 concept. In reality, the finer details are more complex, but unless you are a developer looking to implement OAuth 2.0, this level of detail illustrates the main principles. In the next blog, we’ll revisit the concept from a technical perspective, and relate the actors from the analogy to their real-world articles.