[13.x] Device Authorization Grant RFC8628

[hafezdivandari]

This PR adds support for Device Authorization grant RFC 8628.

• Fix scope on device code grant thephpleague/oauth2-server#1412
• Fix including interval in response of device authorization request thephpleague/oauth2-server#1410

Additions

Grant type

• urn:ietf:params:oauth:grant-type:device_code
• RFC 8628
• Fixes Support for OAuth Device Flow #903

ORM

• oauth_device_codes table.
• Laravel\Passport\DeviceCode model.
• Passport::useDeviceCodeModel()

Routes

• POST /device/code: Request device code / user code.
• GET /device: Display a form for entering the user code.
• GET /device/authorize: Display authorization consent.
• POST /device/authorize: Approve authorization.
• DELETE /device/authorize: Deny authorization.

Views

• Passport::deviceAuthorizationView() (Jestream / Inertia sample) (Jestream / Livewire sample)
• Passport::deviceUserCodeView() (Jestream / Inertia sample) (Jestream / Livewire sample)

Commands

• New --device option on passport:client command.
• Ask user about enabling device flow on passport:client command.
• Purge expired / revoked device codes via passport:purge command.

Device Authorization Grant

The OAuth2 device authorization grant allows browserless or limited input devices, such as TVs and game consoles, to obtain an access token by exchanging a "device code". When using device flow, the device client will instruct the user to use a secondary device, such as a computer or a smartphone and connect to your server where they will enter the provided "user code" and either approve or deny the access request.

To get started, we need to instruct Passport how to return our "user code" and "authorization" views. Remember, Passport is a headless OAuth2 library. If you would like a frontend implementation of Laravel's OAuth features that are already completed for you, you should use an application starter kit.

All the authorization view's rendering logic may be customized using the appropriate methods available via the Laravel\Passport\Passport class. Typically, you should call this method from the boot method of your application's App\Providers\AppServiceProvider class. Passport will take care of defining the routes that returns these views:

use Laravel\Passport\Passport;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::deviceUserCodeView('auth.oauth.device.user-code');
    Passport::deviceAuthorizationView('auth.oauth.device.authorize');

    // ...
}

Creating a Device Code Grant Client

Before your application can issue tokens via the device authorization grant, you will need to create a device flow enabled client. You may do this using the passport:client Artisan command with the --device option:

php artisan passport:client --device

Requesting Tokens

Requesting Device Code

Once a client has been created, developers may use their client ID to request a device code from your application. First, the consuming device should make a POST request to your application's /oauth/device/code route to request a device code:

use Illuminate\Support\Facades\Http;

$response = Http::asForm()->post('http://passport-app.test/oauth/device/code', [
    'client_id' => 'client-id',
    'scope' => '',
]);

return $response->json();

This will return a JSON response containing device_code, user_code, verification_uri, interval and expires_in attributes. The expires_in attribute contains the number of seconds until the device code expires. The interval attribute contains the number of seconds, the consuming device should wait between requests, when polling \oauth\token route to avoid rate limit errors.

Note

Remember, the /oauth/device/code route is already defined by Passport. You do not need to manually define this route.

Displaying Verification URI and User Code

Once a device code request has been obtained, the consuming device should instruct the user to use another device and visit the provided verification_uri and enter the user_code in order to review the authorization request.

Polling Token Request

Since the user will be using a separate device to grant (or deny) access, the consuming device should poll your application's /oauth/token route to determine when the user has responded to the request. The consuming device should use the minimum polling interval provided in the JSON response when requesting device code to avoid rate limit errors:

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Sleep;

$interval = 5;

do {
    Sleep::for($interval)->seconds();

    $response = Http::asForm()->post('http://passport-app.test/oauth/token', [
        'grant_type' => 'urn:ietf:params:oauth:grant-type:device_code',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret', // required for confidential clients only
        'device_code' => 'device-code',
    ]);

    if ($response->json('error') === 'slow_down') {
        $interval += 5;
    }
} while (in_array($response->json('error'), ['authorization_pending', 'slow_down']));

return $response->json();

If the user has approved the authorization request, this will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.