Requesting Authorization

The OAuth 2.0 protocol flow begins when the application requests authorization from the user. The authorization request is typically triggered based on the user taking an action. In the case of Facebook, such an action would be the user clicking the "Log In with Facebook" button.

For example, when the user clicks the following button:

<a class="button" href="/login/federated/facebook">Log In with Facebook</a>

The user's web browser makes a request to the application:

GET /login/federated/facebook HTTP/1.1
Host: www.example.com

This request is handled by a route in the application:

router.get('/login/federated/facebook', passport.authenticate('facebook'));

The route invokes Passport, and in particular the passport-oauth2 strategy, which responds by redirecting the user's web browser to Facebook:

HTTP/1.1 302 Found
Location: https://www.facebook.com/v3.2/dialog/oauth?response_type=code&client_id=3087198538966924&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2Fredirect%2Ffacebook&state=ar75nSeG

The web browser follows this redirect and makes a request to Facebook:

GET /v3.2/dialog/oauth?response_type=code&client_id=3087198538966924&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2Fredirect%2Ffacebook&state=ar75nSeG HTTP/1.1
Host: www.facebook.com

This request to Facebook (the authorization server) is an authorization request. The request is sent to the authorization server's authorization endpoint (/v3.2/dialog/oauth, in the case of Facebook). Let's examine the parameters in this request.

  • response_type: Indicates the type of grant desired from the authorization server's response. The value code indicates that an authorization code is desired, which is used by server-side web applications.

    Recall that OAuth 2.0 is a framework. Other response types are available that support other types of applications. New types can be defined by extensions to OAuth 2.0. This guide explains OAuth 2.0 as used by server-side web applications, so details of other response types are not examined.

    The authorization code response is the first step in a larger authorization code flow. It will be paired with the later step of exchanging the code for an access token.

  • client_id: Identifies the application to the authorization server. This is assigned when registering the application with Facebook.

  • redirect_uri: URL to which the authorization server will redirect the user after completing interaction with the user.

  • state: A value used by the application to maintain state between the redirects to the authorization server and back to the application. Passport adds this automatically to prevent cross-site request forgery (CSRF) attacks.

At this point, Facebook will interact with the user. This interaction will typically involve logging the user in (if they are not already logged in) and obtaining their consent (if it has not been previously obtained). Once that has been completed, Facebook redirects the user back to the application with an authorization code:

HTTP/1.1 302 Found
Location: https://www.example.com/oauth2/redirect/facebook?code=SplxlOBeZQQYbYS6WxSbIA&state=ar75nSeG

The web browser follows this redirect and makes a request to the application:

GET /oauth2/redirect/facebook?code=SplxlOBeZQQYbYS6WxSbIA&state=ar75nSeG HTTP/1.1
Host: www.example.com

This request to the application is an authorization response. The request is sent to the application's redirection endpoint (/oauth2/redirect/facebook, in this case), which corresponds to the value of the redirect_uri parameter in the authorization request. This endpoint is often also referred to as a callback URL, as it was known in the earlier OAuth 1.0 protocol. Let's examine the parameters in this request.

  • code: The authorization code generated by the authorization server.

  • state: The value sent by the application in the authorization request.

This request is handled by a route in the application:

router.get('/oauth2/redirect/facebook', passport.authenticate('facebook', {
  successReturnToOrRedirect: '/',
  failureRedirect: '/login'
}));

This route invokes Passport, and in particular the passport-oauth2 strategy. The strategy first verifies the validity of the state parameter to prevent CSRF attacks. It then exchanges the authorization code for an access token.

SEARCH FOR STRATEGIES

0STRATEGIES