본문 바로가기
← 패키지 목록

Apple

인증된 제출자

socialiteproviders/apple

제출자 이우진
최신 v6.1.0라이센스 MIT배포 2026년 10월 23일
인증

Laravel Socialite용 Apple OAuth2 프로바이더

Apple

composer require socialiteproviders/apple

설치 및 기본 사용법

먼저 기본 설치 가이드를 확인한 다음, 아래의 프로바이더별 안내를 따라 주세요.

config/services.php에 설정 추가

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

자세한 내용은 Configure Apple ID Authentication을 참고하세요.

Note: "Sign In with Apple"에서 사용하는 클라이언트 시크릿은 최대 유효 기간이 6개월인 JWT 토큰입니다. 위 글에서 클라이언트 시크릿을 필요할 때 생성하는 방법을 설명하고 있으며, 이 값은 6개월마다 갱신해야 합니다. 요청마다 클라이언트 시크릿을 생성하려면 Generating A Client Secret For Sign In With Apple On Each Request를 참고하세요.

시크릿 토큰이 없거나 직접 만들고 싶지 않다면 프라이빗 키를 사용할 수 있습니다(공식 문서 참고). 다음과 같이 설정을 추가하세요.

'apple' => [ 'client_id' => env('APPLE_CLIENT_ID'), // Required. Bundle ID from Identifier in Apple Developer. 'client_secret' => env('APPLE_CLIENT_SECRET'), // Empty. We create it from private key. 'key_id' => env('APPLE_KEY_ID'), // Required. Key ID from Keys in Apple Developer. 'team_id' => env('APPLE_TEAM_ID'), // Required. App ID Prefix from Identifier in Apple Developer. 'private_key' => env('APPLE_PRIVATE_KEY'), // Required. Must be absolute path, e.g. /var/www/cert/AuthKey_XYZ.p8 'passphrase' => env('APPLE_PASSPHRASE'), // Optional. Set if your private key have a passphrase. 'signer' => env('APPLE_SIGNER'), // Optional. Signer used for Configuration::forSymmetricSigner(). Default: \Lcobucci\JWT\Signer\Ecdsa\Sha256 'redirect' => env('APPLE_REDIRECT_URI'), // Required. 'jwt_issued_time_leeway' => env('APPLE_JWT_ISSUED_TIME_LEEWAY'), // Optional. Set this to add a leeway to your JWT issued_time value. See section below ],

400 Bad Request {"error":"invalid_client"} 오류가 발생한다면 다른 Signer(비대칭 알고리즘)를 사용해 보세요. 자세한 내용은 Asymmetric algorithms를 참고하세요.

프로바이더 이벤트 리스너 추가

Laravel 11 이상

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

  • 참고: 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 => [ // ... other providers \SocialiteProviders\Apple\AppleExtendSocialite::class.'@handle', ], ];

사용법

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

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

콜백의 state와 nonce

Apple은 콜백을 리다이렉트 URL로 크로스 사이트 POST 방식으로 전송합니다 (response_mode=form_post이며, 스코프를 요청하면 Apple이 이 방식을 요구합니다). 콜백에서 프로바이더는 state를 세션과 비교하고, 아이덴티티 토큰의 nonce를 리다이렉트 시 발급한 값과 비교합니다. 따라서 애플리케이션이 시작하지 않은 콜백은 InvalidStateException과 함께 거부됩니다.

두 검증 모두 이 POST 요청에 세션 쿠키가 함께 도착해야 합니다. Laravel의 기본값인 SameSite=lax 쿠키는 크로스 사이트 POST에서는 전송되지 않으므로, 기본 설치 상태에서는 세션이 비어 있는 것으로 보여 모든 콜백이 거부됩니다. 쿠키가 사이트 경계를 넘을 수 있도록 설정해야 합니다.

SESSION_SAME_SITE=none SESSION_SECURE_COOKIE=true

SameSite=none은 Apple 관련 쿠키뿐 아니라 애플리케이션이 설정하는 모든 쿠키에 적용되어 보호 수준이 낮아집니다. 다른 곳에서는 lax를 유지하고 싶다면, 아래에서 설명하는 cookieNonce()로 스테이트리스 방식의 플로우를 사용하세요.

세션 없이 사용하기 (스테이트리스)

콜백에서 세션을 유지할 수 없다면 cookieNonce()와 함께 스테이트리스 플로우를 사용하세요. nonce는 프로바이더가 처리해 줍니다.

// Redirect. The provider generates the nonce, sends it to Apple, and sets it // on the browser in an encrypted cookie. return Socialite::driver('apple')->stateless()->cookieNonce()->redirect(); // Callback. The provider reads the nonce back from the cookie and verifies it // against the identity token. $user = Socialite::driver('apple')->stateless()->cookieNonce()->user();

nonce는 socialite_apple_nonce 쿠키(Secure, HttpOnly, SameSite=none)에 담겨 전달되며, APP_KEY로 암호화되므로 클라이언트가 위조할 수 없습니다. 로그인을 시작한 브라우저만 이 쿠키를 가지고 있으므로 RFC 9700 2.1절이 요구하는 대로 플로우가 해당 브라우저에 묶입니다. 다른 브라우저에서 가로챈 콜백을 재전송하면 쿠키가 없어 거부되며, 변조된 쿠키도 마찬가지로 거부됩니다. 세션, 캐시, 서버 측 상태는 전혀 사용하지 않습니다.

이 쿠키는 SameSite=none이므로 HTTPS가 필요합니다. 콜백이 TLS로 제공되지 않으면 브라우저가 쿠키를 버립니다. 모든 세션 쿠키를 완화하는 대신 이 목적 전용 쿠키 하나만 사용하므로, 애플리케이션의 나머지 부분에는 lax가 그대로 적용됩니다.

nonce_ttl(초 단위, 기본값 600)을 설정하면 쿠키, 즉 로그인 시도의 유효 시간을 바꿀 수 있습니다.

'apple' => [ // ... 'nonce_ttl' => env('APPLE_NONCE_TTL', 600), ],

nonce를 직접 관리하고 싶다면 setNonce()에 직접 생성한 값을 전달하세요. 이 값을 Apple에 보내고 돌려받아 사용합니다. 둘 중 어느 쪽도 없이 stateless()만 호출하면, 보호되지 않은 콜백을 그대로 받아들이는 대신 InvalidStateException이 발생합니다.

이미 아이덴티티 토큰을 전달해 주는 네이티브 iOS·Android 클라이언트에는 아래의 userByIdentityToken()을 사용하세요.

네이티브 앱 (아이덴티티 토큰)

네이티브 iOS·Android 클라이언트는 아이덴티티 토큰을 서버로 직접 전달합니다. Apple이 요구하는 대로 검증하려면 인증 요청에 사용한 nonce를 함께 전달하세요.

$user = Socialite::driver('apple')->userByIdentityToken($identityToken, $nonce);

nonce는 하위 호환성을 위해 선택 사항이지만, 생략하면 토큰이 만료될 때까지 재전송 공격에 노출될 수 있습니다.

Apple은 토큰을 요청한 클라이언트 기준으로 아이덴티티 토큰을 발급하므로, 여러 클라이언트를 처리하는 하나의 API는 여러 audience를 보게 됩니다.

클라이언트aud
웹, Android (Sign in with Apple JS / REST)Services ID
네이티브 iOS, macOS해당 앱의 App ID(번들 ID)

client_id는 웹 플로우에 필요한 Services ID로 유지하고, 나머지는 audiences에 나열하세요.

'apple' => [ // ... 'audiences' => ['com.example.app', 'com.example.app.macos'], ],

userByIdentityToken()과 userFromToken()은 client_id 또는 audiences 중 하나를 대상으로 발급된 토큰을 허용합니다. 웹 콜백은 client_id만 허용합니다.

반환되는 사용자 필드

  • id
  • name
  • email

name은 서명된 아이덴티티 토큰이 아니라 콜백 POST의 user 필드에서 가져오며, Apple은 최초 인증 때만 이 값을 보냅니다. 사용자 입력으로 취급하여 저장하기 전에 검증하고 정제하세요.

알려진 이슈

JWT Issued_at

시간 불일치로 인해 플러그인이 예외를 던지는 경우가 있습니다. 자세한 내용은 #1354를 참고하세요. config('services.apple.jwt_issued_time_leeway')를 사용해 시간을 '되돌릴' 수 있으며, 기본값은 3초(PT3S)입니다.

가능한 값의 예: PT3S -> 3초, PT1M -> 1분 등

발생하는 예외는 다음과 같은 모습입니다.

[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]

잘못된 audience

아이덴티티 토큰의 aud 클레임은 config('services.apple.client_id') 또는 config('services.apple.audiences') 중 하나와 일치해야 합니다. 네이티브 앱은 웹 플로우에서 사용하는 Services ID가 아니라 번들 ID를 audience로 전송합니다. 자세한 내용은 네이티브 앱을 참고하세요.

발생하는 예외는 다음과 같습니다.

Laravel\Socialite\Two\InvalidStateException: The token violates some mandatory constraints, details:
- The token is not allowed to be used by this audience

참고 자료