نسخه:

پاسپورت لاراول

معرفی

Laravel Passport یک اجرای کامل سرور OAuth2 را برای برنامه لاراول شما در عرض چند دقیقه فراهم می کند. پاسپورت بر روی سرور League OAuth2 ساخته شده است که توسط اندی میلینگتون و سایمون هامپ نگهداری می شود.

این مستندات فرض می‌کند که شما قبلاً با OAuth2 آشنا هستید. اگر چیزی در مورد OAuth2 نمی دانید، قبل از ادامه با اصطلاحات و ویژگی های کلی OAuth2 آشنا شوید.

پاسپورت یا پناهگاه؟

قبل از شروع، ممکن است بخواهید تعیین کنید که آیا درخواست شما توسط Laravel Passport یا Laravel Sanctum بهتر ارائه می شود . اگر برنامه شما کاملاً نیاز به پشتیبانی از OAuth2 دارد، باید از Laravel Passport استفاده کنید.

با این حال، اگر می‌خواهید یک برنامه تک صفحه‌ای، برنامه تلفن همراه یا توکن‌های API را تأیید کنید، باید از Laravel Sanctum استفاده کنید . Laravel Sanctum از OAuth2 پشتیبانی نمی کند. با این حال، تجربه توسعه احراز هویت API بسیار ساده‌تر را فراهم می‌کند.

نصب و راه اندازی

می توانید Laravel Passport را از طریق install:api دستور Artisan نصب کنید: 

php artisan install:api --passport

این دستور مهاجرت های پایگاه داده لازم برای ایجاد جداول مورد نیاز برنامه شما برای ذخیره کلاینت های OAuth2 و توکن های دسترسی را منتشر و اجرا می کند. این فرمان همچنین کلیدهای رمزگذاری مورد نیاز برای تولید توکن های دسترسی ایمن را ایجاد می کند.

علاوه بر این، این دستور از شما می پرسد که آیا می خواهید از UUID ها به عنوان مقدار کلید اصلی مدل پاسپورت Client به جای افزایش خودکار اعداد صحیح استفاده کنید.

پس از اجرای install:api دستور، Laravel\Passport\HasApiTokens ویژگی را به App\Models\User مدل خود اضافه کنید. این ویژگی چند روش کمکی به مدل شما ارائه می دهد که به شما امکان می دهد توکن و محدوده کاربر تأیید شده را بررسی کنید: 

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens;
 
class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

در نهایت، در فایل پیکربندی برنامه خود config/auth.php ، باید یک api محافظ احراز هویت تعریف کنید و driver گزینه را روی passport . این به برنامه شما دستور می دهد تا TokenGuard هنگام احراز هویت درخواست های API ورودی از Passport استفاده کند : 

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
 
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

استقرار پاسپورت

هنگام استقرار Passport برای اولین بار در سرورهای برنامه خود، احتمالاً باید این passport:keys دستور را اجرا کنید. این دستور کلیدهای رمزگذاری مورد نیاز Passport را برای تولید نشانه های دسترسی تولید می کند. کلیدهای تولید شده معمولاً در کنترل منبع نگهداری نمی شوند: 

php artisan passport:keys

در صورت لزوم، می‌توانید مسیری را که کلیدهای پاسپورت باید از آنجا بارگیری شوند، تعیین کنید. Passport::loadKeysFrom برای انجام این کار می توانید از روش استفاده کنید . به طور معمول، این متد باید از boot متد کلاس برنامه شما فراخوانی شود App\Providers\AppServiceProvider : 

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::loadKeysFrom(__DIR__.'/../secrets/oauth');
}

بارگیری کلیدها از محیط

همچنین، می‌توانید فایل پیکربندی Passport را با استفاده از vendor:publish دستور Artisan منتشر کنید: 

php artisan vendor:publish --tag=passport-config

پس از انتشار فایل پیکربندی، می توانید کلیدهای رمزگذاری برنامه خود را با تعریف آنها به عنوان متغیرهای محیطی بارگیری کنید: 

PASSPORT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
<private key here>
-----END RSA PRIVATE KEY-----"
 
PASSPORT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
<public key here>
-----END PUBLIC KEY-----"

ارتقاء پاسپورت

هنگام ارتقاء به نسخه اصلی جدید پاسپورت، مهم است که راهنمای ارتقا را به دقت مرور کنید .

پیکربندی

Client Secret Hashing

اگر می خواهید اسرار مشتری شما هنگام ذخیره در پایگاه داده هش شود، باید متد موجود Passport::hashClientSecrets در boot متد کلاس خود را فراخوانی کنید App\Providers\AppServiceProvider : 

use Laravel\Passport\Passport;
 
Passport::hashClientSecrets();

پس از فعال شدن، تمام اسرار مشتری شما بلافاصله پس از ایجاد برای کاربر قابل نمایش خواهند بود. از آنجایی که مقدار مخفی کلاینت متن ساده هرگز در پایگاه داده ذخیره نمی شود، در صورت از بین رفتن مقدار راز امکان بازیابی آن وجود ندارد.

طول عمر رمز

به طور پیش فرض، پاسپورت توکن های دسترسی طولانی مدت را صادر می کند که پس از یک سال منقضی می شوند. اگر می‌خواهید طول عمر توکن طولانی‌تر/کوتاه‌تر را پیکربندی کنید، می‌توانید از روش‌های tokensExpireIn ، refreshTokensExpireIn و و استفاده کنید personalAccessTokensExpireIn . این متدها باید از boot متد کلاس برنامه شما فراخوانی شوند App\Providers\AppServiceProvider : 

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::tokensExpireIn(now()->addDays(15));
    Passport::refreshTokensExpireIn(now()->addDays(30));
    Passport::personalAccessTokensExpireIn(now()->addMonths(6));
}

ستون‌های expires_at جداول پایگاه داده پاسپورت فقط خواندنی و فقط برای نمایش هستند. هنگام صدور توکن، پاسپورت اطلاعات انقضا را در توکن های امضا شده و رمزگذاری شده ذخیره می کند. اگر نیاز به باطل کردن یک توکن دارید، باید آن را باطل کنید .

نادیده گرفتن مدل های پیش فرض

شما آزاد هستید که مدل های استفاده شده داخلی توسط پاسپورت را با تعریف مدل خود و گسترش مدل پاسپورت مربوطه گسترش دهید: 

use Laravel\Passport\Client as PassportClient;
 
class Client extends PassportClient
{
    // ...
}

پس از تعریف مدل خود، می توانید به Passport دستور دهید که از مدل سفارشی شما از طریق Laravel\Passport\Passport کلاس استفاده کند. به طور معمول، شما باید Passport را در مورد مدل های سفارشی خود در boot روش کلاس برنامه خود اطلاع دهید App\Providers\AppServiceProvider : 

use App\Models\Passport\AuthCode;
use App\Models\Passport\Client;
use App\Models\Passport\PersonalAccessClient;
use App\Models\Passport\RefreshToken;
use App\Models\Passport\Token;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::useTokenModel(Token::class);
    Passport::useRefreshTokenModel(RefreshToken::class);
    Passport::useAuthCodeModel(AuthCode::class);
    Passport::useClientModel(Client::class);
    Passport::usePersonalAccessClientModel(PersonalAccessClient::class);
}

مسیرهای نادیده گرفته شده

گاهی اوقات ممکن است بخواهید مسیرهای تعریف شده توسط پاسپورت را شخصی سازی کنید. برای رسیدن به این هدف، ابتدا باید مسیرهای ثبت شده توسط پاسپورت را با اضافه کردن Passport::ignoreRoutes به register روش برنامه خود نادیده بگیرید AppServiceProvider : 

use Laravel\Passport\Passport;
 
/**
 * Register any application services.
 */
public function register(): void
{
    Passport::ignoreRoutes();
}

سپس، می توانید مسیرهای تعریف شده توسط Passport در فایل مسیرهای آن را در فایل برنامه خود کپی کنید routes/web.php و آنها را به دلخواه تغییر دهید: 

Route::group([
    'as' => 'passport.',
    'prefix' => config('passport.path', 'oauth'),
    'namespace' => '\Laravel\Passport\Http\Controllers',
], function () {
    // Passport routes...
});

صدور توکن های دسترسی

استفاده از OAuth2 از طریق کدهای مجوز، روشی است که اکثر توسعه دهندگان با OAuth2 آشنا هستند. هنگام استفاده از کدهای مجوز، یک برنامه مشتری کاربر را به سرور شما هدایت می کند، جایی که آنها درخواست صدور رمز دسترسی به مشتری را تأیید یا رد می کنند.

مدیریت مشتریان

ابتدا، توسعه‌دهندگانی که برنامه‌هایی را می‌سازند که نیاز به تعامل با API برنامه شما دارند، باید برنامه خود را با ایجاد یک «کلینت» در اپلیکیشن شما ثبت کنند. به طور معمول، این شامل ارائه نام برنامه و یک URL است که برنامه شما می تواند پس از تأیید درخواست مجوز توسط کاربران، به آن هدایت شود.

دستور passport:client ​

ساده ترین راه برای ایجاد مشتری استفاده از passport:client دستور Artisan است. این دستور ممکن است برای ایجاد کلاینت های خود برای آزمایش عملکرد OAuth2 استفاده شود. هنگامی که دستور را اجرا می کنید client ، Passport از شما می خواهد اطلاعات بیشتری در مورد مشتری خود دریافت کنید و یک شناسه مشتری و راز را در اختیار شما قرار می دهد: 

php artisan passport:client

تغییر مسیر URL ها

اگر می‌خواهید چندین URL تغییر مسیر را برای مشتری خود مجاز کنید، می‌توانید آنها را با استفاده از یک لیست محدود شده با کاما در زمانی که دستور URL از شما خواسته می‌شود، مشخص کنید passport:client . هر نشانی اینترنتی که حاوی کاما است باید URL کدگذاری شده باشد: 

http://example.com/callback,http://examplefoo.com/callback

JSON API

از آنجایی که کاربران برنامه شما نمی توانند از این client دستور استفاده کنند، Passport یک API JSON ارائه می دهد که می توانید از آن برای ایجاد کلاینت استفاده کنید. این کار شما را از مشکل کدنویسی دستی کنترلرها برای ایجاد، به‌روزرسانی و حذف کلاینت‌ها نجات می‌دهد.

با این حال، باید API JSON Passport را با ظاهر خود جفت کنید تا داشبوردی برای کاربران خود فراهم کنید تا مشتریان خود را مدیریت کنند. در زیر، همه نقاط پایانی API را برای مدیریت مشتریان بررسی می‌کنیم. برای راحتی، از Axios برای نشان دادن درخواست های HTTP به نقاط پایانی استفاده می کنیم .

JSON API توسط میان افزار web و auth میان افزار محافظت می شود. بنابراین، ممکن است فقط از برنامه خود شما فراخوانی شود. امکان فراخوانی از منبع خارجی وجود ندارد.

GET /oauth/clients

این مسیر همه کلاینت ها را برای کاربر احراز هویت شده برمی گرداند. این در درجه اول برای فهرست کردن همه مشتریان کاربر مفید است تا آنها بتوانند آنها را ویرایش یا حذف کنند: 

axios.get('/oauth/clients')
    .then(response => {
        console.log(response.data);
    });

POST /oauth/clients

این مسیر برای ایجاد مشتریان جدید استفاده می شود. به دو داده نیاز دارد: مشتری name و redirect URL. URL redirect جایی است که کاربر پس از تأیید یا رد درخواست مجوز هدایت می شود.

هنگامی که یک کلاینت ایجاد می شود، شناسه مشتری و راز مشتری برای آن صادر می شود. این مقادیر هنگام درخواست نشانه های دسترسی از برنامه شما استفاده می شود. مسیر ایجاد مشتری، نمونه مشتری جدید را برمی گرداند: 

const data = {
    name: 'Client Name',
    redirect: 'http://example.com/callback'
};
 
axios.post('/oauth/clients', data)
    .then(response => {
        console.log(response.data);
    })
    .catch (response => {
        // List errors on response...
    });

PUT /oauth/clients/{client-id}

این مسیر برای به روز رسانی کلاینت ها استفاده می شود. به دو داده نیاز دارد: مشتری name و redirect URL. URL redirect جایی است که کاربر پس از تأیید یا رد درخواست مجوز هدایت می شود. مسیر نمونه مشتری به روز شده را برمی گرداند: 

const data = {
    name: 'New Client Name',
    redirect: 'http://example.com/callback'
};
 
axios.put('/oauth/clients/' + clientId, data)
    .then(response => {
        console.log(response.data);
    })
    .catch (response => {
        // List errors on response...
    });

DELETE /oauth/clients/{client-id}

این مسیر برای حذف کلاینت ها استفاده می شود: 

axios.delete('/oauth/clients/' + clientId)
    .then(response => {
        // ...
    });

درخواست توکن

تغییر مسیر برای مجوز

هنگامی که یک کلاینت ایجاد شد، توسعه دهندگان ممکن است از شناسه مشتری و راز خود برای درخواست کد مجوز و رمز دسترسی از برنامه شما استفاده کنند. ابتدا، برنامه مصرف کننده باید یک درخواست تغییر مسیر به مسیر برنامه شما /oauth/authorize مانند زیر ارسال کند: 

use Illuminate\Http\Request;
use Illuminate\Support\Str;
 
Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));
 
    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://third-party-app.com/callback',
        'response_type' => 'code',
        'scope' => '',
        'state' => $state,
        // 'prompt' => '', // "none", "consent", or "login"
    ]);
 
    return redirect('http://passport-app.test/oauth/authorize?'.$query);
});

این prompt پارامتر ممکن است برای تعیین رفتار احراز هویت برنامه Passport استفاده شود.

اگر prompt مقدار باشد none ، اگر کاربر قبلاً با برنامه پاسپورت احراز هویت نشده باشد، پاسپورت همیشه یک خطای احراز هویت می دهد. اگر مقدار باشد consent ، پاسپورت همیشه صفحه تأیید مجوز را نشان می‌دهد، حتی اگر همه دامنه‌ها قبلاً به برنامه مصرف‌کننده اعطا شده باشد. وقتی مقدار است login ، برنامه پاسپورت همیشه از کاربر می خواهد که دوباره به برنامه وارد شود، حتی اگر قبلاً یک جلسه موجود داشته باشد.

اگر prompt مقداری ارائه نشده باشد، تنها در صورتی از کاربر درخواست مجوز می‌شود که قبلاً مجوز دسترسی به برنامه مصرف‌کننده برای محدوده‌های درخواستی را نداشته باشد.

به یاد داشته باشید، /oauth/authorize مسیر قبلاً توسط پاسپورت تعریف شده است. نیازی به تعریف دستی این مسیر ندارید.

تایید درخواست

هنگام دریافت درخواست های مجوز، پاسپورت به طور خودکار بر اساس مقدار prompt پارامتر (در صورت وجود) پاسخ می دهد و ممکن است الگویی را به کاربر نمایش دهد که به کاربر اجازه می دهد درخواست مجوز را تأیید یا رد کند. اگر آنها درخواست را تأیید کنند، به همان چیزی که redirect_uri توسط برنامه مصرف کننده مشخص شده است هدایت می شوند. باید با URL که هنگام ایجاد مشتری مشخص شده بود redirect_uri مطابقت داشته باشد . redirect

اگر می‌خواهید صفحه تأیید مجوز را سفارشی کنید، می‌توانید نماهای پاسپورت را با استفاده از vendor:publish دستور Artisan منتشر کنید. نماهای منتشر شده در resources/views/vendor/passport دایرکتوری قرار خواهند گرفت: 

php artisan vendor:publish --tag=passport-views

گاهی اوقات ممکن است بخواهید از درخواست مجوز صرفنظر کنید، مانند زمانی که یک مشتری شخص اول را مجوز می دهید. شما می توانید این کار را با گسترش Client مدل و تعریف یک skipsAuthorization روش انجام دهید. در صورت skipsAuthorization بازگرداندن true ، کلاینت تأیید می شود و کاربر فوراً به برنامه بازگردانده می شود redirect_uri ، مگر اینکه برنامه مصرف کننده به صراحت prompt پارامتر را هنگام هدایت مجدد برای مجوز تنظیم کرده باشد: 

<?php
 
namespace App\Models\Passport;
 
use Laravel\Passport\Client as BaseClient;
 
class Client extends BaseClient
{
    /**
     * Determine if the client should skip the authorization prompt.
     */
    public function skipsAuthorization(): bool
    {
        return $this->firstParty();
    }
}

تبدیل کدهای مجوز به توکن های دسترسی

اگر کاربر درخواست مجوز را تأیید کند، به برنامه مصرف کننده هدایت می شود. مصرف کننده ابتدا باید state پارامتر را در برابر مقداری که قبل از تغییر مسیر ذخیره شده بود تأیید کند. اگر پارامتر حالت مطابقت داشته باشد، مصرف کننده باید POST درخواستی برای درخواست توکن دسترسی به برنامه شما بدهد. درخواست باید شامل کد مجوزی باشد که زمانی که کاربر درخواست مجوز را تأیید کرد، توسط برنامه شما صادر شده است: 

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
 
Route::get('/callback', function (Request $request) {
    $state = $request->session()->pull('state');
 
    throw_unless(
        strlen($state) > 0 && $state === $request->state,
        InvalidArgumentException::class,
        'Invalid state value.'
    );
 
    $response = Http::asForm()->post('http://passport-app.test/oauth/token', [
        'grant_type' => 'authorization_code',
        'client_id' => 'client-id',
        'client_secret' => 'client-secret',
        'redirect_uri' => 'http://third-party-app.com/callback',
        'code' => $request->code,
    ]);
 
    return $response->json();
});

این مسیر یک پاسخ JSON حاوی , و ویژگی ها /oauth/token را برمی گرداند . این ویژگی حاوی تعداد ثانیه هایی است که تا زمانی که نشانه دسترسی منقضی شود. access_token refresh_token expires_in expires_in

مانند /oauth/authorize مسیر، /oauth/token مسیر نیز با پاسپورت برای شما تعریف می شود. نیازی به تعریف دستی این مسیر نیست.

JSON API

پاسپورت همچنین دارای یک API JSON برای مدیریت توکن های دسترسی مجاز است. می‌توانید این را با ظاهر خود جفت کنید تا به کاربران خود داشبوردی برای مدیریت توکن‌های دسترسی ارائه دهید. برای راحتی، از Axios برای نشان دادن درخواست های HTTP به نقاط پایانی استفاده می کنیم . JSON API توسط میان افزار web و auth میان افزار محافظت می شود. بنابراین، ممکن است فقط از برنامه خود شما فراخوانی شود.

GET /oauth/tokens

این مسیر تمام نشانه های دسترسی مجاز را که کاربر احراز هویت شده ایجاد کرده است، برمی گرداند. این در درجه اول برای فهرست کردن تمام نشانه های کاربر مفید است تا آنها بتوانند آنها را باطل کنند: 

axios.get('/oauth/tokens')
    .then(response => {
        console.log(response.data);
    });

DELETE /oauth/tokens/{token-id}

این مسیر ممکن است برای لغو نشانه‌های دسترسی مجاز و نشانه‌های تازه‌سازی مرتبط با آن‌ها استفاده شود: 

axios.delete('/oauth/tokens/' + tokenId);

نشانه های تازه کردن

اگر برنامه شما کدهای دسترسی کوتاه مدت صادر می کند، کاربران باید نشانه های دسترسی خود را از طریق نشانه رفرشی که هنگام صدور نشانه دسترسی به آنها ارائه شده است، بازخوانی کنند: 

use Illuminate\Support\Facades\Http;
 
$response = Http::asForm()->post('http://passport-app.test/oauth/token', [
    'grant_type' => 'refresh_token',
    'refresh_token' => 'the-refresh-token',
    'client_id' => 'client-id',
    'client_secret' => 'client-secret',
    'scope' => '',
]);
 
return $response->json();

این مسیر یک پاسخ JSON حاوی , و ویژگی ها /oauth/token را برمی گرداند . این ویژگی حاوی تعداد ثانیه هایی است که تا زمانی که نشانه دسترسی منقضی شود. access_token refresh_token expires_in expires_in

ابطال توکن ها

شما می توانید با استفاده از revokeAccessToken روش موجود در Laravel\Passport\TokenRepository . می‌توانید نشانه‌های به‌روزرسانی یک نشانه را با استفاده از revokeRefreshTokensByAccessTokenId روش موجود در ابطال کنید Laravel\Passport\RefreshTokenRepository . این کلاس ها ممکن است با استفاده از کانتینر سرویس لاراول حل شوند : 

use Laravel\Passport\TokenRepository;
use Laravel\Passport\RefreshTokenRepository;
 
$tokenRepository = app(TokenRepository::class);
$refreshTokenRepository = app(RefreshTokenRepository::class);
 
// Revoke an access token...
$tokenRepository->revokeAccessToken($tokenId);
 
// Revoke all of the token's refresh tokens...
$refreshTokenRepository->revokeRefreshTokensByAccessTokenId($tokenId);

پاکسازی توکن ها

هنگامی که توکن ها باطل یا منقضی شدند، ممکن است بخواهید آنها را از پایگاه داده پاک کنید. دستور Artisan شامل پاسپورت passport:purge می تواند این کار را برای شما انجام دهد: 

# Purge revoked and expired tokens and auth codes...
php artisan passport:purge
 
# Only purge tokens expired for more than 6 hours...
php artisan passport:purge --hours=6
 
# Only purge revoked tokens and auth codes...
php artisan passport:purge --revoked
 
# Only purge expired tokens and auth codes...
php artisan passport:purge --expired

همچنین می‌توانید یک کار زمان‌بندی‌شده را در فایل برنامه‌تان پیکربندی کنید routes/console.php تا به‌طور خودکار توکن‌هایتان را بر اساس یک زمان‌بندی هرس کند: 

use Laravel\Support\Facades\Schedule;
 
Schedule::command('passport:purge')->hourly();

اعطای کد مجوز با PKCE

اعطای کد مجوز با "کلید اثبات برای تبادل کد" (PKCE) راهی امن برای احراز هویت برنامه های کاربردی تک صفحه ای یا برنامه های کاربردی بومی برای دسترسی به API شما است. این کمک هزینه زمانی باید استفاده شود که نمی‌توانید تضمین کنید که راز مشتری به‌طور محرمانه ذخیره می‌شود یا به منظور کاهش خطر رهگیری کد مجوز توسط مهاجم. ترکیبی از "تأیید کننده کد" و "چالش کد" جایگزین رمز مشتری در هنگام مبادله کد مجوز برای یک نشانه دسترسی می شود.

ایجاد مشتری

قبل از اینکه برنامه شما بتواند از طریق اعطای کد مجوز با PKCE توکن صادر کند، باید یک کلاینت با قابلیت PKCE ایجاد کنید. می توانید این کار را با استفاده از passport:client دستور Artisan با --public گزینه زیر انجام دهید: 

php artisan passport:client --public

درخواست توکن

تأیید کننده کد و چالش کد

از آنجایی که این اعطای مجوز یک راز مشتری ارائه نمی‌کند، توسعه‌دهندگان باید ترکیبی از تأییدکننده کد و چالش کد را برای درخواست یک رمز ایجاد کنند.

تأییدکننده کد باید یک رشته تصادفی بین 43 تا 128 کاراکتر باشد که شامل حروف، اعداد و نویسه‌های ، , "-" , همانطور که در مشخصات RFC 7636 تعریف شده است . "." "_" "~"

چالش کد باید یک رشته رمزگذاری شده Base64 با URL و کاراکترهای ایمن برای نام فایل باشد. کاراکترهای انتهایی '=' باید حذف شوند و هیچ خط شکنی، فضای خالی یا سایر کاراکترهای اضافی نباید وجود داشته باشد. 

$encoded = base64_encode(hash('sha256', $code_verifier, true));
 
$codeChallenge = strtr(rtrim($encoded, '='), '+/', '-_');

تغییر مسیر برای مجوز

هنگامی که یک کلاینت ایجاد شد، می توانید از شناسه مشتری و تأیید کننده کد تولید شده و چالش کد برای درخواست کد مجوز و رمز دسترسی از برنامه خود استفاده کنید. ابتدا، برنامه مصرف کننده باید یک درخواست تغییر مسیر به /oauth/authorize مسیر برنامه شما ارسال کند: 

use Illuminate\Http\Request;
use Illuminate\Support\Str;
 
Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));
 
    $request->session()->put(
        'code_verifier', $code_verifier = Str::random(128)
    );
 
    $codeChallenge = strtr(rtrim(
        base64_encode(hash('sha256', $code_verifier, true))
    , '='), '+/', '-_');
 
    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://third-party-app.com/callback',
        'response_type' => 'code',
        'scope' => '',
        'state' => $state,
        'code_challenge' => $codeChallenge,
        'code_challenge_method' => 'S256',
        // 'prompt' => '', // "none", "consent", or "login"
    ]);
 
    return redirect('http://passport-app.test/oauth/authorize?'.$query);
});

تبدیل کدهای مجوز به توکن های دسترسی

اگر کاربر درخواست مجوز را تأیید کند، به برنامه مصرف کننده هدایت می شود. مصرف کننده باید state پارامتر را در برابر مقداری که قبل از تغییر مسیر ذخیره شده است، تأیید کند، همانطور که در اعطای کد مجوز استاندارد وجود دارد.

اگر پارامتر حالت مطابقت داشته باشد، مصرف کننده باید POST درخواستی برای درخواست توکن دسترسی به برنامه شما صادر کند. این درخواست باید شامل کد مجوزی باشد که زمانی که کاربر درخواست مجوز را تأیید کرد توسط برنامه شما صادر شده است به همراه تأییدکننده کد اولیه ایجاد شده: 

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
 
Route::get('/callback', function (Request $request) {
    $state = $request->session()->pull('state');
 
    $codeVerifier = $request->session()->pull('code_verifier');
 
    throw_unless(
        strlen($state) > 0 && $state === $request->state,
        InvalidArgumentException::class
    );
 
    $response = Http::asForm()->post('http://passport-app.test/oauth/token', [
        'grant_type' => 'authorization_code',
        'client_id' => 'client-id',
        'redirect_uri' => 'http://third-party-app.com/callback',
        'code_verifier' => $codeVerifier,
        'code' => $request->code,
    ]);
 
    return $response->json();
});

رمزهای اعطای رمز عبور

ما دیگر استفاده از رمزهای اعطای رمز عبور را توصیه نمی کنیم. در عوض، باید نوع کمک مالی را انتخاب کنید که در حال حاضر توسط OAuth2 Server توصیه شده است .

اعطای رمز عبور OAuth2 به دیگر مشتریان شخص اول شما، مانند یک برنامه تلفن همراه، اجازه می دهد تا با استفاده از آدرس ایمیل / نام کاربری و رمز عبور، رمز دسترسی به دست آورند. این به شما امکان می‌دهد تا توکن‌های دسترسی را به طور ایمن برای مشتریان شخص اول خود صادر کنید، بدون اینکه کاربران خود را ملزم به گذراندن کل جریان تغییر مسیر کد مجوز OAuth2 کنید.

برای فعال کردن اعطای رمز عبور، enablePasswordGrant متد موجود در boot متد کلاس برنامه خود را فراخوانی کنید App\Providers\AppServiceProvider : 

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::enablePasswordGrant();
}

ایجاد یک مشتری اعطای رمز عبور

قبل از اینکه برنامه شما بتواند از طریق اعطای رمز عبور توکن صادر کند، باید یک کلاینت اعطای رمز عبور ایجاد کنید. می توانید این کار را با استفاده از passport:client دستور Artisan با --password گزینه انجام دهید. اگر قبلاً دستور را اجرا کرده اید passport:install ، نیازی به اجرای این دستور ندارید: 

php artisan passport:client --password

درخواست توکن

هنگامی که یک کلاینت اعطای رمز عبور ایجاد کردید، می توانید با ارسال یک POST درخواست به /oauth/token مسیر با آدرس ایمیل و رمز عبور کاربر، یک نشانه دسترسی درخواست کنید. به یاد داشته باشید، این مسیر قبلاً توسط پاسپورت ثبت شده است، بنابراین نیازی به تعریف دستی آن نیست. اگر درخواست موفقیت آمیز باشد، پاسخ JSON را از سرور دریافت خواهید access_token کرد refresh_token : 

use Illuminate\Support\Facades\Http;
 
$response = Http::asForm()->post('http://passport-app.test/oauth/token', [
    'grant_type' => 'password',
    'client_id' => 'client-id',
    'client_secret' => 'client-secret',
    'username' => 'taylor@laravel.com',
    'password' => 'my-password',
    'scope' => '',
]);
 
return $response->json();

به یاد داشته باشید که توکن های دسترسی به طور پیش فرض عمر طولانی دارند. با این حال، در صورت نیاز می توانید حداکثر طول عمر رمز دسترسی خود را پیکربندی کنید .

درخواست همه دامنه ها

هنگام استفاده از اعطای رمز عبور یا اعطای اعتبار مشتری، ممکن است بخواهید توکن را برای همه حوزه‌های پشتیبانی شده توسط برنامه خود تأیید کنید. شما می توانید این کار را با درخواست * دامنه انجام دهید. اگر دامنه را درخواست کنید * ، can متد موجود در نمونه توکن همیشه برمی‌گردد true . این محدوده ممکن است فقط به یک توکن اختصاص داده شود که با استفاده از password یا client_credentials کمک مالی صادر می شود: 

use Illuminate\Support\Facades\Http;
 
$response = Http::asForm()->post('http://passport-app.test/oauth/token', [
    'grant_type' => 'password',
    'client_id' => 'client-id',
    'client_secret' => 'client-secret',
    'username' => 'taylor@laravel.com',
    'password' => 'my-password',
    'scope' => '*',
]);

سفارشی کردن ارائه دهنده کاربر

اگر برنامه شما از بیش از یک ارائه‌دهنده کاربر احراز هویت --provider استفاده می‌کند، می‌توانید با ارائه گزینه‌ای هنگام ایجاد سرویس گیرنده از طریق دستور ، مشخص کنید که مشتری اعطای رمز عبور از کدام ارائه‌دهنده کاربری استفاده می‌کند artisan passport:client --password . نام ارائه دهنده داده شده باید با ارائه دهنده معتبر تعریف شده در فایل پیکربندی برنامه شما مطابقت داشته باشد config/auth.php . سپس می‌توانید با استفاده از میان‌افزار از مسیر خود محافظت کنید تا مطمئن شوید که فقط کاربرانی از ارائه‌دهنده مشخص‌شده گارد مجاز هستند.

سفارشی کردن فیلد نام کاربری

هنگام احراز هویت با استفاده از اعطای رمز عبور، Passport email از ویژگی مدل قابل احراز هویت شما به عنوان "نام کاربری" استفاده می کند. با این حال، می توانید این رفتار را با تعریف findForPassport روشی در مدل خود سفارشی کنید: 

<?php
 
namespace App\Models;
 
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens;
 
class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
 
    /**
     * Find the user instance for the given username.
     */
    public function findForPassport(string $username): User
    {
        return $this->where('username', $username)->first();
    }
}

سفارشی کردن اعتبارسنجی رمز عبور

هنگام احراز هویت با استفاده از اعطای رمز عبور، Passport password از ویژگی مدل شما برای تأیید اعتبار رمز عبور داده شده استفاده می کند. اگر مدل شما ویژگی ندارد password یا می‌خواهید منطق اعتبارسنجی رمز عبور را سفارشی کنید، می‌توانید validateForPassportPasswordGrant روشی را بر روی مدل خود تعریف کنید: 

<?php
 
namespace App\Models;
 
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Illuminate\Support\Facades\Hash;
use Laravel\Passport\HasApiTokens;
 
class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
 
    /**
     * Validate the password of the user for the Passport password grant.
     */
    public function validateForPassportPasswordGrant(string $password): bool
    {
        return Hash::check($password, $this->password);
    }
}

توکن های اعطای ضمنی

ما دیگر استفاده از نشانه‌های اعطایی ضمنی را توصیه نمی‌کنیم. در عوض، باید نوع کمک مالی را انتخاب کنید که در حال حاضر توسط OAuth2 Server توصیه شده است .

کمک هزینه ضمنی مشابه اعطای کد مجوز است. با این حال، توکن بدون تبادل کد مجوز به مشتری بازگردانده می شود. این کمک هزینه بیشتر برای جاوا اسکریپت یا برنامه های تلفن همراه استفاده می شود که در آنها اعتبار مشتری نمی تواند به طور ایمن ذخیره شود. برای فعال کردن کمک هزینه، enableImplicitGrant متد را در boot متد کلاس برنامه خود فراخوانی کنید App\Providers\AppServiceProvider : 

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::enableImplicitGrant();
}

پس از فعال شدن کمک هزینه، توسعه دهندگان ممکن است از شناسه مشتری خود برای درخواست رمز دسترسی از برنامه شما استفاده کنند. برنامه مصرف کننده باید یک درخواست تغییر مسیر به مسیر برنامه شما /oauth/authorize مانند زیر ارسال کند: 

use Illuminate\Http\Request;
 
Route::get('/redirect', function (Request $request) {
    $request->session()->put('state', $state = Str::random(40));
 
    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://third-party-app.com/callback',
        'response_type' => 'token',
        'scope' => '',
        'state' => $state,
        // 'prompt' => '', // "none", "consent", or "login"
    ]);
 
    return redirect('http://passport-app.test/oauth/authorize?'.$query);
});

به یاد داشته باشید، /oauth/authorize مسیر قبلاً توسط پاسپورت تعریف شده است. نیازی به تعریف دستی این مسیر ندارید.

توکن های اعطای اعتبار مشتری

اعطای اعتبار مشتری برای احراز هویت ماشین به ماشین مناسب است. برای مثال، ممکن است از این کمک هزینه در یک کار برنامه ریزی شده استفاده کنید که وظایف تعمیر و نگهداری را از طریق یک API انجام می دهد.

قبل از اینکه برنامه شما بتواند از طریق اعطای اعتبار مشتری، توکن صادر کند، باید یک مشتری اعطای اعتبار مشتری ایجاد کنید. می توانید این کار را با استفاده از --client گزینه passport:client دستور Artisan انجام دهید: 

php artisan passport:client --client

در مرحله بعد، برای استفاده از این نوع کمک هزینه، یک نام مستعار میان افزار برای CheckClientCredentials میان افزار ثبت کنید. می‌توانید در bootstrap/app.php فایل برنامه خود، نام مستعار میان‌افزار را تعریف کنید: 

use Laravel\Passport\Http\Middleware\CheckClientCredentials;
 
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'client' => CheckClientCredentials::class
    ]);
})

سپس میان افزار را به یک مسیر وصل کنید: 

Route::get('/orders', function (Request $request) {
    ...
})->middleware('client');

client برای محدود کردن دسترسی به مسیر به محدوده‌های خاص، می‌توانید هنگام اتصال میان‌افزار به مسیر ، فهرستی از محدوده‌های مورد نیاز با کاما ارائه دهید : 

Route::get('/orders', function (Request $request) {
    ...
})->middleware('client:check-status,your-scope');

بازیابی توکن ها

برای بازیابی یک نشانه با استفاده از این نوع کمک هزینه، یک درخواست به oauth/token نقطه پایانی ارسال کنید: 

use Illuminate\Support\Facades\Http;
 
$response = Http::asForm()->post('http://passport-app.test/oauth/token', [
    'grant_type' => 'client_credentials',
    'client_id' => 'client-id',
    'client_secret' => 'client-secret',
    'scope' => 'your-scope',
]);
 
return $response->json()['access_token'];

توکن های دسترسی شخصی

گاهی اوقات، کاربران شما ممکن است بخواهند بدون عبور از جریان تغییر مسیر کد مجوز معمولی، توکن های دسترسی را برای خود صادر کنند. اجازه دادن به کاربران برای صدور نشانه برای خود از طریق UI برنامه شما می تواند برای اجازه دادن به کاربران برای آزمایش با API شما مفید باشد یا ممکن است به عنوان یک رویکرد ساده تر برای صدور توکن های دسترسی به طور کلی باشد.

اگر برنامه شما عمدتاً از Passport برای صدور توکن های دسترسی شخصی استفاده می کند، از Laravel Sanctum ، کتابخانه سبک وزن لاراول برای صدور توکن های دسترسی API استفاده کنید.

ایجاد یک کلاینت دسترسی شخصی

قبل از اینکه برنامه شما بتواند توکن های دسترسی شخصی صادر کند، باید یک کلاینت دسترسی شخصی ایجاد کنید. می توانید این کار را با اجرای passport:client دستور Artisan با --personal گزینه انجام دهید. اگر قبلاً دستور را اجرا کرده اید passport:install ، نیازی به اجرای این دستور ندارید: 

php artisan passport:client --personal

پس از ایجاد مشتری دسترسی شخصی خود، شناسه مشتری و مقدار مخفی متن ساده را در .env فایل برنامه خود قرار دهید: 

PASSPORT_PERSONAL_ACCESS_CLIENT_ID="client-id-value"
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET="unhashed-client-secret-value"

مدیریت توکن های دسترسی شخصی

هنگامی که یک کلاینت دسترسی شخصی ایجاد کردید، می توانید با استفاده از createToken روش موجود در App\Models\User نمونه مدل، توکن هایی را برای یک کاربر مشخص صادر کنید. این createToken متد نام نشانه را به عنوان اولین آرگومان خود و یک آرایه اختیاری از دامنه ها را به عنوان آرگومان دوم می پذیرد: 

use App\Models\User;
 
$user = User::find(1);
 
// Creating a token without scopes...
$token = $user->createToken('Token Name')->accessToken;
 
// Creating a token with scopes...
$token = $user->createToken('My Token', ['place-orders'])->accessToken;

JSON API

پاسپورت همچنین دارای یک API JSON برای مدیریت توکن های دسترسی شخصی است. می‌توانید این را با ظاهر خود جفت کنید تا به کاربران خود داشبوردی برای مدیریت نشانه‌های دسترسی شخصی ارائه دهید. در زیر، تمام نقاط پایانی API را برای مدیریت نشانه‌های دسترسی شخصی بررسی می‌کنیم. برای راحتی، از Axios برای نشان دادن درخواست های HTTP به نقاط پایانی استفاده می کنیم .

JSON API توسط میان افزار web و auth میان افزار محافظت می شود. بنابراین، ممکن است فقط از برنامه خود شما فراخوانی شود. امکان فراخوانی از منبع خارجی وجود ندارد.

GET /oauth/scopes

این مسیر تمام محدوده های تعریف شده برای برنامه شما را برمی گرداند. می‌توانید از این مسیر برای فهرست کردن دامنه‌هایی که کاربر ممکن است به یک نشانه دسترسی شخصی اختصاص دهد استفاده کنید: 

axios.get('/oauth/scopes')
    .then(response => {
        console.log(response.data);
    });

GET /oauth/personal-access-tokens

این مسیر تمام نشانه های دسترسی شخصی را که کاربر احراز هویت شده ایجاد کرده است، برمی گرداند. این در درجه اول برای فهرست کردن تمام نشانه های کاربر مفید است تا آنها بتوانند آنها را ویرایش یا لغو کنند: 

axios.get('/oauth/personal-access-tokens')
    .then(response => {
        console.log(response.data);
    });

POST /oauth/personal-access-tokens

این مسیر توکن های دسترسی شخصی جدیدی ایجاد می کند. به دو قطعه داده نیاز دارد: نشانه name و داده ای scopes که باید به توکن اختصاص داده شود: 

const data = {
    name: 'Token Name',
    scopes: []
};
 
axios.post('/oauth/personal-access-tokens', data)
    .then(response => {
        console.log(response.data.accessToken);
    })
    .catch (response => {
        // List errors on response...
    });

DELETE /oauth/personal-access-tokens/{token-id}

این مسیر ممکن است برای لغو نشانه های دسترسی شخصی استفاده شود: 

axios.delete('/oauth/personal-access-tokens/' + tokenId);

حفاظت از مسیرها

از طریق Middleware

پاسپورت شامل یک محافظ احراز هویت است که توکن های دسترسی را در درخواست های دریافتی تأیید می کند. هنگامی که api محافظ را برای استفاده از درایور پیکربندی کردید passport ، فقط باید auth:api میان افزار را در مسیرهایی که باید به یک نشانه دسترسی معتبر نیاز داشته باشند، مشخص کنید: 

Route::get('/user', function () {
    // ...
})->middleware('auth:api');

اگر از اعطای اعتبار مشتری استفاده می کنید ، باید به جای میان افزار از client auth:api میان افزار برای محافظت از مسیرهای خود استفاده کنید .

گاردهای احراز هویت چندگانه

اگر برنامه شما انواع مختلفی از کاربران را احراز هویت می کند که احتمالاً از مدل های Eloquent کاملاً متفاوت استفاده می کنند، احتمالاً باید برای هر نوع ارائه دهنده کاربر در برنامه خود یک پیکربندی محافظ تعریف کنید. این به شما امکان می دهد از درخواست هایی که برای ارائه دهندگان کاربر خاص در نظر گرفته شده است محافظت کنید. به عنوان مثال، با توجه به پیکربندی محافظ زیر، config/auth.php فایل پیکربندی: 

'api' => [
    'driver' => 'passport',
    'provider' => 'users',
],
 
'api-customers' => [
    'driver' => 'passport',
    'provider' => 'customers',
],

مسیر زیر از api-customers محافظی استفاده می کند که از customers ارائه دهنده کاربر برای احراز هویت درخواست های دریافتی استفاده می کند: 

Route::get('/customer', function () {
    // ...
})->middleware('auth:api-customers');

برای اطلاعات بیشتر در مورد استفاده از چندین ارائه دهنده کاربر با پاسپورت، لطفاً به اسناد اعطای رمز عبور مراجعه کنید .

عبور رمز دسترسی

هنگام فراخوانی مسیرهایی که توسط پاسپورت محافظت می شوند، مصرف کنندگان API برنامه شما باید توکن دسترسی خود را به عنوان یک Bearer توکن در Authorization هدر درخواست خود مشخص کنند. به عنوان مثال، هنگام استفاده از کتابخانه HTTP Guzzle: 

use Illuminate\Support\Facades\Http;
 
$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer '.$accessToken,
])->get('https://passport-app.test/api/user');
 
return $response->json();

محدوده توکن

Scopes به مشتریان API شما اجازه می دهد هنگام درخواست مجوز برای دسترسی به یک حساب، مجموعه خاصی از مجوزها را درخواست کنند. به عنوان مثال، اگر در حال ساخت یک برنامه تجارت الکترونیک هستید، همه مصرف کنندگان API به توانایی سفارش دادن نیاز نخواهند داشت. درعوض، می‌توانید به مصرف‌کنندگان اجازه دهید فقط برای دسترسی به وضعیت ارسال سفارش مجوز درخواست کنند. به عبارت دیگر، دامنه ها به کاربران برنامه شما اجازه می دهند تا اقداماتی را که یک برنامه شخص ثالث می تواند از طرف آنها انجام دهد محدود کنند.

تعریف محدوده ها

شما می توانید محدوده های API خود را با استفاده از Passport::tokensCan روش موجود در boot متد کلاس برنامه خود تعریف کنید App\Providers\AppServiceProvider . این tokensCan روش مجموعه‌ای از نام‌های محدوده و توصیف‌های محدوده را می‌پذیرد. شرح محدوده ممکن است هر چیزی باشد که شما بخواهید و در صفحه تایید مجوز برای کاربران نمایش داده می شود: 

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::tokensCan([
        'place-orders' => 'Place orders',
        'check-status' => 'Check order status',
    ]);
}

محدوده پیش فرض

اگر یک کلاینت دامنه خاصی را درخواست نمی کند، می توانید سرور پاسپورت خود را پیکربندی کنید تا محدوده(های) پیش فرض را با استفاده از روش به توکن متصل کند setDefaultScope . به طور معمول، شما باید این متد را از boot متد کلاس برنامه خود فراخوانی کنید App\Providers\AppServiceProvider : 

use Laravel\Passport\Passport;
 
Passport::tokensCan([
    'place-orders' => 'Place orders',
    'check-status' => 'Check order status',
]);
 
Passport::setDefaultScope([
    'check-status',
    'place-orders',
]);

دامنه‌های پیش‌فرض پاسپورت برای نشانه‌های دسترسی شخصی که توسط کاربر تولید می‌شوند اعمال نمی‌شود.

اختصاص دامنه به توکن ها

هنگام درخواست کدهای مجوز

هنگام درخواست رمز دسترسی با استفاده از اعطای کد مجوز، مصرف کنندگان باید محدوده مورد نظر خود را به عنوان scope پارامتر رشته پرس و جو مشخص کنند. پارامتر scope باید فهرستی از محدوده‌ها با فاصله محدود باشد: 

Route::get('/redirect', function () {
    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://example.com/callback',
        'response_type' => 'code',
        'scope' => 'place-orders check-status',
    ]);
 
    return redirect('http://passport-app.test/oauth/authorize?'.$query);
});

هنگام صدور توکن های دسترسی شخصی

اگر نشانه‌های دسترسی شخصی را با استفاده از روش App\Models\User مدل صادر می‌کنید createToken ، می‌توانید آرایه دامنه‌های مورد نظر را به عنوان آرگومان دوم به متد ارسال کنید: 

$token = $user->createToken('My Token', ['place-orders'])->accessToken;

بررسی محدوده ها

پاسپورت شامل دو میانافزار است که ممکن است برای تأیید اعتبار درخواست ورودی با توکنی استفاده شود که محدوده مشخصی به آن داده شده است. برای شروع، نام مستعار میان افزار زیر را در bootstrap/app.php فایل برنامه خود تعریف کنید: 

use Laravel\Passport\Http\Middleware\CheckForAnyScope;
use Laravel\Passport\Http\Middleware\CheckScopes;
 
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'scopes' => CheckScopes::class,
        'scope' => CheckForAnyScope::class,
    ]);
})

همه دامنه ها را بررسی کنید

میان‌افزار scopes ممکن است به مسیری اختصاص داده شود تا تأیید کند که رمز دسترسی درخواست ورودی دارای تمام دامنه‌های فهرست شده است: 

Route::get('/orders', function () {
    // Access token has both "check-status" and "place-orders" scopes...
})->middleware(['auth:api', 'scopes:check-status,place-orders']);

هر محدوده را بررسی کنید

میان scope افزار ممکن است به مسیری اختصاص داده شود تا تأیید کند که نشانه دسترسی درخواست ورودی حداقل یکی از حوزه های فهرست شده را دارد: 

Route::get('/orders', function () {
    // Access token has either "check-status" or "place-orders" scope...
})->middleware(['auth:api', 'scope:check-status,place-orders']);

بررسی دامنه ها در یک نمونه توکن

tokenCan هنگامی که یک درخواست احراز هویت توکن دسترسی وارد برنامه شما شد، همچنان می‌توانید با استفاده از روش موجود در App\Models\User نمونه احراز هویت شده ، بررسی کنید که آیا توکن دارای محدوده مشخصی است : 

use Illuminate\Http\Request;
 
Route::get('/orders', function (Request $request) {
    if ($request->user()->tokenCan('place-orders')) {
        // ...
    }
});

روش های دامنه اضافی

متد scopeIds آرایه ای از همه شناسه ها / نام های تعریف شده را برمی گرداند: 

use Laravel\Passport\Passport;
 
Passport::scopeIds();

متد scopes آرایه ای از تمام محدوده های تعریف شده را به عنوان نمونه های زیر برمی گرداند Laravel\Passport\Scope : 

Passport::scopes();

این scopesFor روش آرایه‌ای از Laravel\Passport\Scope نمونه‌های مطابق با شناسه‌ها/نام‌های داده شده را برمی‌گرداند: 

Passport::scopesFor(['place-orders', 'check-status']);

شما می توانید تعیین کنید که آیا یک محدوده معین با استفاده از روش تعریف شده است hasScope : 

Passport::hasScope('place-orders');

مصرف API خود با جاوا اسکریپت

هنگام ساختن یک API، این می تواند بسیار مفید باشد که بتوانید API خود را از برنامه جاوا اسکریپت خود مصرف کنید. این رویکرد برای توسعه API به برنامه کاربردی شما اجازه می‌دهد تا همان API را که با جهان به اشتراک می‌گذارید، مصرف کند. همان API ممکن است توسط برنامه های کاربردی وب، برنامه های تلفن همراه، برنامه های شخص ثالث و هر SDK که ممکن است در مدیران بسته های مختلف منتشر کنید مصرف شود.

به طور معمول، اگر می خواهید API خود را از برنامه جاوا اسکریپت خود مصرف کنید، باید به صورت دستی یک نشانه دسترسی به برنامه ارسال کنید و آن را با هر درخواست به برنامه خود ارسال کنید. با این حال، Passport شامل یک میان افزار است که می تواند این کار را برای شما انجام دهد. تنها کاری که باید انجام دهید این است که CreateFreshApiToken میان افزار را به web گروه میان افزار در فایل برنامه خود اضافه کنید bootstrap/app.php : 

use Laravel\Passport\Http\Middleware\CreateFreshApiToken;
 
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        CreateFreshApiToken::class,
    ]);
})

باید اطمینان حاصل کنید که CreateFreshApiToken میان افزار آخرین میان افزار لیست شده در پشته میان افزار شما باشد.

این میان افزار یک laravel_token کوکی به پاسخ های خروجی شما متصل می کند. این کوکی حاوی یک JWT رمزگذاری شده است که پاسپورت از آن برای احراز هویت درخواست های API از برنامه جاوا اسکریپت شما استفاده می کند. طول عمر JWT برابر با session.lifetime مقدار پیکربندی شما است. اکنون، از آنجایی که مرورگر به‌طور خودکار کوکی را با تمام درخواست‌های بعدی ارسال می‌کند، می‌توانید درخواست‌هایی را به API برنامه خود بدون ارسال صریح یک نشانه دسترسی ارسال کنید: 

axios.get('/api/user')
    .then(response => {
        console.log(response.data);
    });

در صورت نیاز، می توانید laravel_token نام کوکی را با استفاده از Passport::cookie روش سفارشی کنید. به طور معمول، این متد باید از boot متد کلاس برنامه شما فراخوانی شود App\Providers\AppServiceProvider : 

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Passport::cookie('custom_name');
}

حفاظت CSRF

هنگام استفاده از این روش احراز هویت، باید اطمینان حاصل کنید که یک هدر توکن معتبر CSRF در درخواست‌های شما گنجانده شده است. داربست پیش‌فرض جاوا اسکریپت لاراول شامل یک نمونه Axios است که به‌طور خودکار از XSRF-TOKEN مقدار کوکی رمزگذاری‌شده برای ارسال X-XSRF-TOKEN هدر در درخواست‌های با منبع مشابه استفاده می‌کند.

X-CSRF-TOKEN اگر بجای ارسال هدر انتخاب کنید X-XSRF-TOKEN ، باید از رمز رمزگذاری نشده ارائه شده توسط استفاده کنید csrf_token() .

مناسبت ها

پاسپورت رویدادها را هنگام صدور توکن های دسترسی و رفرش توکن ها افزایش می دهد. می‌توانید به این رویدادها گوش دهید تا سایر نشانه‌های دسترسی را در پایگاه داده خود حذف یا لغو کنید:

نام رخداد
Laravel\Passport\Events\AccessTokenCreated
Laravel\Passport\Events\RefreshTokenCreated

آزمایش کردن

روش پاسپورت actingAs ممکن است برای مشخص کردن کاربر تأیید شده فعلی و همچنین محدوده آن استفاده شود. اولین آرگومان داده شده به actingAs متد، نمونه کاربر است و دومی آرایه ای از دامنه است که باید به توکن کاربر اعطا شود: 

use App\Models\User;
use Laravel\Passport\Passport;
 
test('servers can be created', function () {
    Passport::actingAs(
        User::factory()->create(),
        ['create-servers']
    );
 
    $response = $this->post('/api/create-server');
 
    $response->assertStatus(201);
});
use App\Models\User;
use Laravel\Passport\Passport;
 
public function test_servers_can_be_created(): void
{
    Passport::actingAs(
        User::factory()->create(),
        ['create-servers']
    );
 
    $response = $this->post('/api/create-server');
 
    $response->assertStatus(201);
}

روش پاسپورت actingAsClient ممکن است برای مشخص کردن مشتری تأیید شده فعلی و همچنین محدوده آن استفاده شود. اولین آرگومان ارائه شده به actingAsClient متد، نمونه مشتری است و دومی آرایه ای از دامنه است که باید به توکن مشتری اعطا شود: 

use Laravel\Passport\Client;
use Laravel\Passport\Passport;
 
test('orders can be retrieved', function () {
    Passport::actingAsClient(
        Client::factory()->create(),
        ['check-status']
    );
 
    $response = $this->get('/api/orders');
 
    $response->assertStatus(200);
});
use Laravel\Passport\Client;
use Laravel\Passport\Passport;
 
public function test_orders_can_be_retrieved(): void
{
    Passport::actingAsClient(
        Client::factory()->create(),
        ['check-status']
    );
 
    $response = $this->get('/api/orders');
 
    $response->assertStatus(200);
}