An introduction to OAuth2 and OpenID Connect intended for a technical audience. This covers terminology, core concepts, and all the core grants/flows for OAuth2 and OpenID Connect
2. Straight to the point: OAuth
• OAuth is an IETF standard for allowing an application to obtain access to
an HTTP service on behalf of an end user(without a user sharing their
password!), or on its own behalf.
• OAuth is not just using signed JWTs for authentication, though a lot of
OAuth implementations use signed JWTs.
• OAuth does not Authenticate end-users (humans like us!) to
applications
• Everyone who is sane in the industry refers to “OAuth2” when saying
OAuth. OAuth1 is officially deprecated
• OpenID Connect (OIDC) is an authentication layer for end-
users(Humans!) built on top of OAuth
3. OAuth 2.0 Terminology
• Client: The application that is calling an API
• Resource Server: the API that is being called
• Access Token: The credential used by a client to interact with the resource server.
• Authorization Server: The server that issues access tokens. Can also be called to
validate access tokens
• Resource Owner: the person or application that an access token represents. Can
be called “end-user” if this is a human
• Authorization Code: A one time use token an end-user receives from an
authorization server and gives to an OAuth client
• Grant: Mode of Operation. OAuth has 4 core “grants”, that define the use case and
how all the different components interact
4. OAuth Core Concepts
• Access Tokens are signed JWTs or long strings (opaque tokens)
• JWTs can be validated without phoning home to the authorization server. This means that a bad
setup might issue tokens that are difficult/impossible to revoke without disrupting users!(rotating
signing keys!)
• A resource server receiving an Opaque token would have to phone home to the issuing
Authorization Server to see if it’s still valid
• The content of access tokens is defined as a standard (RFC7662)
• OAuth is “delegation” and is a stand-in for the old pattern of users sharing or syncing passwords
between services. We’d call credential sharing “impersonation”, and that is risky for users.
• End-Users must be authenticated to the OAuth Client and Authorization server to finish “OAuthing”
• Authorization servers should always prompt for consent before granting an OAuth token for humans,
and inform them of what permissions they’re granting the OAuth client
• Authorization servers keep a registry of a redirect URI specific for each client
• In all diagrams following we assume the user is already authenticated to the OAuth Client and
Authorization server
5. Client Credentials Grant
• Client Credentials grant: A system authenticates itself to the authorization
server with its own credential, and receives back an access token scoped
to its own identity.
• Think an application that queries information from a remote API for its
own usage.
OAuth Client
Authorization
Server
Resource
Server
OAuth Client’s Credentials
Access Token
Access Token, API call
Results of API call
6. Authorization Code Grant
• A remote system(running on a server) gains consent from a user to take an action on their behalf:
• Think entitling an inbox management software to read your gmail and unsubscribe you from
spam
• Authorization code grant clients can be given a refresh token that they can use to renew a user’s
access token without re-interacting with the user! (Best practice: refresh tokens must expire if not
redeemed within a suitable time window)
OAuth Client
Authorization
Server
Resource
Server
(1)Redirect to Authorization Server
(4) Authorization Code
(7)Access Token, API call
(8)Results of API call
End-User’s
User Agent
(5)Authorization Code+Client Credential
(6)Access Token, Optional Refresh Token
**(2)Request Authorization code (3) Return Authorization Code
(2) (3)
7. Implicit Grant
• An app running locally on a user’s device gains user consent to take an action on their behalf
• Think apps on a smart phone accessing your Instagram, modern applications on your desktop
connecting to back end services (Office 365), single page web apps accessing APIs
• Implicit clients have no secret for which to authenticate themselves - we are forced to trust the
user’s device’s registered URI scheme and/or DNS resolutions
OAuth Client
Authorization
Server
Resource
Server
(1)Redirect to Authorization Server
(4) Access Token
(5)Access Token, API call
(6)Results of API call
End-User’s
User Agent
**(2)Request Access Token (3) Return Access Token
(2) (3)
8. Resource Owner Password Grant
• A user gives their password to a client, and the client requests an Access token on their behalf.
• Sharing passwords is fundamentally not secure, and Resource Owner Password Grant
should be avoided at all costs. If you simply must use this, have the OAuth client discard the
user’s password immediately after the Access/Refresh token is received.
• Can also get a refresh token, like authorization code grant
OAuth Client
Authorization
Server
Resource
Server
(1)Resource Owner’s Password
(2) Access Token, Optional refresh token
(5)Access Token, API call
(6)Results of API call
9. OpenID Connect
• OpenID Connect is a simple identity and authentication layer built on top of
OAuth2 implicit and authorization code grants
• Works essentially the exact same as implicit and authorization code grant,
but the client also gets an “id_token” with the user’s identity attributes
(Name, email, address, date of birth, etc)
• It allows an end-user who is authenticated with one application (The OpenID
Provider) to authenticate to a second application using the first application’s
identity
• Think signing into a mobile or web app with your Google, Facebook or
GitHub account.
• Allows you to seamlessly integrate delegations and authentication together,
simplifying the developer and user experience!
10. OpenID Connect
Terminology
• End-User: The Resource owner. By Definition, must be
human
• Relying Party: The OAuth Client to which an end-user is
authenticating
• OpenID Provider: The Authorization Server, in OpenID terms.
Issues ID_Tokens
• ID_Token: The token that an End-user gets from their
OpenID Provider to authenticate themselves to a relying party
• Flow: OpenID term for “Grant”
11. OpenID Connect Core
Concepts
• Trusting an OpenID Provider means you may allow your user’s account to be taken over
by an attacker if their account at the OpenID Provider gets taken over!
• Best practices would be to notify a user if there is a login from a new OpenID provider,
and perform the same monitoring you would for normal logins on OpenID logins, or
challenge them for a 2nd factor of authentication on a sensitive operation
• You do not need to let a client take action on an End-User’s behalf or even issue them a
valid access token at all in OpenID Connect. You can keep it to “authentication” and
remove the delegation
• OpenID providers should ask for consent before allowing a user to authenticate to a
website, and inform a user of what data they are sharing
• OpenID connect is for Humans only
• In all diagrams following we assume the user is already authenticated to the OpenID
provider
12. Authorization Code Flow
• A user wants to sign in to a third party web application
(e.g. Strava) that also wants to access additional
information in their OpenID provider’s platform (e.g.
Google)
OAuth Client
Authorization
Server
Resource
Server
(1)Redirect to OpenID Provider
(4) Authorization Code
(7)Access Token, API call
(8)Results of API call
End-User’s
User Agent
(5)Authorization Code+Client Credential
(6)ID_token, Optional Access Token, Optional Refresh Token
**(2)Request Authorization code (3) Return Authorization Code
(2) (3)
13. Implicit Flow
• An app running locally on a user’s device gains user consent to take an action on their behalf
• Think apps on a smart phone accessing your Instagram, modern applications on your
desktop connecting to back end services(office 365), single page web apps accessing APIs
• Steps 5 and 6 only happen if an access token was granted
OAuth Client
Authorization
Server
Resource
Server
(1)Redirect to OpenID Provider
(4) ID_Token, Optional Access Token
(5)Access Token, API call*
(6)Results of API call*
End-User’s
User Agent
**(2)Request Access Token (3) Return Access Token
(2) (3)
14. Hybrid Flow
• A user wants to sign in to a third party web application (e.g. Strava) that also wants
to access additional information in their OpenID provider’s platform (e.g. Google)
• User Authentication comes before delegation, speeds up the user experience. Has
the URI scheme/DNS security implication of implicit grant for the user’s information
OAuth Client
Authorization
Server
Resource
Server
(1)Redirect to OpenID Provider
(4) Authorization Code, ID_Token
(7)Access Token, API call
(8)Results of API call
End-User’s
User Agent
(5)Authorization Code+Client Credential
(6)Access Token, Optional Refresh Token
**(2)Request Authorization code, ID_token (3) Return Authorization Code, ID_Token
(2) (3)
15. References
OAuth RFC core RFC: https://tools.ietf.org/html/rfc6749
Access token introspection: https://tools.ietf.org/html/rfc7662
Signed JWT tokens RFC: https://tools.ietf.org/html/rfc7515
Open ID Connect Core: https://openid.net/specs/openid-connect-core-1_0.html
Intro to JWTs: https://jwt.io/introduction/
Draft OAuth Device grant (emerging standard): https://tools.ietf.org/html/draft-ietf-
oauth-device-flow-15
JWT as client secret: https://tools.ietf.org/html/rfc7523
XML as client secret: https://tools.ietf.org/html/rfc7522
