이제 정식 출시(generally available)되었습니다.Vercel Passport

Passport를 사용하면 자체 ID 제공자(identity provider)를 통해 Vercel 배포(deployments)를 보호할 수 있습니다. 방문자는 보호된 배포를 보기 전에 Okta, Microsoft Entra ID 또는 모든 OIDC 제공자를 통해 인증하며, Vercel은 서명된 ID 토큰(identity token)을 배포로 전달하여 애플리케이션 코드가 방문자가 누구인지에 기반하여 동작할 수 있도록 합니다.

@vercel/passport의 getIdentity() 헬퍼는 Vercel 요청 컨텍스트(request context)를 읽고 인증된 방문자를 반환합니다. Vercel은 Passport가 세션을 검증한 후, 헤더에서 클라이언트가 제공한 값을 제거하고 검증된 토큰을 주입하므로, 코드가 받는 ID는 이미 검증된 상태입니다. getIdentity() x-vercel-oidc-passport-token

externalSubject 필드는 방문자에 대한 안정적인 식별자(stable identifier)로, 귀하의 팀과 Passport를 ID 제공자에 연결하는 애플리케이션으로 범위가 제한되며, 제공자 자체에서의 방문자 ID입니다. 인증되지 않은 브라우저 방문자는 코드가 실행되기 전에 ID 제공자로 리디렉션되기 때문에, getIdentity() 헬퍼는 Passport 세션 없이 요청이 도착할 때만 null을 반환합니다. subject [Vercel Connect](https://vercel.com/docs/connect)

로컬 개발 시에는 구성 가능한 development identity를 반환하므로, 실제 ID 제공자 없이도 동일한 코드 경로가 작동합니다. getIdentity()

서명된 Passport 토큰은 이제 그룹 멤버십(group membership)과 같이 제공자의 추가적인 ID 클레임(identity claims)을 포함할 수 있습니다. 스코프(scope)를 요청하고 Passport가 사용하는 Vercel Connect 애플리케이션에서 해당 클레임을 허용 목록(allowlist)에 추가한 다음, ID 페이로드(identity payload)에서 이를 읽으세요: groups

이 문서는 전체 Okta 단계별 안내를 포함한 제공자 설정을 다룹니다. additional identity scopes documentation

애플리케이션에서 다른 백엔드로 Passport 토큰을 Bearer 토큰으로 전달하고, 1.0.0 버전부터 사용 가능한 @vercel/passport 라이브러리의 verifyIdentity()를 사용하여 해당 토큰을 검증할 수 있습니다. 이 헬퍼 함수는 토큰 서명(signature), Passport 클레임(claims), 그리고 토큰이 예상된 프로젝트 및 환경에서 왔는지 여부를 확인합니다.

JavaScript 외부의 서비스들은 공개된 JWKS를 사용하여 표준 JWT로서 토큰을 검증할 수 있습니다. 자세한 내용은 인증 검증(verify identity) 문서를 참조하세요.

Passport 인증에 성공할 때마다 passport-access-granted 이벤트가 Activity Log와 Audit Logs 모두에 기록되어, 방문자를 식별하고 보호된 호스트네임(hostname)과 프로젝트를 기록합니다. Activity Log 뷰는 이미 Passport 액세스에 맞춰 필터링되어 있습니다.

x-vercel-protection-bypass는 이제 Passport에도 적용됩니다. 헤더나 쿼리 파라미터에 이미 바이패스 비밀값(bypass secret)을 보내는 웹훅(Webhooks), 크론 잡(cron jobs), CI 실행은 Passport를 활성화하더라도 그대로 작동합니다. Passport는 배포된 라우트 및 프록시 함수(proxy functions)보다 앞서 Vercel 네트워크에서 실행되기 때문에, 비밀값은 자체 미들웨어(middleware)에 의해 추가되는 것이 아니라 원래의 요청(original request)에 포함되어 있어야 합니다. 바이패스된 요청에는 로그인된 방문자가 없으므로 getIdentity()는 null을 반환합니다. 자동화를 위한 보호 바이패스(Protection Bypass for Automation)

Trusted Sources는 공유 비밀값 없이도 동일한 바이패스를 제공합니다. 보호된 배포(Protected deployments)는 Vercel 프로젝트 및 사용자가 승인한 외부 서비스로부터 수명이 짧은 OIDC 토큰을 수락하며, 이를 통해 Slack에서 트리거되는 워크플로우가 Passport로 보호된 배포에 도달할 수 있습니다. eve

Passport는 이제 custom environments (staging, qa)를 지원하므로, 이러한 환경에서의 배포도 프리뷰(preview) 및 프로덕션(production) 배포와 동일한 ID 제공자(identity provider) 로그인을 사용할 수 있습니다.

Vercel Passport는 Enterprise plan에서 사용할 수 있습니다. 새로운 가이드에서는 identity provider setup, token claims, 로컬 개발(local development), forwarding identity between backends, 그리고 자동화를 위한 Passport 우회(bypassing) 방법을 다룹니다.

Passport documentation을 참조하여 ID 제공자와 함께 Passport를 설정하거나, Vercel API를 통해 프로그래밍 방식으로 구성할 수 있습니다.

Read more

애플리케이션 코드에서 방문자 신원(identity) 읽기

ID 제공자의 그룹을 사용하여 권한 부여(Authorize)

다운스트림 서비스(downstream services)에서 신원 검증

Passport 액세스 모니터링

자동화된 트래픽을 위한 Passport 우회

신뢰할 수 있는 소스(Trusted Sources)로 Passport 우회

커스텀 환경(custom environments) 보호

시작하기