Apple

인증된 제출자

socialiteproviders/apple

제출자 이우진

최신 v5.10.0라이센스 MIT배포 2026년 7월 6일

인증

Laravel Socialite용 Apple OAuth2 프로바이더

GitHub

Apple 소셜 로그인

composer require socialiteproviders/apple

설치 및 기본 사용법

먼저 기본 설치 가이드를 참고한 뒤, 아래 Apple 프로바이더 전용 설정을 진행하세요.

`config/services.php`에 설정 추가

'apple' => [
  'client_id' => env('APPLE_CLIENT_ID'),
  'client_secret' => env('APPLE_CLIENT_SECRET'),
  'redirect' => env('APPLE_REDIRECT_URI')
],

Apple ID 인증 설정 방법은 Configure Apple ID Authentication 문서를 참고하세요.

NOTE

"Sign In with Apple"에서 사용하는 client_secret은 JWT 토큰으로, 최대 유효 기간이 6개월입니다. 위 문서에서 client secret을 수동으로 생성하는 방법을 설명하며, 6개월마다 갱신해야 합니다. 요청마다 자동으로 client secret을 생성하려면 Generating A Client Secret For Sign In With Apple On Each Request를 참고하세요.

수동으로 secret 토큰을 관리하고 싶지 않다면, 프라이빗 키를 사용하는 방식을 권장합니다(Apple 공식 문서 참고). 이 경우 설정을 다음과 같이 확장하세요:

'apple' => [
  'client_id' => env('APPLE_CLIENT_ID'), // 필수. Apple Developer의 Identifier에서 확인하는 Bundle ID
  'client_secret' => env('APPLE_CLIENT_SECRET'), // 비워둠. 프라이빗 키로 자동 생성됨
  'key_id' => env('APPLE_KEY_ID'), // 필수. Apple Developer의 Keys에서 확인하는 Key ID
  'team_id' => env('APPLE_TEAM_ID'), // 필수. Apple Developer의 Identifier에서 확인하는 App ID Prefix
  'private_key' => env('APPLE_PRIVATE_KEY'), // 필수. 절대 경로 사용, 예: /var/www/cert/AuthKey_XYZ.p8
  'passphrase' => env('APPLE_PASSPHRASE'), // 선택. 프라이빗 키에 패스프레이즈가 있는 경우 설정
  'signer' => env('APPLE_SIGNER'), // 선택. Configuration::forSymmetricSigner()에 사용할 서명자. 기본값: \Lcobucci\JWT\Signer\Ecdsa\Sha256
  'redirect' => env('APPLE_REDIRECT_URI'), // 필수.

  'jwt_issued_time_leeway' => env('APPLE_JWT_ISSUED_TIME_LEEWAY'), // 선택. JWT issued_time에 여유 시간을 추가할 때 사용. 아래 섹션 참고
],

400 Bad Request {"error":"invalid_client"} 오류가 발생한다면, 다른 서명자(비대칭 알고리즘)를 사용하는 것이 해결책이 될 수 있습니다. Asymmetric algorithms를 참고하세요.

프로바이더 이벤트 리스너 등록

Laravel 11 이상

Laravel 11부터는 기본 EventServiceProvider가 제거되었습니다. 대신 AppServiceProvider의 boot 메서드에서 Event 파사드의 listen 메서드를 사용해 리스너를 등록하세요.

NOTE

기본 제공되는 Socialite 프로바이더는 별도로 추가할 필요가 없습니다. 직접 구현한 커스텀 프로바이더로 재정의하는 경우에만 등록이 필요합니다.

Event::listen(function (\SocialiteProviders\Manager\SocialiteWasCalled $event) {
    $event->extendSocialite('apple', \SocialiteProviders\Apple\Provider::class);
});

Laravel 10 이하

SocialiteWasCalled 이벤트를 감지하도록 패키지의 리스너를 설정해야 합니다.

app/Providers/EventServiceProvider의 listen[] 배열에 이벤트를 추가하세요. 자세한 내용은 기본 설치 가이드를 참고하세요.

protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        // ... 다른 프로바이더
        \SocialiteProviders\Apple\AppleExtendSocialite::class.'@handle',
    ],
];

사용법

설정이 완료되면 일반적인 Socialite 사용 방식과 동일하게 Apple 프로바이더를 사용할 수 있습니다(Socialite 파사드가 설치되어 있다고 가정):

return Socialite::driver('apple')->redirect();

반환되는 사용자 필드

id
name
email

알려진 문제

JWT issued_at 시간 불일치

서버 간 시간 차이로 인해 플러그인이 예외를 던질 수 있습니다(#1354 참고). config('services.apple.jwt_issued_time_leeway') 설정으로 시간 여유값을 지정하면 이 문제를 완화할 수 있습니다. 기본값은 3초(PT3S)입니다.

설정 가능한 값의 예시: PT3S → 3초, PT1M → 1분 등 (ISO 8601 기간 형식 사용)

발생하는 예외는 다음과 같은 형태입니다:

[object] (Laravel\\Socialite\\Two\\InvalidStateException(code: 0): The token violates some mandatory constraints, details:                                                                                           - The token was issued in the future at /vendor/socialiteproviders/apple/Provider.php:207)                      [stacktrace]

참고 자료

Apple API 공식 문서