RSS

OAuth2 101: Introduction to OAuth2 Protocol

Introduction to OAuth2 Protocol

What is OAuth2

OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This specification and its extensions are being developed within the IETF OAuth Working Group.

OAuth2 standardize in RFC 6749 and RFC 6750 in 2012.

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849.

OAuth2 Grant Flows

To understand OAuth2 flow, first need know following roles in OAuth2:

  • resource owner

    An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.

  • resource server

    The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

  • client

    An application making protected resource requests on behalf of the resource owner and with its authorization. The term “client” does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).

  • user-agent

    Typically a web browser.

  • authorization server

    The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

OAuth2 use https and JSON to carry tokens.

Authorization Code Grant Flow (With User Interaction)

The code flow is defined in RFC 6749 section 4.1.

The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token.

After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.

OAuth2 Authorization Code Grant Flow Sequence Diagram

Implicit Grant Flow (With User Interaction)

The implicit grant flow is defined in RFC 6749 section 4.2.

The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript.

Compare to authorization code grant flow, implicit grant flow simplify token request step, authorization server return access_token to client directly.

OAuth2 Implicit Grant Flow Sequence Diagram

Resource Owner Password Credentials Grant Flow (Without User Interaction)

The resource owner password credentials grant flow is defined in RFC 6749 section 4.3.

The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application. The authorization server should take special care when enabling this grant type and only allow it when other flows are not viable.

Resource Owner Password Credential Grant Flow Sequence Diagram

Client Credential Grant Flow (Without User Interaction)

The client credential grant flow is defined in RFC 6749 section 4.4.

The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user.

This is typically used by clients to access resources about themselves rather than to access a user's resources.

OAuth2 Client Credential Flow Sequence Diagram

OAuth2 Refresh access_token

If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint.

grant_type is required and its value MUST be set to “refresh_token”.

refresh_token is also required.

OAuth2 Refreshing an Access Token Flow Sequence Flow

OAuth2 Use access_token to access protected resource

The OAuth access token is a bearer token. It define in RFC 6750.

Any party in possession of a bearer token (a “bearer”) can use it to get access to the associated resources. To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.

OAuth2 Use Bearer Token to Access Protected Resources Flow Sequence Diagram

Evolution History of OAuth & OAuth2

  • 2007 - OAuth started.
  • 2008 - IETF normalization started.
  • 2010 - RFC 5849 defines OAuth 1.0.
  • 2010 - WRAP (Web Resource Authorization Profiles) proposed by Microsoft, Yahoo! and Google.
  • 2010 - OAuth 2.0 work begins in IETF.
  • Working deployments of various drafts at Google, Microsoft, Facebook, Github, Twitter, Flickr, Dropbox…
  • Mid 2012 - Lead auth and editor resigned & withdraws his name from all specs.
  • October 2012 - RFC 6749, RFC 6750 defines OAuth 2.0.

OAuth 1.0 does not need https, it has build-in encryption. OAuth 2.0 try to simplify OAuth, editor didn't like it, resigned.

OAuth 1.0 more complicated and more secure compare to OAuth 2.0. OAuth 2.0 is more easy for client to integration. Security is trade-off.

OAuth 2.0 Security

There are complaints about OAuth2 security, an on-going IETF OAuth 2.0 Security Best Current Practice draft try to address this issue. OAuth 2.0 Security Best Current Practice describes security requirements and other recommendations for clients and servers implementing OAuth 2.0.

Recommendations

  • It is RECOMMENDED to use end-to-end TLS.
  • When comparing client redirect URIs against pre-registered URIs, authorization servers MUST utilize exact string matching.
  • Clients MUST prevent Cross-Site Request Forgery (CSRF).
  • In order to prevent mix-up attacks, clients MUST only process redirect responses of the authorization server they sent the respective request to and from the same user agent this authorization request was initiated with.
  • Clients MUST prevent injection (replay) of authorization codes into the authorization response by attackers. The use of PKCE [RFC7636] is RECOMMENDED to this end.
  • When using PKCE, clients SHOULD use PKCE code challenge methods that do not expose the PKCE verifier in the authorization request.
  • Authorization servers MUST provide a way to detect their support for PKCE.
  • clients SHOULD NOT use the implicit grant (response type “token”) or other response types issuing access tokens in the authorization response, unless access token injection in the authorization response is prevented and the aforementioned token leakage vectors are mitigated.
  • Clients SHOULD instead use the response type “code” (aka authorization code grant type) or any other response type that causes the authorization server to issue access tokens in the token response, such as the “code id_token” response type.
  • The privileges associated with an access token SHOULD be restricted to the minimum required for the particular application or use case.
  • The resource owner password credentials grant MUST NOT be used. This grant type insecurely exposes the credentials of the resource owner to the client.
  • Authorization servers SHOULD use client authentication if possible.
  • Authorization servers SHOULD NOT allow clients to influence their “client_id” or “sub” value or any other claim if that can cause confusion with a genuine resource owner

Bearer Token Usage Recommendations

Bearer token just plain text, we must take care of this token to avoid expose security risk in OAuth2 implementation. There are some recommendations:

  • Safeguard bearer tokens: Client implementations MUST ensure that bearer tokens are not leaked to unintended parties, as they will be able to use them to gain access to protected resources. This is the primary security consideration when using bearer tokens and underlies all the more specific recommendations that follow.
  • Always use TLS (https)
  • Validate TLS certificate chains.
  • Don't store bearer tokens in cookies.
  • Issue short-lived bearer tokens.
  • Issue scoped bearer tokens.
  • Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be passed in page URLs (for example, as query string parameters). Instead, bearer tokens SHOULD be passed in HTTP message headers or message bodies for which confidentiality measures are taken. Browsers, web servers, and other software may not adequately secure URLs in the browser history, web server logs, and other data structures. If bearer tokens are passed in page URLs, attackers might be able to steal them from the history data, logs, or other unsecured locations.

OAuth 2.1

There is a good reading about coming OAuth 2.1. A brief summary as below.

In fact, the “core” OAuth spec, RFC 6749, isn’t even called a specification, it’s technically a “framework” you can use to build specifications from. Part of the reason for this is because it leaves a lot of things optional, and requires that an implementer makes decisions about things like which grant types to support, whether or not refresh tokens are one-time use, and even whether access tokens should be Bearer tokens or use some sort of signed token mechanism.

This has often been quoted as the biggest failure of OAuth.

OAuth has been patched and extended a lot in the last decade of experience deploying systems using it.

The overarching goals of OAuth 2.1 are:

  • Give people a starting point which lays out a clear path for what they will need to read
  • Reduce the number of documents people have to read to understand OAuth and implement it securely
  • Get rid of the irrelevant content in old RFCs that has been deprecated, so that readers don’t get through an entire section only to discover a later RFC deprecated it
  • Labeling libraries or products as OAuth 2.1 is a lot simpler to understand than having to figure out whether it accurately implements OAuth 2.0 and all the desired extensions

References