What is OAuth 2.0?

OAuth 2.0, which stands for “Open Authorization”, is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user. OAuth 2.0 provides consented access and restricts actions of what the client app can perform on resources on behalf of the user, without ever sharing the user's credentials.

OAuth 2.0 uses Access Tokens. An Access Token is a piece of data that represents the authorization to access resources on behalf of the end-user. OAuth 2.0 doesn’t define a specific format for Access Tokens. However, in some contexts, the JSON Web Token (JWT) format is often used. This enables token issuers to include data in the token itself. Also, for security reasons, Access Tokens may have an expiration date.

OAuth2.0 Actors

The idea of roles is part of the core specification of the OAuth2.0 authorization framework. These define the essential components of an OAuth 2.0 system, and are as follows:

• Resource Owner: The user or system that owns the protected resources and can grant access to them.
• Client: The client is the system that requires access to the protected resources. To access resources, the Client must hold the appropriate Access Token.
• Authorization Server: This server receives requests from the Client for Access Tokens and issues them upon successful authentication and consent by the Resource Owner. The authorization server exposes two endpoints: the Authorization endpoint, which handles the interactive authentication and consent of the user, and the Token endpoint, which is involved in a machine to machine interaction.
• Resource Server: A server that protects the user’s resources and receives access requests from the Client. It accepts and validates an Access Token from the Client and returns the appropriate resources to it.

Abstract Flow

At the most basic level, before OAuth 2.0 can be used, the Client must acquire its own credentials, a client id and client secret, from the Authorization Server in order to identify and authenticate itself when requesting an Access Token.

Using OAuth 2.0, access requests are initiated by the Client, e.g., a mobile app, website, smart TV app, desktop application, etc. The token request, exchange, and response follow this general flow:

1. The Client requests authorization (authorization request) from the Authorization server, supplying the client id and secret to as identification; it also provides the scopes and an endpoint URI (redirect URI) to send the Access Token or the Authorization Code to.
2. The Authorization server authenticates the Client and verifies that the requested scopes are permitted.
3. The Resource owner interacts with the Authorization server to grant access.
4. The Authorization server redirects back to the Client with either an Authorization Code or Access Token, depending on the grant type, as it will be explained in the next section. A Refresh Token may also be returned.
5. With the Access Token, the Client requests access to the resource from the Resource server.

Abstract Implementation

Authorize Endpoint:

Route::get('/oauth/authorize', function (Request $request) {

    // validate authorization request

    // set the user as logged in

    // return redirect response

    $params = [
        'code' => Str::random(40), // encrypted auth code
        'state' => $request->input('state'),
    ];

    return redirect('/redirect-url?' . http_build_query($params));
});

Token Endpoint:

Route::post('/oauth/token', function (Request $request) {

    // respond to token request

    return response()->json([
        'token_type' => '{token_type}', // Bearer
        'access_token' => '{access_token}',
    ]);
});

User Endpoint:

Route::get('/oauth/user', function (Request $request) {

    // authenticate user by the authorization header from the incoming request

    $user = $request->user();

    return response()->json([
        'external_id' => $user->external_id,
        'email' => $user->email,
        'name' => $user->name,
        'partner_id' => $user->partner_id,
        'client_id' => $user->client_id,
        'client_name' => $user->client_name,
        'roles' => ['Partner Administrator', 'Partner Read Only', 'Client Administrator', 'Client Read Only']
    ]);
});