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

# 패키지의 커스텀 UserProvider

> Laravel 패키지에서 인증 사용자의 저장소를 확장하고, UserProvider 계약·Auth::provider 등록·세션과 비밀번호 재해시를 안전하게 구현하는 방법을 설명합니다.

패키지가 사용자를 Laravel의 표준 Eloquent 모델이나 데이터베이스 이외의 곳에서 가져오는 경우에는 독자적인 `UserProvider`를 등록합니다. 예를 들어 외부 디렉터리, 기존 회원 시스템, 전용 API 등을 인증의 저장소로 사용할 수 있습니다.

이는 가드를 새로 만드는 확장과는 다릅니다. 기존 `session`이나 `token` 가드에 사용자를 검색·검증하는 구현만 제공합니다. 가드 자체의 인증 방식을 변경하려면 [커스텀 인증 가드 구현](https://kawax.biz/ko/advanced/custom-auth-guard.md)을 참고하세요.

> [!NOTE]
>
> 이 페이지는 Laravel 13을 대상으로, 공식 문서의 `13.x` 브랜치와 Framework `v13.43.0`의 구현을 참조합니다. 패키지가 지원하는 Laravel의 각 버전에서 계약의 메서드와 비밀번호 재해시 동작을 확인하세요.

## 가드와 UserProvider의 책임을 분리하기

`Auth::guard()`가 반환하는 가드는 세션이나 요청에서 인증 상태를 꺼냅니다. 가드가 사용자를 가져올 때는 설정된 프로바이더에 처리를 위임합니다.

```mermaid theme={null}
sequenceDiagram
    participant G as SessionGuard
    participant P as UserProvider
    participant S as 외부 사용자 저장소
    G->>P: retrieveById / retrieveByCredentials
    P->>S: 사용자 검색
    S-->>P: 저장 데이터
    P-->>G: Authenticatable 또는 null
    G->>P: validateCredentials
    P-->>G: true 또는 false
```

| 확장 대상 | 주요 책임 | 설정하는 위치 |
| - | - | - |
| Guard | 요청, 세션, 토큰에서 인증 상태를 관리한다 | `auth.guards` |
| UserProvider | 사용자 조회, 비밀번호 검증, remember token 갱신 | `auth.providers` |
| Authenticatable | 인증 ID, 비밀번호, remember token의 속성 이름을 공개한다 | 사용자 객체 |

`UserProvider`가 반환하는 값은 저장소의 배열이나 SDK의 응답이 아니라 `Illuminate\Contracts\Auth\Authenticatable`을 구현한 객체여야 합니다.

## 패키지에서 `Auth::provider` 등록하기

### 서비스 프로바이더의 `boot`에서 등록하기

Laravel은 `Auth::provider($name, $callback)`에 등록한 콜백을 `auth.providers.*.driver` 값에 따라 호출합니다. 콜백에는 애플리케이션과 프로바이더 설정이 전달됩니다.

패키지의 서비스 프로바이더에서는 인증 서비스가 사용되기 전에 등록합니다.

```php theme={null}
<?php

namespace Acme\Directory;

use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\ServiceProvider;

final class DirectoryServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Auth::provider('directory', function (
            Application $app,
            array $config,
        ): UserProvider {
            return new DirectoryUserProvider(
                $app->make(DirectoryClientManager::class)
                    ->connection($config['connection'] ?? 'default'),
                $app->make('hash'),
            );
        });
    }
}
```

`DirectoryClientManager`와 `DirectoryUserProvider`는 패키지가 컨테이너에 등록하는 클래스입니다. `$config`는 이용하는 애플리케이션의 `auth.php`에서 전달되므로, 연결 이름이나 테넌트 등 프로바이더 생성에 필요한 값을 여기서 읽을 수 있습니다.

`Auth::provider`는 인증 **사용자 프로바이더**의 이름을 등록합니다. `Auth::extend`가 등록하는 커스텀 가드의 드라이버와는 다른 확장 지점입니다. 둘 다 사용하는 경우에도 가드의 책임과 사용자 저장소의 책임을 별도 클래스로 유지합니다.

### `auth.php`에서 프로바이더와 가드 연결하기

등록한 이름을 `auth.providers`의 `driver`에 지정하고, 그 프로바이더를 가드에서 참조합니다.

```php theme={null}
// config/auth.php
return [
    'defaults' => [
        'guard' => 'directory-web',
        'passwords' => 'users',
    ],

    'guards' => [
        'directory-web' => [
            'driver' => 'session',
            'provider' => 'directory-users',
        ],
    ],

    'providers' => [
        'directory-users' => [
            'driver' => 'directory',
            'connection' => 'primary-directory',
        ],
    ],
];
```

이 설정의 대응 관계는 다음과 같습니다.

1. `directory-web` 가드가 `directory-users` 프로바이더를 참조한다.
2. `directory-users`의 `driver`가 `directory`이므로 앞의 콜백이 선택된다.
3. `SessionGuard`가 생성되고, 생성된 `UserProvider`를 사용해 사용자를 가져온다.

`AuthManager`는 가드를 처음 해결할 때 캐시합니다. 프로바이더 등록 후 이미 해결된 가드를 교체하는 API는 없으므로, 서비스 프로바이더의 부팅 순서와 테스트에서의 `Auth::forgetGuards()` 사용에 유의합니다. `auth` 설정을 캐시해서 사용하는 경우에도 연결 정보를 환경 변수에서 직접 읽지 말고, 설정으로 해결한 뒤 콜백에 전달하세요.

## `UserProvider` 계약 구현하기

Laravel 13의 `Illuminate\Contracts\Auth\UserProvider`는 다음 6개의 메서드를 요구합니다.

```php theme={null}
interface UserProvider
{
    public function retrieveById($identifier);
    public function retrieveByToken($identifier, $token);
    public function updateRememberToken(Authenticatable $user, $token);
    public function retrieveByCredentials(array $credentials);
    public function validateCredentials(Authenticatable $user, array $credentials);
    public function rehashPasswordIfRequired(
        Authenticatable $user,
        array $credentials,
        bool $force = false,
    );
}
```

조회 계열 3개 메서드는 사용자 또는 `null`을 반환하며, 찾을 수 없는 사용자를 예외로 나타내지 않습니다. 저장소의 타임아웃이나 통신 장애를 `null`로 변환할지, 재시도 가능한 예외로 다룰지는 패키지의 계약으로 정합니다. 인증 실패와 저장소 장애를 같은 "자격 증명이 올바르지 않음"으로 숨기지 않는 것이 중요합니다.

### `Authenticatable` 반환하기

외부 저장소의 레코드를 그대로 반환하지 않고 `GenericUser`로 변환하는 최소 예입니다. 실제 패키지에서는 이용자가 추가 속성에 타입 있게 접근할 수 있는 전용 사용자 클래스를 준비해도 됩니다.

```php theme={null}
use Illuminate\Auth\GenericUser;
use Illuminate\Contracts\Auth\Authenticatable;

private function makeUser(?array $record): ?Authenticatable
{
    if ($record === null) {
        return null;
    }

    // id, password, remember_token 을 포함하는 레코드를 가정한다.
    return new GenericUser($record);
}
```

`GenericUser`는 `id`, `password`, `remember_token`이라는 속성 이름을 기본값으로 사용합니다. 다른 이름을 사용하는 경우에는 `Authenticatable`을 구현하는 전용 클래스에서 `getAuthIdentifierName()` 등을 오버라이드합니다.

### ID와 remember token으로 가져오기

`retrieveById`는 세션에 저장된 인증 ID로부터 사용자를 복원합니다. remember token에 의한 로그인을 지원하는 경우에는 식별자와 토큰을 저장소에서 대조합니다.

```php theme={null}
public function retrieveById($identifier): ?Authenticatable
{
    return $this->makeUser($this->client->find($identifier));
}

public function retrieveByToken(
    $identifier,
    #[\SensitiveParameter] $token,
): ?Authenticatable {
    $record = $this->client->find($identifier);
    $rememberToken = $record['remember_token'] ?? null;

    if (! is_string($rememberToken) || ! hash_equals($rememberToken, $token)) {
        return null;
    }

    return $this->makeUser($record);
}

public function updateRememberToken(
    Authenticatable $user,
    #[\SensitiveParameter] $token,
): void {
    $this->client->updateRememberToken(
        $user->getAuthIdentifier(),
        $token,
    );
}
```

`hash_equals`의 인수를 저장소에서 가져온 문자열과 토큰으로 한정하고, 토큰을 로그에 출력하지 않도록 합니다. 외부 저장소가 remember token을 지원하지 않는 경우에는 `updateRememberToken`을 빈 구현으로 두어 성공한 것처럼 보이게 하지 말고, 패키지의 인증 설정에서 remember 기능을 사용할 수 없음을 명시하세요.

## 자격 증명 검색과 비밀번호 검증 분리하기

### `retrieveByCredentials`에서는 비밀번호를 검증하지 않기

`Auth::attempt()`는 먼저 `retrieveByCredentials`로 사용자를 찾고, 그 후 `validateCredentials`로 비밀번호를 검증합니다. 검색 메서드에서 비밀번호 비교까지 하면 가드가 상정하는 처리 순서와 비밀번호 재해시가 깨집니다.

```php theme={null}
use Illuminate\Contracts\Auth\Authenticatable;

public function retrieveByCredentials(
    #[\SensitiveParameter] array $credentials,
): ?Authenticatable {
    $criteria = array_filter(
        $credentials,
        fn (string $key): bool => ! str_contains($key, 'password'),
        ARRAY_FILTER_USE_KEY,
    );

    if ($criteria === []) {
        return null;
    }

    return $this->makeUser($this->client->findBy($criteria));
}
```

`password`뿐만 아니라 `password_confirmation` 등의 키도 저장소의 검색 조건에서 제외합니다. 비밀번호나 액세스 토큰을 검색 API의 쿼리·로그·캐시 키에 포함하지 않도록 하세요. 검색 조건으로 받는 키를 `email` 등의 허용 목록으로 제한하는 설계도 외부 API에 임의의 필드를 넘기지 않기 위해 효과적입니다.

### `validateCredentials`에서 Hash 비교하기

검증에는 애플리케이션의 `Hasher`를 사용하고, 평문 비밀번호를 저장소로 전송하거나 로그에 출력하지 않습니다.

```php theme={null}
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Contracts\Hashing\Hasher;

public function validateCredentials(
    Authenticatable $user,
    #[\SensitiveParameter] array $credentials,
): bool {
    $plain = $credentials['password'] ?? null;
    $hashed = $user->getAuthPassword();

    if (! is_string($plain) || ! is_string($hashed)) {
        return false;
    }

    return $this->hasher->check($plain, $hashed);
}
```

`$credentials['password']`가 없는 경우나 사용자가 비밀번호를 가지고 있지 않은 경우에는 `false`를 반환합니다. 외부 인증 API에 검증을 위임하는 설계에서는 같은 계약을 지키면서 실패·타임아웃·레이트 리밋을 패키지의 예외 방침에 따라 다룹니다.

## 비밀번호 재해시 유지하기

Laravel은 로그인 성공 후 설정된 해시 방식에 대해 재해시가 필요한지 확인할 수 있습니다. 커스텀 프로바이더는 `rehashPasswordIfRequired`를 구현하고, 필요할 때만 저장소의 해시를 갱신합니다.

```php theme={null}
public function rehashPasswordIfRequired(
    Authenticatable $user,
    #[\SensitiveParameter] array $credentials,
    bool $force = false,
): void {
    $plain = $credentials['password'] ?? null;
    $currentHash = $user->getAuthPassword();

    if (! is_string($plain) || ! is_string($currentHash)) {
        return;
    }

    if (! $force && ! $this->hasher->needsRehash($currentHash)) {
        return;
    }

    $this->client->updatePassword(
        $user->getAuthIdentifier(),
        $this->hasher->make($plain),
    );
}
```

외부 저장소에 갱신을 수행하므로 재해시 실패를 무시하지 마세요. 갱신 후 반환하는 사용자 객체의 비밀번호 속성이 오래된 상태로 남으면 다음 인증에서 재해시가 반복될 수 있습니다. 사용하는 `Hasher`와 저장소의 비밀번호 형식이 일치하는 것도 패키지의 요구 사항으로 명시합니다.

## 서비스 프로바이더와 인증 흐름 테스트하기

패키지 테스트에서는 저장소 클라이언트를 fake로 교체하고, `UserProvider`의 각 책임을 개별적으로 검증합니다. 특히 다음 3가지를 나누어 확인합니다.

* `retrieveByCredentials`가 비밀번호를 클라이언트에 전달하지 않는다.
* 올바른 해시만 `validateCredentials`를 통과한다.
* 재해시가 필요한 경우에만 갱신 API를 호출한다.

```php theme={null}
public function test_credentials_lookup_does_not_send_password(): void
{
    $this->client->expects('findBy')
        ->with(['email' => 'user@example.com'])
        ->andReturn([
            'id' => 'user-1',
            'password' => $this->hasher->make('secret'),
            'remember_token' => null,
        ]);

    $user = $this->provider->retrieveByCredentials([
        'email' => 'user@example.com',
        'password' => 'secret',
    ]);

    $this->assertSame('user-1', $user?->getAuthIdentifier());
}
```

위의 `expects`는 사용하는 mock 라이브러리의 API에 맞게 바꿔 주세요. 실제 HTTP 클라이언트를 사용하는 경우에는 HTTP fake로 전송 내용을 확인하고, 평문 비밀번호가 요청이나 로그에 나타나지 않는 것을 테스트합니다.

`Auth::provider` 등록을 포함한 통합 테스트에서는 Testbench 등으로 다음 순서를 검증합니다.

1. 패키지의 서비스 프로바이더를 로드한다.
2. `auth.providers`에 커스텀 `driver`를 설정한다.
3. `auth.guards`에서 그 프로바이더를 참조한다.
4. 가드를 처음 해결하고, 사용자 조회가 fake 클라이언트에 위임되는 것을 확인한다.
5. 설정이나 등록을 변경하는 테스트에서는 다음 케이스로 넘어가기 전에 `Auth::forgetGuards()`를 호출한다.

## 업데이트 시의 호환성 설계하기

`UserProvider`는 인증의 경계에 있으므로 패키지 업데이트 시에는 다음을 확인합니다.

* `Authenticatable`의 ID·비밀번호·remember token 속성 이름을 바꾸는 경우, 기존 세션과 remember cookie의 처리를 정한다.
* 외부 저장소의 ID 형식이나 비밀번호 해시 방식을 바꾸는 경우, 기존 사용자를 복원해 로그인할 수 있는지 확인한다.
* `retrieveByCredentials`의 허용 키를 좁히는 경우, 이용자가 `Auth::attempt`에 전달하던 조건과의 호환성을 확인한다.
* 저장소 장애를 인증 실패와 구별하고, 로그인 화면에서 잘못된 비밀번호를 다시 입력하게 하지 않는 방침을 정한다.
* provider 이름, `auth.php`의 설정 키, 연결 설정을 삭제하기 전에 설정 캐시와 배포 절차를 확인한다.

패키지는 "어느 저장소에서 무엇을 사용자로 반환하는가"와 "비밀번호를 어떤 해시로 관리하는가"를 공개 계약으로 다루고, 인증 정보의 취급을 애플리케이션에 지나치게 맡기지 않도록 합니다.

## 관련 페이지

> [card] [커스텀 인증 가드 구현](https://kawax.biz/ko/advanced/custom-auth-guard.md)
>
> 가드 자체를 확장하고, 세션이나 API 토큰에서 사용자를 해결하는 방법을 확인합니다.

> [card] [서비스 프로바이더](https://kawax.biz/ko/service-providers.md)
>
> 패키지의 서비스 프로바이더를 등록하고, 부팅 시 확장을 적용하는 기본을 확인합니다.

## 참조한 1차 정보

* [Laravel 공식 문서: Adding Custom User Providers](https://github.com/laravel/docs/blob/13.x/authentication.md#adding-custom-user-providers)
* [Laravel 공식 문서: User Provider Contract](https://github.com/laravel/docs/blob/13.x/authentication.md#the-user-provider-contract)
* [AuthManager: provider()와 가드 해결](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/AuthManager.php)
* [CreatesUserProviders: 커스텀 프로바이더 생성](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/CreatesUserProviders.php)
* [UserProvider contract](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Contracts/Auth/UserProvider.php)
* [Authenticatable contract](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Contracts/Auth/Authenticatable.php)
* [EloquentUserProvider: 기본 구현](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/EloquentUserProvider.php)
* [GenericUser: 속성으로 만드는 Authenticatable](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/GenericUser.php)


## Related topics

- [고급 주제](https://kawax.biz/ko/advanced/index.md)
- [패키지의 커스텀 캐시 스토어와 계약](https://kawax.biz/ko/advanced/package-cache-drivers.md)
- [패키지의 커스텀 세션 드라이버](https://kawax.biz/ko/advanced/package-session-drivers.md)
- [패키지의 커스텀 알림 채널과 전송 검증](https://kawax.biz/ko/advanced/package-notification-channels.md)
- [커스텀 인증 가드 구현](https://kawax.biz/ko/advanced/custom-auth-guard.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.