4 Key OAuth2 Terms You Need To Know
In this video we get started with actually installing the FOS OAuth Server Bundle inside our Symfony2 project. Yes, amazingly that was not the first step we took.
We don't deviate to far from the official installation guide, so if you're comfortable with Symfony2 bundles, where config goes, creating Entities and passing those changes through to your database then by all means, feel free to skip over this episode.
I have talked fairly frequently about User Providers so far in this series, and that's largely because without some end-users (or Resource Owners) to authorise against, we are missing a core piece of the OAuth puzzle. A User Provider is a way of providing Symfony with a list of one or more Symfony compatible Users. To make that as real-world as possible, we are integrating with FOS User Bundle.
Much like we did in the previous video, we are going to put the code that is relevant to our OAuth Server inside its own bundle - the CodeReviewOAuthServerBundle. What a mouthful. We did the same with the FOSUserBundle code (into CodeReviewUserBundle) in a bid to keep things as understandable and separated as possible. Again, FOSUserBundle is not a pre-req for FOSOAuthServerBundle.
You're Listening to RFC6749, Radio OAuth2
There are a few unusual terms you will have to use and understand if you want to implement OAuth2.
All of these terms are explained in RFC6749 - The OAuth 2.0 Authorization Framework.
Now, if I'm being brutally honest, the thought of sitting down and reading 76 pages on the minutiae of OAuth2 is not my idea of fun.
But the thing is - reading this RFC is pretty darned important.
If you are serious about implementing OAuth2, it will become a core part of your security infrastructure and you need to understand the implications and potential problems that adding OAuth2 will entail.
At the very least, please read the Security Considerations chapter.
Key OAuth Terminology
Before we get too far into the installation, we are tasked with configuring four new entities:
Client(OAuth2 consumers)AccessTokenRefreshTokenAuthCode
The instructions don't give much away in regards to what these four classes are for, and why we need to set them up, so lets look in a little more detail at each.
Client
This was the one that caused me the most confusion initially.
A Client is an application which accesses secured resources on behalf of Resource Owners (read: Users, but could be other things as well).
You might have a Client for mobile devices, a Client for your secured desktop devices, but you could also have one Client per User.
This was the confusing part for me. There aren't hard and fast rules here, it's what best meets your requirements.
Typically however, I would say that it is more common to have a single Client for mobile devices which would be used by many Users, rather than create an individual mobile Client per user.
Access Token
An Access Token is a long string that on the face of things looks like random nonsense - a varying length of characters consisting of upper and lower case letters and numbers ranging from 0 to 9.
To FOS OAuth Server this Access Token represents the information required to decipher who this token belongs to and what they can and cannot do when using it.
Using an Access Token replaces the requirement for providing your username and password with every request.
Access Tokens also enable you to be more restrictive over what resources are and are not available, regardless of what the same User may be able to do when logging in to the system in a more traditional fashion. This is done by way of Scopes.
An Access Token has a defined lifetime, after which it expires and is no longer valid.
To continue accessing the system, another Access Token is required - this can either be requested using the same workflow that was used to provide the now expired Access Token, or a Refresh Token can be used.
Refresh Token
You use a Refresh Token to obtain another Access Token.
Refresh Tokens are literally credentials used to obtain Access Tokens.
Of course, thanks to nefarious evil-types, Refresh Tokens are obfuscated in a manner very similar to Access Tokens. Because, well, life is not designed to be that easy, right? ;)
Not every OAuth Server will issue Clients with a Refresh Token. And indeed, your OAuth Server implementation may choose not too. It's your call.
If a Refresh Token is provided, it is provided at the same time as the Access Token. That is, you don't need to ask the server for a Refresh Token, it will be given to you at the same time you get your Access Token. If its giving you one. Which it might not.
AuthCode
An Authorisation Code.
This is a "middle man" received by the Client, which the Client can then continue on and exchange for an Access Token.
Depending on how you're Authorising, you may not actually need to implement this in your FOS OAuth Server set up.
If you have ever seen an website or web service allow you to sign in with your Google, Facebook, Github, etc, login details, then you will have used this, even if you didn't realise it.
The AuthCode will be part of the URI that the Authorising (whether it be Google, Facebook, or our OAuth2 implementation) Server will create to redirect our end-users as part of their app, or desktop, or whatever's login flow.
TL;DR;
I hope not. Tut tut.
No, seriously, the take away points here are the bits and pieces of terminology, and the fact that to get our FOSOAuthServer Bundle installed and configured is largely copy and paste at this point.
But you need to know and understand what you are copying and pasting.
Because - if my experience is anything to go by - you will make mistakes, you will get weird errors, or worse, nothing at all will happen when something pretty important definitely should. You think. Or do you? Never mind, that little bug will only prey on your mind relentlessly until you get a eureka moment two days later just as you're falling asleep.
So read the RFC.
Yes, it's long and difficult to get through. It's not supposed to be Harry Potter.
But if you don't read it, this stuff will just look like magic.
