Venidu Creations
Published in

Venidu Creations

Explore OAuth 2.0

OAuth 2.0 is an open standard for access delegation. This blog will focus on the importance and basic concepts of OAuth 2.0.

Before moving on to OAuth 2.0, you need to know the underlying basic concepts such as authentication, authorization and delegated authorization. For that, please refer the blog post in https://medium.com/@indunilRathnayake/authentication-authorization-ff8c681de8cc.

Pre OAuth Era :

In the pre OAuth era, users needed to provide their valuable credentials to third party applications, in order get their resources accessed from application level.

As in the above example, users need to give away their email address and password to the twitter application itself, in order to send twitter invitations to all his/her friends in the email contacts.

In this case :

  • The user has no control over the password storage in twitter end. Hence, twitter application will have complete access to the user’s email.
  • Applications can be compromised, in that case your credentials can be exposed to third parties.
  • Afterwards, requires user password reset to revoke the twitter application access to the email. But that will also impact for the other applications, which the user have already given the credentials.

OAuth 2.0

OAuth solves the problem of allowing third party entities( eg: applications) to access a resource owner’s protected resources without actually giving away the valuable credentials like passwords.

In OAuth 2.0, a user grants access to an application to perform actions on the user’s behalf and the application can only perform the authorized actions.

Let me explain how OAuth has solves this problem with a real world example.

Assume that a facebook gaming application requesting access to read your facebook friend list (i.e. Protected resource) from your (i.e. Resource owner) profile.

  • Pre-OAuth Era : Need to give your user name/password to the application, which would give unlimited access to do anything with your profile.
  • OAuth : From the application, you will be redirected to the facebook login page for authentication. Hence your credentials should be entered in the facebook end and will be not giving the password to the gaming app. After logging in successfully you would be prompted with a screen showing the details about the gaming app and the requested permissions by the app. This is to allow/deny authorizing the app from getting the requested permission on your account.

Roles

There are several key actors in the OAuth 2.0 protocol flows :

Resource server

  • The server hosting user-owned resources that are protected by OAuth.
  • Typically an API provider that holds and protects data such as photos, videos, calendars, or contacts.

Resource owner

  • The resource owner has the ability to grant access to their own data hosted on the resource server.
  • Typically the end-user of an application.

Client

  • An application making API requests to perform actions on protected resources on behalf of the resource owner and with its authorization.

Authorization server

  • The authorization server gets consent from the resource owner and issues access tokens to clients for accessing protected resources hosted by a resource server.

Client Profiles

OAuth 2.0 defines several important client profiles :

Server-side web application

  • An OAuth client running on a web server.
  • The web application is accessed by a resource owner (user) and the application makes the appropriate API calls using a server-side programming language.
  • The user has no access to the OAuth client secret or any access tokens issued by the authorization server.

Client-side application running in a web browser

  • An OAuth client running in a user’s web browser, where the user has access to the application code and/or API requests.
  • The application could be distributed as JavaScript included in a web page, as a browser extension, or using a plug-in technology such as Flash.
  • The OAuth credentials are not trusted to be kept confidential from the resource owner, so some API providers won’t issue client secrets for applications using this profile.

Native application

  • Software program that is developed for use on a particular platform or device.
  • An OAuth client which is very similar to the client-side application, as the credentials are not trusted to be kept confidential.
  • However, since it’s an installed application, it may not have access to the full capabilities of a web browser.

Authorization Flows

Each of the above client profiles needs to be accommodated with an appropriate protocol flow, to obtain authorization from the resource owner for accessing the data.

Therefore, the core OAuth 2.0 protocol defines four primary “grant types” used for obtaining authorization and also defines an extension mechanism for enabling additional grant types.

Before initiating the protocol, OAuth requires that applications register with the authorization server to obtain client credentials(Client ID and Client Secret), which are used to authenticate requests made to the authorization server.

The authorization process utilizes two authorization server endpoints (HTTP resources):

  • Authorization endpoint — used by the client to obtain authorization from the resource owner via user-agent redirection.
  • Token endpoint — used by the client to exchange an authorization grant for an access token, typically with client authentication.

As well as one client endpoint:

  • Redirection endpoint — used by the authorization server to return
    responses containing authorization credentials to the client via
    the resource owner user-agent.

Not every authorization grant type utilizes both endpoints. Extension grant types MAY define additional endpoints as needed.

Authorization Code Grant

  • Most appropriate for server-side web applications.
  • Application will be initially sending an authorize request as follows to the authorize endpoint of the authorization server.
GET https://server.example.com/authorize?response_type=code&client_id=nnKPyBOPfVQmlNXtBz3L2dbZHNQa&scope=openid&redirect_uri=https://localhost/callback&prompt=login&nonce=n-0S6_WzA2M&state=YWlzcDozMTQ2

Following are some of the parameters in the authorize request.

response_type — Determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Authorization Code Flow, this value is “code”.

client_id — OAuth 2.0 Client Identifier valid at the Authorization Server.

scope — Defines what the application needs to access in resource provider side. With scopes, can limit that the app can do in resource provider side, so there won’t be a full scale access.

redirect_uri — Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider.

state — Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

prompt — Specifies whether the Authorization Server prompts the End-User for reauthentication and consent.

Ex : “login” indicates that the Authorization Server SHOULD prompt the End-User for reauthentication.

nonce — String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.

  • After the resource owner has authorized access to their data, will redirected back to the web application with an authorization code as a query parameter in the URL. Authorization code is an indication that the user has approved the request.
https://localhost/callback?code=0bba8771-f254-34a6-99e1-4a01404a8ec0&state=YWlzcDozMTQ2&session_state=f5c68edda126acaf700d568fd8796e4e13b23992dbdf8658e1c2a53abd519b7d.-U6MJaFF1ZAx1InWHT4JKw
  • This code must be exchanged for an access token by the client application by invoking the token endpoint of the authorization server. So that, you can obtain an OAuth access token that your application can use to perform API requests on behalf of the user. This exchange is done server-to-server, preventing even the resource owner from obtaining the access token.
curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=f2d0f7dd-df6d-34ac-9d61-851f4f0cab9f&scope=openid&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<jwt_assertion>&redirect_uri=https%3A%2F%2Flocalhost%2Fcallback" https://server.example.com/token

Following are some of the parameters in the token request.

grant_type — “authorization_code” indicates that application wants to exchange code for an access token.

client_assertion — This is for application identification, so that authorization server, knows who is trading the code to token. There are several client authentication methods defined OAuth specification, in this example I have used private key JWT client authentication.

  • This grant type also allows for long-lived access to an API by using refresh tokens. So in the response to the token endpoint, you will receive an access token and a refresh token.
{ "access_token":"b5d57408-d468–3076-bdd7-ba20e11005f8","refresh_token":"5c1a8287–23bd-3cb6–9bb6-d6a6addb41de","scope":"openid","id_token":"<id_token>","token_type":"Bearer","expires_in":3584 }

refresh_token— Token that can be used to acquire new access token after expiration. Refresh token are long lived, hence must be properly stored as they provide an interesting target for attacks.

access_token — Access token never sent through the browser. User doesn’t know the token. Access tokens are very short lived.

Implicit grant

  • Optimized for browser-based client-side applications (unable to store client secret securely)
  • The resource owner grants access to the application, and a new access token is immediately minted and passed back to the application using a #hash fragment in the URL.

Request :

GET https://server.example.com/authorize?response_type=token&client_id= nnKPyBOPfVQmlNXtBz3L2dbZHNQa&scope=openid&redirect_uri=https://localhost/callback&state=123

Response :

https://localhost/callback#access_token=2a7377a3-b3aa-3206-80fc-96f12e1b051b&state=123&token_type=Bearer&expires_in=3599&session_state=686fcd8793c082021610829730a02a10c0579d4518b911ef3e6383432d8c56f6.sw6qe_vZufZiRPmbHkCc8w
  • The application can immediately extract the access token from the hash fragment (using JavaScript) and make API requests.
  • This grant type does not require the intermediary “authorization code,” but it also doesn’t make available refresh tokens for long-lived access.
  • User credentials never seen in the browser, it only has the access token.
  • Less accountability : there is no difference between the resource owner doing the call of a third party app. No clear separation between app and the browser (user).

Resource owner password-based grant

  • This grant type enables a resource owner’s username and password to be exchanged for an OAuth access token.

Request :

curl -k -X POST -H "Authorization:Basic <base64encoded(client_id:client_secret)>" -d "grant_type=password&scope=openid&username=admin&password=admin" https://server.example.com/token

Response :

{ "access_token":"c3374bd6-ffcb-3982-a602-4efbb838e706","refresh_token":"98047e46-7aae-363d-b1bc-1f69161452c6","scope":"openid","id_token":"<id_token>","token_type":"Bearer","expires_in":3600 }
  • It is used for only highly-trusted clients, such as a mobile application written by the API provider or legacy applications previously secured with basic auth.
  • While the user’s password is still exposed to the client, it does not need to be stored on the device. After the initial authentication, only the OAuth token needs to be stored. Access tokens are used to limit exposure of the password.
  • Because the password is not stored, the user can revoke access to the app without changing the password, and the token is scoped to a limited set of data, so this grant type still provides enhanced security over traditional username/password authentication.

Client credentials

  • Most of the OAuth flows are for handling delegated authorization, when a resource owner grants access to an application to access her data.
  • However, there are cases when the client itself owns the data and does not need delegated access from a resource owner, or delegated access has already been granted to the application outside of a typical OAuth flow.
  • Simply, when an application wants to access a resource on its own behalf, client-credentials grant can be used.

Request :

curl -k -X POST -H "Authorization: Basic <base64encoded(client_id:client_secret)>" -d "grant_type=client_credentials&scope=openid" https://server.example.com/token

Response :

{ "access_token":"8d11153b-7a4c-3ae3-a31a-e6eb62873070","token_type":"Bearer","expires_in":3600 }

Refresh Token Grant

  • The refresh token can be used when the current access token is expired or when a new access token is needed.
  • Issuing a refresh token is optional and if the authorization server issues a refresh token, it is included when issuing an access token.

Request :

curl -k -d "grant_type=refresh_token&refresh_token=<refresh_token>" -H "Authorization: Basic <base64encoded(client_id:client_secret)>" -H "Content-Type: application/x-www-form-urlencoded" https://server.example.com/token

Response :

{ "access_token":"2500e091-20bc-35e5-a870-df060c19b2cf","refresh_token":"837dc423-e0d2-3e60-be1c-2eae2145c9d1","scope":"openid","id_token":"<id_token>","token_type":"Bearer","expires_in":3600 }

Extension Grants

SAML2 Bearer Grant

Security Assertion Markup Language (SAML) is an XML-based markup language for security assertions (XML document that the identity provider sends to the service provider which contains the user authorization & authentication information, that service providers use to make access-control decisions).

Enterprise applications that have SAML2 based SSO infrastructures sometimes need to consume OAuth-protected resources through APIs. However, these apps prefer to use the existing trust relationship with the IDP, even if the OAuth authorization server is entirely different from the IDP.

SAML2 Bearer Grant is an OAuth extension grant type that uses a SAML 2.0 Bearer Assertion to request an OAuth 2.0 access token. This is used when a client wishes to utilize an existing trust relationship, expressed through the semantics of (and digital signature or keyed message digest calculated over) the SAML Assertion, without a direct user approval step at the authorization server.

Request :

curl -k -d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=<base64-URL_encoded_assertion>&scope=openid" -H "Authorization: Basic <base64encoded(client_id:client_secret)>" -H "Content-Type: application/x-www-form-urlencoded" https://server.example.com/token

Response :

{ "access_token":"e0b94fc8-faf5-34d4-b385-8602903422a8","refresh_token":"825e84c3-9504-3288-9c59-2880ed975b3b","scope":"openid","id_token":"<id_token>","token_type":"Bearer","expires_in":3600 }

JWT Bearer Grant

This is an extension grant type that uses a JWT Bearer Token to request an OAuth 2.0 access token, when a client wishes to utilize an existing trust relationship, expressed through the semantics of the JWT, without a direct user-approval step at the authorization server.

Request :

curl -i -X POST -u <clientid>:<clientsecret> -k -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<JWT>" -H "Content-Type: application/x-www-form-urlencoded" https://server.example.com/token

Response :

{ "access_token":"e0b94fc8-faf5-34d4-b385-8602903422a8","refresh_token":"825e84c3-9504-3288-9c59-2880ed975b3b","token_type":"Bearer","expires_in":3600 }

Comparison of Grant Types

I hope this article gives you a basic idea on how OAuth 2.0 works. Future articles will focus on more areas of OAuth 2.0, OpenID Connect and UMA.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Indunil Rathnayake

Indunil Rathnayake

Former Associate Technical Lead @ WSO2 | IT graduate @ University of Moratuwa