메인 콘텐츠로 건너뛰기
패키지가 사용자를 Laravel의 표준 Eloquent 모델이나 데이터베이스 이외의 곳에서 가져오는 경우에는 독자적인 UserProvider를 등록합니다. 예를 들어 외부 디렉터리, 기존 회원 시스템, 전용 API 등을 인증의 저장소로 사용할 수 있습니다. 이는 가드를 새로 만드는 확장과는 다릅니다. 기존 session이나 token 가드에 사용자를 검색·검증하는 구현만 제공합니다. 가드 자체의 인증 방식을 변경하려면 커스텀 인증 가드 구현을 참고하세요.
이 페이지는 Laravel 13을 대상으로, 공식 문서의 13.x 브랜치와 Framework v13.43.0의 구현을 참조합니다. 패키지가 지원하는 Laravel의 각 버전에서 계약의 메서드와 비밀번호 재해시 동작을 확인하세요.

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

Auth::guard()가 반환하는 가드는 세션이나 요청에서 인증 상태를 꺼냅니다. 가드가 사용자를 가져올 때는 설정된 프로바이더에 처리를 위임합니다. UserProvider가 반환하는 값은 저장소의 배열이나 SDK의 응답이 아니라 Illuminate\Contracts\Auth\Authenticatable을 구현한 객체여야 합니다.

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

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

Laravel은 Auth::provider($name, $callback)에 등록한 콜백을 auth.providers.*.driver 값에 따라 호출합니다. 콜백에는 애플리케이션과 프로바이더 설정이 전달됩니다. 패키지의 서비스 프로바이더에서는 인증 서비스가 사용되기 전에 등록합니다.
DirectoryClientManager와 DirectoryUserProvider는 패키지가 컨테이너에 등록하는 클래스입니다. $config는 이용하는 애플리케이션의 auth.php에서 전달되므로, 연결 이름이나 테넌트 등 프로바이더 생성에 필요한 값을 여기서 읽을 수 있습니다. Auth::provider는 인증 사용자 프로바이더의 이름을 등록합니다. Auth::extend가 등록하는 커스텀 가드의 드라이버와는 다른 확장 지점입니다. 둘 다 사용하는 경우에도 가드의 책임과 사용자 저장소의 책임을 별도 클래스로 유지합니다.

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

등록한 이름을 auth.providers의 driver에 지정하고, 그 프로바이더를 가드에서 참조합니다.
이 설정의 대응 관계는 다음과 같습니다.
  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개의 메서드를 요구합니다.
조회 계열 3개 메서드는 사용자 또는 null을 반환하며, 찾을 수 없는 사용자를 예외로 나타내지 않습니다. 저장소의 타임아웃이나 통신 장애를 null로 변환할지, 재시도 가능한 예외로 다룰지는 패키지의 계약으로 정합니다. 인증 실패와 저장소 장애를 같은 “자격 증명이 올바르지 않음”으로 숨기지 않는 것이 중요합니다.

Authenticatable 반환하기

외부 저장소의 레코드를 그대로 반환하지 않고 GenericUser로 변환하는 최소 예입니다. 실제 패키지에서는 이용자가 추가 속성에 타입 있게 접근할 수 있는 전용 사용자 클래스를 준비해도 됩니다.
GenericUser는 id, password, remember_token이라는 속성 이름을 기본값으로 사용합니다. 다른 이름을 사용하는 경우에는 Authenticatable을 구현하는 전용 클래스에서 getAuthIdentifierName() 등을 오버라이드합니다.

ID와 remember token으로 가져오기

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

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

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

Auth::attempt()는 먼저 retrieveByCredentials로 사용자를 찾고, 그 후 validateCredentials로 비밀번호를 검증합니다. 검색 메서드에서 비밀번호 비교까지 하면 가드가 상정하는 처리 순서와 비밀번호 재해시가 깨집니다.
password뿐만 아니라 password_confirmation 등의 키도 저장소의 검색 조건에서 제외합니다. 비밀번호나 액세스 토큰을 검색 API의 쿼리·로그·캐시 키에 포함하지 않도록 하세요. 검색 조건으로 받는 키를 email 등의 허용 목록으로 제한하는 설계도 외부 API에 임의의 필드를 넘기지 않기 위해 효과적입니다.

validateCredentials에서 Hash 비교하기

검증에는 애플리케이션의 Hasher를 사용하고, 평문 비밀번호를 저장소로 전송하거나 로그에 출력하지 않습니다.
$credentials['password']가 없는 경우나 사용자가 비밀번호를 가지고 있지 않은 경우에는 false를 반환합니다. 외부 인증 API에 검증을 위임하는 설계에서는 같은 계약을 지키면서 실패·타임아웃·레이트 리밋을 패키지의 예외 방침에 따라 다룹니다.

비밀번호 재해시 유지하기

Laravel은 로그인 성공 후 설정된 해시 방식에 대해 재해시가 필요한지 확인할 수 있습니다. 커스텀 프로바이더는 rehashPasswordIfRequired를 구현하고, 필요할 때만 저장소의 해시를 갱신합니다.
외부 저장소에 갱신을 수행하므로 재해시 실패를 무시하지 마세요. 갱신 후 반환하는 사용자 객체의 비밀번호 속성이 오래된 상태로 남으면 다음 인증에서 재해시가 반복될 수 있습니다. 사용하는 Hasher와 저장소의 비밀번호 형식이 일치하는 것도 패키지의 요구 사항으로 명시합니다.

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

패키지 테스트에서는 저장소 클라이언트를 fake로 교체하고, UserProvider의 각 책임을 개별적으로 검증합니다. 특히 다음 3가지를 나누어 확인합니다.
  • retrieveByCredentials가 비밀번호를 클라이언트에 전달하지 않는다.
  • 올바른 해시만 validateCredentials를 통과한다.
  • 재해시가 필요한 경우에만 갱신 API를 호출한다.
위의 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의 설정 키, 연결 설정을 삭제하기 전에 설정 캐시와 배포 절차를 확인한다.
패키지는 “어느 저장소에서 무엇을 사용자로 반환하는가”와 “비밀번호를 어떤 해시로 관리하는가”를 공개 계약으로 다루고, 인증 정보의 취급을 애플리케이션에 지나치게 맡기지 않도록 합니다.

관련 페이지

커스텀 인증 가드 구현

가드 자체를 확장하고, 세션이나 API 토큰에서 사용자를 해결하는 방법을 확인합니다.

서비스 프로바이더

패키지의 서비스 프로바이더를 등록하고, 부팅 시 확장을 적용하는 기본을 확인합니다.

참조한 1차 정보

마지막 수정일 2026년 11월 17일