> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Passport(OAuth2 서버 구현)

> Laravel Passport로 OAuth2 서버를 구현하는 방법을 설명합니다. Sanctum과의 사용 구분, 설치, 클라이언트 관리, 스코프와 토큰 운용까지 다룹니다.

## Passport란

Laravel Passport는 Laravel 애플리케이션을 OAuth2 인가 서버로 동작시키기 위한 공식 패키지입니다.
서드파티 앱 연동이나 엄격한 OAuth2 플로우가 필요한 API에서 사용합니다.

```mermaid theme={null}
sequenceDiagram
    participant User as 사용자
    participant Client as OAuth 클라이언트
    participant App as Laravel 앱<br>(Passport)
    participant API as 보호된 API

    User->>Client: 연동 시작
    Client->>App: 인가 요청
    App->>User: 동의 화면 표시
    User->>App: 허가
    App-->>Client: 인가 코드
    Client->>App: 인가 코드를 액세스 토큰으로 교환
    App-->>Client: 액세스 토큰
    Client->>API: Bearer 토큰과 함께 API 호출
    API-->>Client: 응답
```

## Passport vs Sanctum

OAuth2가 필수라면 Passport를 선택합니다.
단순한 API 토큰 인증이나 SPA / 모바일 인증이 목적이라면 Sanctum을 선택합니다.

| 관점     | Passport              | Sanctum             |
| ------ | --------------------- | ------------------- |
| 목적     | OAuth2 서버 구현          | 단순한 API 인증          |
| 적합한 사례 | 외부 앱 연동, OAuth2 표준 준수 | 자사 SPA, 모바일, 개인용 토큰 |
| 복잡도    | 높음                    | 낮음                  |

## 설치

Laravel 13의 공식 권장은 `install:api --passport`입니다.

```shell theme={null}
php artisan install:api --passport
```

기존 프로젝트에서 수동 도입하는 경우, 다음 명령으로도 설정할 수 있습니다.

```shell theme={null}
composer require laravel/passport
php artisan passport:install
```

첫 배포 시에는 키 생성만 실행하고 싶은 경우도 있습니다.

```shell theme={null}
php artisan passport:keys
```

## 설정

### User 모델

`User` 모델에 `HasApiTokens` 트레이트와 `OAuthenticatable` 인터페이스를 추가합니다.

```php theme={null}
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}
```

### auth 가드

`config/auth.php`의 `api` 가드에서 `passport` 드라이버를 사용합니다.

```php theme={null}
'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],
```

### 서비스 프로바이더 설정

`AppServiceProvider`의 `boot()`에서 스코프 정의와 토큰 유효 기간을 설정할 수 있습니다.

```php theme={null}
use Carbon\CarbonInterval;
use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::tokensCan([
        'orders:read' => '주문 참조',
        'orders:create' => '주문 생성',
    ]);

    Passport::defaultScopes(['orders:read']);

    Passport::tokensExpireIn(CarbonInterval::days(15));
    Passport::refreshTokensExpireIn(CarbonInterval::days(30));
    Passport::personalAccessTokensExpireIn(CarbonInterval::months(6));
}
```

## 클라이언트 관리

### 인가 코드 그랜트용 클라이언트

```shell theme={null}
php artisan passport:client
```

이 클라이언트는 사용자 동의 화면을 동반하는 OAuth2 표준 플로우에서 사용합니다.

### 클라이언트 크리덴셜 그랜트용 클라이언트

```shell theme={null}
php artisan passport:client --client
```

머신 간 통신 엔드포인트에서는 `EnsureClientIsResourceOwner` 미들웨어를 사용합니다.

```php theme={null}
use Laravel\Passport\Http\Middleware\EnsureClientIsResourceOwner;

Route::get('/orders', function () {
    // ...
})->middleware(EnsureClientIsResourceOwner::using('orders:read'));
```

## 토큰 관리

### 스코프 부여

```php theme={null}
$accessToken = $user->createToken(
    'dashboard-token',
    ['orders:read', 'orders:create']
)->accessToken;
```

### 스코프 체크

```php theme={null}
use Laravel\Passport\Http\Middleware\CheckToken;

Route::get('/orders', function () {
    // ...
})->middleware(['auth:api', CheckToken::using('orders:read')]);
```

### 실효

```php theme={null}
use Laravel\Passport\Passport;

$token = Passport::token()->find($tokenId);
$token?->revoke();
```

## API 라우트 보호

사용자 액세스 토큰으로 보호하는 API에는 `auth:api`를 붙입니다.

```php theme={null}
Route::middleware('auth:api')->group(function () {
    Route::get('/user', fn (Request $request) => $request->user());
    Route::get('/orders', [OrderController::class, 'index']);
});
```

<Warning>
  클라이언트 크리덴셜 그랜트 라우트는 `auth:api`가 아닌 `EnsureClientIsResourceOwner`를 사용해 주세요.
</Warning>

## Personal Access Token

OAuth2의 완전 플로우를 사용하지 않고, 사용자 자신이 API 토큰을 발행하는 용도에 적합합니다.

```shell theme={null}
php artisan passport:client --personal
```

```php theme={null}
$token = $request->user()->createToken('cli-token', ['orders:read'])->accessToken;
```

<Info>
  Personal Access Token이 주요 용도라면, Laravel 공식에서도 Sanctum을 검토할 것을 권장하고 있습니다.
</Info>

## 관련 링크

* [Laravel 공식 문서: Passport](https://laravel.com/docs/13.x/passport)
* [Laravel 공식 문서: Sanctum](https://laravel.com/docs/13.x/sanctum)


## Related topics

- [Laravel Sanctum (API 토큰 인증)](/ko/sanctum.md)
- [Socialite for Discord](/ko/packages/socialite-discord.md)
- [Socialite (LINE Login) - LINE SDK for Laravel](/ko/packages/laravel-line-sdk/socialite.md)
- [LINE SDK for Laravel](/ko/packages/laravel-line-sdk/index.md)
- [Laravel에서 MCP 서버 만들기](/ko/advanced/mcp-server.md)