The OAuth2 Apartment Building

Understand core OAuth2 concepts by analogy and learn how the various ForgeRock Identity Platform components relate to OAuth2.

I live in a modern apartment building. It’s a very nice place – pet friendly, upscale furnishings, prime location. One of the best parts about my apartment building, though, is that it has electronic locks available for all the doors. This is pretty similar to most new hotels; each door opens only by using a key card that was issued by the front-desk. The thing that sets it apart from hotels is that it isn’t just the main apartment door that is opened by a key card – each of the inside doors is too. Every internal door in the entire building will only open for you if your key card is authorized for it.

Surprising thing to consider the best feature, right? You might think having doors like this is actually inconvenient and unnecessary – what value is there to having such a locked-down home? What is wrong with just using a plain-old key to open the front door? Let me explain some of the advantages that this door setup offers.

The other day I was walking through the lobby and I noticed that there was an item on the community bulletin board – an advertisement for “Clint’s Dog-Walking Service”. For a small fee, this company offered to make regular stops up to my apartment to pick up my dog (Fido) and take him for walks, whether I’m at home or not. I felt bad for leaving my pooch at home all day while I was at work, so this sounded like a great deal! I called them up for a trial.

This was a small company, and so they sent Clint himself to meet me in the lobby. I filled out the paperwork for my initial trial and then we walked up to the front-desk for Clint to get his key card to my place. The attendant working the desk was named Amy. The first thing Amy needed to see from me was my driver’s license – she wanted to make sure I really was a tenant in the building and also find out which apartment was mine. Next, as is building policy for all key cards issued to non-tenants, Amy asked Clint for his company information along with which doors of mine he would like to be able to open – it’s important that these details are on file with building management, for liability purposes.

Once she was able to verify that Clint’s company was properly registered, she had me look over a form listing the doors that Clint was asking permission to access. For his dog-walking service, he only needed to open my front door and the “dog room” (like I said, this is a very pet-friendly apartment building). I certainly didn’t want him to be able to open my bedroom or office door – he has no business in there, especially when I’m not at home! Fortunately he was only asking for the doors he needed, so I signed Amy’s form. She filed this away for record-keeping and then produced a brand-new key card, which she then handed over to Clint. This key card was only good for a month; this is another building policy designed to reduce the risk of it getting lost or stolen.

Clint then started his regular service walking my dog. Every time he opened one of my doors, the software managing the door logged his entries. I had peace of mind knowing that he could enter my apartment but only to the areas I had approved. I was very happy with the convenience of the whole thing and confident that my privacy was secure.

After the first month, his card expired and so he stopped by the front-desk for a new one. Amy checked to make sure that he was still allowed access; since I was apparently happy with the service at this point (as far as Amy could tell), there was no reason to refuse his request for a new card. Service continued uninterrupted.

Sadly, I eventually decided that Clint’s service wasn’t really worth the money he was asking. In addition, I was working from home more so I didn’t leave my dog alone as often. I contacted Clint and told him I wanted to cancel my account. I also called up Amy at the front-desk and told her that I would like to deactivate Clint’s current key card, and also prevent him from getting any more cards in the future.

This is why my apartment building really is awesome – if I had an old-school physical key and lock on my door, I would have had to make a copy of my key for Clint. In that case, I would have had no idea when he came and left, which rooms he went into, or if he made any other copies of that key for anyone else. When the time came for me to cancel his service, I would have had to take his word for it that he hadn’t made any additional copies of my key when I asked for it back. To have complete peace of mind that he couldn’t come back in without my approval I would have had to change the locks on my door (and if I had changed the locks, anyone else that I had given a key would need to get a new one). These are major problems! I would have never accepted that much hassle and risk if I had been using an old door lock. As it turns out, Clint’s business was really only possible in an environment where I can control these factors.

This is not really my apartment building, it’s OAuth2. This analogy explains exactly why OAuth2 was created and covers the basic way it works.

Before OAuth2, when you needed to give software services access to your account to do things on your behalf you had to give that service your username and password. This is exactly like the physical door key – there is no way to tell whether the agent accessing your data is a third party doing so on your behalf rather than you doing it yourself. As with the physical key, they would have complete access to everything in your account (similar to how a person with a single physical key to the main apartment door would have access to everything inside). If you want to cancel your service, you would need to change your password to be sure they wouldn’t be able to use it again without your permission.

OAuth2 solves this in the same way that my fictitious apartment building solves the physical key problem.

The apartment you wish to visit is an OAuth2 “resource“. Every apartment has an owner; in OAuth2, every resource has a “resource owner” that is authorized to grant access to it. These are the users in your systems; their data are the resources. ForgeRock Identity Management defines an API for operating on user data that may be exposed in this context.

Just how my apartment building replaced physical keys with electronic key cards, in OAuth2 usernames and passwords have been replaced with “access tokens“.

Similar to opening an apartment door with a key card, you request resources using an access token. Likewise, in the way that you would expect a key card to only be able to open certain doors, access tokens are only usable for specific things. In OAuth2, the particular things an access token is capable of being used for are called “scopes“. In my analogy, the doors within my apartment are all coded to require a specific scope (such as “main door”, “dog room”, “bedroom”, “office”, etc…). Any access token presented to one of them which does not have the required scope will fail to open it.

Clint is an example of an OAuth2 “client“. A client is any entity which has been given an access token. Clients vary based on their relationship to the other parties and the ways in which they are able to get an access token. Regardless of these details, all clients essentially behave the same after they have a token – they use it to request protected resources. Clients are the software applications that you bring into your systems to provide benefits to your users. For software without native OAuth2 client capabilites, ForgeRock Identity Gateway offers an easy way to operate as an OAuth2 client.

The building front-desk and associated door tracking software is the OAuth2 “authorization server” (or AS). It is chiefly responsible for issuing access tokens to clients. For that to be possible, some of the same steps that were taken in my story are also required in OAuth2. For example, by presenting my driver’s license I was able to “authenticate” to the front-desk; OAuth2 authorization servers also require an authentication step (usually a username and password prompt but often other prompts too). After Amy at the front-desk checked my ID, she then looked up the details for Clint’s company. This is part of OAuth2 as well – the client needs to be registered with the AS before any tokens are issued to it. The client is responsible for telling the AS which scopes it would like, similar to the way Clint told Amy which doors he wanted to be able to open. The AS shows the resource owner a list of those scopes, as a means of obtaining informed consent regarding what the client will be able to do with their token. If the resource owner approves, then the AS returns the access token to the client. ForgeRock Access Management implements the role of the authorization server.

Every time the client uses its token to request a protected resource, there is a check made by the software protecting the resource (in OAuth2 terms, this software is called a “resource server“) to verify that the token is legitimate, not expired, and has the necessary scopes for the request. This is called “token introspection“. Usually, token introspection involves a call to the AS that issued the token. In the same way that the door checks with the building management software when a key card is presented, this is something that happens without the client’s involvement. The client only sees if the request is granted; the door either opens or it doesn’t. ForgeRock Identity Gateway offers an easy solution to act as a resource server, with several means of token introspection available to choose from.

Access tokens expire in the same way that the key cards were described. Depending on the agreement made between the client, the resource owner, and the AS there may be a way for the client to obtain new access tokens without having to ask the resource owner every time it expires. This is just like the way Clint was able to get a new key card from Amy after his first expired. In OAuth2, this process involves the “refresh token“. The refresh token is only usable to get new access tokens; it’s not usable directly to access protected resources. The point of this token is to try to limit the risk of lost or stolen access tokens. Both refresh tokens and access tokens can be revoked by the resource owner on the AS, in the same way that I described calling Amy when I wanted to cancel my service with Clint. Revoked access tokens will be detected during token introspection, which will prevent their continued use.

OAuth2 enables new businesses and practices to thrive in a trusted environment where it would be impossible otherwise. By establishing this consent relationship between the clients and the resource owners, people have the tools necessary to maintain their privacy and security to the degree they demand. The ForgeRock Identity Platform is the best means to offer that relationship – go forth and build your own OAuth2 apartment building!

Special thanks to Aaron Parecki for the basic “access token as hotel key card” analogy, which I heard him mention in a user group presentation similar to the one he gives here: Using OAuth2 and OpenID Connect in your Applications.

Update: Read the follow-up which describes how the OAuth2 Apartment Building relates to the OpenID Connect Neighborhood

1 Comment
  1. alexander.dracka 1 week ago

    Very nice, at first I was like “damm, what a fancy apartment” :)

Leave a reply

©2018 ForgeRock - we provide an identity and access platform to secure every online relationship for the enterprise market, educational sector and even entire countries. Click to view our privacy policy and terms of use.

Log in with your credentials

Forgot your details?