HTTPS SSH

Bitbucket Cloud Authorization Code Grant Sample App

Introduction

This app aims to demonstrate the Authorization Code Grant Type Authorization flow, what is needed to generate an access_token and how to use that to invoke Bitbucket REST APIs, and lastly a reference app where the developer can copy paste the code and try it in their own projects

What is Authorization Code Grant?

This is the most common auth grant. You see this everyday when you log in to Facebook or Google. The difference of this auth grant is it is user initiated via the user-agent/browser. The authorization code is obtained by using an authorization server as an intermediary between the client and resource owner. Instead of requesting authorization directly from the resource owner, the client directs the resource owner to an authorization server (via its user- agent as defined in which in turn directs the resource owner back to the client with the authorization code. Before directing the resource owner back to the client with the authorization code, the authorization server authenticates the resource owner and obtains authorization. Because the resource owner only authenticates with the authorization server, the resource owner's credentials are never shared with the client.

Difference with other grants

  • Security Benefit
  • User initiated grant through user-agent/browser
  • Resource Owner credentials are never shared because resource owner interacts with the Authorization server and not the client
  • Provides security benefit by authenticating client and returning the access token to the client directly without passing to the resource owner's user-agent (browser)

Authorization Flow Chart

Alt text

Things to consider

What is OAuth?

OAuth is a mechanism for authorizing an entity and granting them access over which the user is capable of doing in an application

What it is not?

OAuth is not a way to authenticate but rather to authorize an entity for access

Definition of terms

Term Description
Basic Auth Is an authentication mechanism. Is straightforward but unsecure. It is the combination of your username and password that you would use to access an API endpoint.
client_id Key generated from Bitbucket Settings → Add Consumer
secret Secret generated from Bitbucket Settings → Add Consumer
https://bitbucket.org/site/oauth2/authorize URL that you use to authorize an entity
https://bitbucket.org/site/oauth2/access_token URL that generates an access token for an entity
access_token Defines the permission of the selected user, ergo represents the authorization of a specific application to access specific parts of a user's data. Tokens that represents the authorization of an entity to access specific parts of a user's data in an application. It is the token generated or returned by https://bitbucket.org/site/oauth2/access_token

Participants

Role Description
Resource Owner/End-user 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.
Client An application making protected resource requests on behalf of the resource owner and with its authorization.
Resource Server The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.
Authorization Server The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

Prerequisite

  1. NodeJs

Running the app

  1. You are free to use the consumer key and secret configured in this project or generate your own. If you are creating your own oauth consumer, please make sure to set the callback URL to http://localhost:3000/oauth-callback as /oauth-callback processes the response from Bitbucket's Authorization server, just replace the consumerKey and consumerSecret in config.json and you're good to go.
  2. In the project's root directory, run npm install. This should download all the dependencies for you needed by the app
  3. Once download is complete, run npm start
  4. Open your browser and launch: http://localhost:3000/ , this should display an intuitive page on how to go through the authorization flow

See it live here

Navigating the app

Endpoint Description
/ Redirects the user to the landing page of the sample app
/healthcheck Test whether your app is alive
/authorize Redirects the user for permission to access, if not yet authorized to access. Once you've granted access to your data, invoking this endpoint would get a temporary code from Bitbucket's authorization server and returned to the callback URL defined in OAuth consumer settings
/oauth-callback This is where the action happens! This is the callback URL that the authorization server recognizes that would receive the temporary code (if authorization code grant is used) and access_tokens for others

Support

If you have any questions about this app or simply want to give us feedback please do so in the Bitbucket Cloud category on the Developer Community.