OAuth 2.0을 사용하여 Google API에 액세스하기

Google API는 인증과 승인에 OAuth 2.0 프로토콜을 사용합니다. Google은 웹 서버, 클라이언트 측, 설치된 기기, 입력이 제한된 기기 애플리케이션과 같은 일반적인 OAuth 2.0 시나리오를 지원합니다.

시작하려면 Google API Console에서 OAuth 2.0 클라이언트 사용자 인증 정보를 가져옵니다. 그런 다음 클라이언트 애플리케이션이 Google 승인 서버에 액세스 토큰을 요청하고, 응답에서 토큰을 추출한 후 액세스하려는 Google API에 토큰을 전송합니다. 자체 클라이언트 사용자 인증 정보를 사용하는 옵션을 포함하여 Google에서 OAuth 2.0을 사용하는 대화형 데모를 보려면 OAuth 2.0 플레이그라운드를 사용해 보세요.

이 페이지에서는 Google에서 지원하는 OAuth 2.0 승인 시나리오에 대한 개요와 자세한 콘텐츠로 연결되는 링크를 제공합니다. 인증에 OAuth 2.0을 사용하는 방법에 대한 자세한 내용은 OpenID Connect를 참조하세요.

기본 단계

모든 애플리케이션은 OAuth 2.0을 사용하여 Google API에 액세스할 때 기본적인 패턴을 따릅니다. 대략적으로 5단계를 따릅니다.

1. Google API Console에서 OAuth 2.0 사용자 인증 정보를 가져옵니다.

Google API Console로 이동하여 Google과 애플리케이션에 모두 알려진 클라이언트 ID 및 클라이언트 보안 비밀번호와 같은 OAuth 2.0 사용자 인증 정보를 가져옵니다. 값 집합은 빌드 중인 애플리케이션 유형에 따라 다릅니다. 예를 들어 JavaScript 애플리케이션에는 보안 비밀이 필요하지 않지만 웹 서버 애플리케이션에는 보안 비밀이 필요합니다.

앱을 실행할 플랫폼에 적합한 OAuth 클라이언트를 만들어야 합니다. 예를 들면 다음과 같습니다.

  • 서버 측 또는 JavaScript 웹 앱의 경우 '웹' 클라이언트 유형을 사용합니다. 네이티브 또는 모바일 앱과 같은 다른 애플리케이션에는 이 클라이언트 유형을 사용하지 마세요.
  • Android 앱의 경우 'Android' 클라이언트 유형을 사용합니다.
  • iOS 및 macOS 앱의 경우 'iOS' 클라이언트 유형을 사용합니다.
  • 범용 Windows 플랫폼 앱의 경우 '범용 Windows 플랫폼' 클라이언트 유형을 사용합니다.
  • 제한된 입력 기기(예: TV 또는 내장형 기기)의 경우 'TV 및 제한된 입력 기기' 클라이언트 유형을 사용합니다.
  • 서버 간 상호작용의 경우 서비스 계정을 사용합니다.

2. Google 승인 서버에서 액세스 토큰을 가져옵니다.

애플리케이션에서 Google API를 사용하여 비공개 데이터에 액세스하려면 먼저 해당 API에 대한 액세스 권한을 부여하는 액세스 토큰을 가져와야 합니다. 단일 액세스 토큰은 여러 API에 다양한 수준의 액세스를 부여할 수 있습니다. scope라는 변수 매개변수는 액세스 토큰에서 허용하는 리소스 및 작업 집합을 제어합니다. 액세스 토큰 요청 중에 애플리케이션은 scope 매개변수에 하나 이상의 값을 전송합니다.

이 요청을 수행하는 방법에는 여러 가지가 있으며 빌드 중인 애플리케이션 유형에 따라 달라집니다. 예를 들어 JavaScript 애플리케이션은 Google로 가는 브라우저 리디렉션을 사용하여 액세스 토큰을 요청하는 반면, 브라우저가 없는 기기에 설치된 애플리케이션은 웹 서비스 요청을 사용할 수 있습니다.

일부 요청에는 사용자가 Google 계정으로 로그인하는 인증 단계가 필요합니다. 로그인하면 애플리케이션에서 요청하는 하나 이상의 권한을 부여할지 묻는 메시지가 사용자에게 표시됩니다. 이 과정을 사용자 동의라고 합니다.

사용자가 하나 이상의 권한을 부여하면 Google 승인 서버가 애플리케이션에 액세스 토큰 (또는 애플리케이션이 액세스 토큰을 얻는 데 사용할 수 있는 승인 코드) 및 해당 토큰이 부여하는 액세스 범위 목록을 보냅니다. 사용자가 권한을 부여하지 않으면 서버에서 오류를 반환합니다.

일반적으로 범위를 미리 요청하는 것이 아니라 액세스가 필요할 때 점진적으로 요청하는 것이 좋습니다. 예를 들어 캘린더에 이벤트 저장을 지원하려는 앱은 사용자가 '캘린더에 추가' 버튼을 누를 때까지 Google Calendar 액세스를 요청해서는 안 됩니다. 증분 승인을 참고하세요.

3. 사용자가 부여한 액세스 범위를 검토합니다.

액세스 토큰 응답에 포함된 범위를 관련 Google API에 대한 액세스에 따라 애플리케이션의 기능에 액세스하는 데 필요한 범위와 비교합니다. 관련 API에 액세스하지 않고는 작동할 수 없는 앱 기능을 중지합니다.

사용자가 요청된 모든 범위를 부여했더라도 요청에 포함된 범위가 응답에 포함된 범위와 일치하지 않을 수 있습니다. 액세스에 필요한 범위는 각 Google API의 문서를 참조하세요. API는 여러 범위 문자열 값을 단일 액세스 범위에 매핑하여 요청에서 허용되는 모든 값에 동일한 범위 문자열을 반환할 수 있습니다. 예: 앱에서 사용자에게 https://www.google.com/m8/feeds/의 범위를 승인하도록 요청한 경우 Google People API는 https://www.googleapis.com/auth/contacts의 범위를 반환할 수 있습니다. Google People API 메서드 people.updateContact에는 https://www.googleapis.com/auth/contacts의 부여된 범위가 필요합니다.

4. API에 액세스 토큰을 전송합니다.

애플리케이션은 액세스 토큰을 받은 후 HTTP 승인 요청 헤더에 있는 Google API로 토큰을 전송합니다. 토큰을 URI 쿼리 문자열 매개변수로 보낼 수 있지만 URI 매개변수는 안전하지 않은 로그 파일에 포함될 수 있으므로 권장하지 않습니다. 또한 불필요한 URI 매개변수 이름을 만들지 않는 것이 좋습니다.

액세스 토큰은 토큰 요청의 scope에 설명된 작업 및 리소스 집합에 대해서만 유효합니다. 예를 들어 Google Calendar API용으로 액세스 토큰이 발급되더라도 Google Contacts API에 대한 액세스 권한은 부여되지 않습니다. 하지만 유사한 작업을 위해 해당 액세스 토큰을 Google Calendar API에 여러 번 보낼 수 있습니다.

5. 필요한 경우 액세스 토큰을 갱신합니다.

액세스 토큰의 수명은 제한되어 있습니다. 애플리케이션이 단일 액세스 토큰의 수명보다 더 오래 Google API에 액세스해야 하는 경우 갱신 토큰을 얻을 수 있습니다. 갱신 토큰을 사용하면 애플리케이션에서 새 액세스 토큰을 가져올 수 있습니다.

시나리오

웹 서버 애플리케이션

Google OAuth 2.0 엔드포인트는 PHP, Java, Go, Python, Ruby, ASP.NET과 같은 언어와 프레임워크를 사용하는 웹 서버 애플리케이션을 지원합니다.

승인 순서는 애플리케이션이 브라우저를 Google URL로 리디렉션할 때 시작됩니다. 이 URL에는 요청 중인 액세스 유형을 나타내는 쿼리 매개변수가 포함됩니다. Google에서 사용자 인증, 세션 선택, 사용자 동의를 처리합니다. 그 결과로 애플리케이션이 액세스 토큰 및 갱신 토큰으로 교환할 수 있는 승인 코드가 생성됩니다.

애플리케이션은 나중에 사용할 수 있도록 갱신 토큰을 저장하고 액세스 토큰을 사용하여 Google API에 액세스해야 합니다. 액세스 토큰이 만료되면 애플리케이션에서 갱신 토큰을 사용하여 새 토큰을 받습니다.

애플리케이션이 토큰 요청을 Google 승인 서버로 전송하고, 승인 코드를 수신하고, 코드를 토큰으로 교환하고, 토큰을 사용하여 Google API 엔드포인트를 호출합니다.

자세한 내용은 웹 서버 애플리케이션용 OAuth 2.0 사용하기를 참고하세요.

설치된 애플리케이션

Google OAuth 2.0 엔드포인트는 컴퓨터, 휴대기기, 태블릿과 같은 기기에 설치된 애플리케이션을 지원합니다. Google API Console를 통해 클라이언트 ID를 만들 때 설치된 애플리케이션이라고 지정한 다음 애플리케이션 유형으로 Android, Chrome 앱, iOS, 범용 Windows 플랫폼 (UWP) 또는 데스크톱 앱을 선택합니다.

이 프로세스를 통해 클라이언트 ID가 생성되며 클라이언트 보안 비밀번호가 생깁니다. 클라이언트 보안 비밀번호가 애플리케이션의 소스 코드에 삽입되는 경우도 있습니다. 이 컨텍스트에서 클라이언트 보안 비밀은 당연히 보안 비밀로 취급되지 않습니다.

승인 순서는 애플리케이션이 브라우저를 Google URL로 리디렉션할 때 시작됩니다. 이 URL에는 요청 중인 액세스 유형을 나타내는 쿼리 매개변수가 포함됩니다. Google에서 사용자 인증, 세션 선택, 사용자 동의를 처리합니다. 그 결과로 애플리케이션이 액세스 토큰 및 갱신 토큰으로 교환할 수 있는 승인 코드가 생성됩니다.

애플리케이션은 나중에 사용할 수 있도록 갱신 토큰을 저장하고 액세스 토큰을 사용하여 Google API에 액세스해야 합니다. 액세스 토큰이 만료되면 애플리케이션에서 갱신 토큰을 사용하여 새 토큰을 받습니다.

애플리케이션이 토큰 요청을 Google 승인 서버로 전송하고, 승인 코드를 수신하고, 코드를 토큰으로 교환하고, 토큰을 사용하여 Google API 엔드포인트를 호출합니다.

자세한 내용은 설치된 애플리케이션에 OAuth 2.0 사용을 참고하세요.

클라이언트 측 (자바스크립트) 애플리케이션

Google OAuth 2.0 엔드포인트는 브라우저에서 실행되는 JavaScript 애플리케이션을 지원합니다.

승인 순서는 애플리케이션이 브라우저를 Google URL로 리디렉션할 때 시작됩니다. 이 URL에는 요청 중인 액세스 유형을 나타내는 쿼리 매개변수가 포함됩니다. Google에서 사용자 인증, 세션 선택, 사용자 동의를 처리합니다.

그 결과로 클라이언트가 액세스 토큰을 검증한 후 Google API 요청에 포함합니다. 토큰이 만료되면 애플리케이션에서 프로세스를 반복합니다.

JS 애플리케이션은 토큰 요청을 Google 승인 서버로 전송하고, 토큰을 수신하고, 토큰을 검증하고, 토큰을 사용하여 Google API 엔드포인트를 호출합니다.

자세한 내용은 클라이언트 측 애플리케이션용 OAuth 2.0 사용을 참고하세요.

입력이 제한된 기기의 애플리케이션

Google OAuth 2.0 엔드포인트는 게임 콘솔, 비디오 카메라, 프린터와 같은 입력이 제한된 기기에서 실행되는 애플리케이션을 지원합니다.

승인 시퀀스는 애플리케이션이 승인 코드의 Google URL에 웹 서비스를 요청하는 것으로 시작됩니다. 응답에는 애플리케이션이 사용자에게 표시하는 URL 및 코드를 비롯한 여러 매개변수가 포함됩니다.

사용자가 기기에서 URL과 코드를 가져온 다음 더 풍부한 입력 기능을 갖춘 별도의 기기나 컴퓨터로 전환합니다. 사용자가 브라우저를 시작하고, 지정된 URL로 이동하여 로그인하고, 코드를 입력합니다.

한편 애플리케이션은 지정된 간격으로 Google URL을 폴링합니다. 사용자가 액세스를 승인하면 Google 서버의 응답에 액세스 토큰과 갱신 토큰이 포함됩니다. 애플리케이션은 나중에 사용할 수 있도록 갱신 토큰을 저장하고 액세스 토큰을 사용하여 Google API에 액세스해야 합니다. 액세스 토큰이 만료되면 애플리케이션에서 갱신 토큰을 사용하여 새 토큰을 받습니다.

사용자가 브라우저가 있는 별도의 기기에 로그인합니다.

자세한 내용은 기기용 OAuth 2.0 사용을 참고하세요.

서비스 계정

Prediction API 및 Google Cloud Storage와 같은 Google API는 사용자 정보에 액세스하지 않고도 애플리케이션을 대신하여 작동할 수 있습니다. 이러한 상황에서는 애플리케이션이 API에 자체 ID를 증명해야 하지만 사용자 동의는 필요하지 않습니다. 마찬가지로 엔터프라이즈 시나리오에서는 애플리케이션이 일부 리소스에 대한 위임된 액세스 권한을 요청할 수 있습니다.

이러한 유형의 서버 간 상호작용에는 개별 최종 사용자가 아닌 애플리케이션에 속한 계정인 서비스 계정이 필요합니다. 애플리케이션은 서비스 계정을 대신하여 Google API를 호출하며 사용자 동의가 필요하지 않습니다. (비서비스 계정 시나리오에서는 애플리케이션이 최종 사용자를 대신하여 Google API를 호출하며 사용자 동의가 필요한 경우도 있습니다.)

Google API Console에서 가져오는 서비스 계정의 사용자 인증 정보에는 고유한 생성된 이메일 주소, 클라이언트 ID, 하나 이상의 공개 키/비공개 키 쌍이 포함됩니다. 클라이언트 ID와 비공개 키 1개를 사용하여 서명된 JWT를 만들고 적절한 형식으로 액세스 토큰 요청을 작성합니다. 그런 다음 애플리케이션이 토큰 요청을 Google OAuth 2.0 승인 서버로 전송하여 액세스 토큰을 반환합니다. 애플리케이션은 토큰을 사용하여 Google API에 액세스합니다. 토큰이 만료되면 애플리케이션이 프로세스를 반복합니다.

서버 애플리케이션은 JWT를 사용하여 Google 승인 서버에서 토큰을 요청한 다음 토큰을 사용하여 Google API 엔드포인트를 호출합니다. 최종 사용자는 관여하지 않습니다.

자세한 내용은 서비스 계정 문서를 참조하세요.

토큰 크기

토큰의 크기는 다음과 같을 수 있으며 최대 한도는 다음과 같습니다.

  • 승인 코드: 256바이트
  • 액세스 토큰: 2048바이트
  • 갱신 토큰: 512바이트

Google Cloud의 Security Token Service API에서 반환하는 액세스 토큰은 Google API OAuth 2.0 액세스 토큰과 유사하게 구조화되지만 토큰 크기 한도가 다릅니다. 자세한 내용은 API 문서를 참고하세요.

Google은 이 한도 내에서 토큰 크기를 변경할 권리를 보유하며, 이에 따라 애플리케이션이 가변 토큰 크기를 지원해야 합니다.

갱신 토큰 만료

부여된 갱신 토큰이 더 이상 작동하지 않을 수 있음을 예상하도록 코드를 작성해야 합니다. 다음과 같은 이유로 갱신 토큰이 작동하지 않을 수 있습니다.

외부 사용자 유형에 대해 OAuth 동의 화면이 구성되고 게시 상태가 '테스트 중'인 Google Cloud Platform 프로젝트에는 7일 후에 만료되는 갱신 토큰이 발급됩니다. 단, 요청된 OAuth 범위가 이름, 이메일 주소, 사용자 프로필의 하위 집합 ( userinfo.email, userinfo.profile, openid 범위 또는 OpenID Connect 해당 항목을 통해)이 아닌 경우는 예외입니다.

현재 OAuth 2.0 클라이언트 ID당 Google 계정당 갱신 토큰 100개로 제한됩니다. 한도에 도달하면 새 갱신 토큰을 만들면 경고 없이 자동으로 가장 오래된 갱신 토큰이 무효화됩니다. 이 한도는 서비스 계정에는 적용되지 않습니다.

또한 사용자 계정 또는 서비스 계정이 모든 클라이언트에서 보유할 수 있는 갱신 토큰의 총 개수에도 더 큰 한도가 있습니다. 대부분의 일반 사용자는 이 한도를 초과하지 않지만 구현을 테스트하는 데 사용되는 개발자 계정에서는 이 한도를 초과할 수 있습니다.

여러 프로그램, 컴퓨터 또는 기기를 승인해야 하는 경우 한 가지 해결 방법은 Google 계정당 승인하는 클라이언트 수를 15개 또는 20개로 제한하는 것입니다. Google Workspace 관리자는 관리 권한이 있는 추가 사용자를 만들어 일부 클라이언트를 승인하는 데 사용할 수 있습니다.

Google Cloud Platform (GCP) 조직의 세션 제어 정책 처리

GCP 조직의 관리자는 GCP 리소스에 액세스하는 동안 Google Cloud 세션 제어 기능을 사용하여 사용자를 자주 재인증하도록 요구할 수 있습니다. 이 정책은 Google Cloud 콘솔, Google Cloud SDK (gcloud CLI라고도 함), Cloud Platform 범위가 필요한 서드 파티 OAuth 애플리케이션에 대한 액세스에 영향을 미칩니다. 사용자에게 세션 제어 정책이 적용된 경우 세션 시간 만료 시점에 API 호출에서 갱신 토큰이 취소되었을 때와 유사한 오류가 발생합니다. 호출이 invalid_grant 오류 유형으로 실패하고 세션 제어 정책으로 인한 실패(예: "error_subtype": "invalid_rapt")로 토큰과 실패를 구분할 수 있습니다. 세션 시간은 1시간에서 1시간까지 매우 제한될 수 있습니다.error_subtype

마찬가지로 서버 간 배포에 사용자 인증 정보를 사용하거나 사용을 권장해서는 안 됩니다. 장기 실행 작업 또는 작업을 위해 사용자 인증 정보가 서버에 배포되고 고객이 이러한 사용자에게 세션 제어 정책을 적용하면 세션 시간이 만료되면 사용자를 다시 인증할 방법이 없으므로 서버 애플리케이션이 실패합니다.

고객이 이 기능을 배포하도록 지원하는 방법에 대한 자세한 내용은 관리자 중심의 도움말을 참조하세요.

클라이언트 라이브러리

다음 클라이언트 라이브러리는 널리 사용되는 프레임워크와 통합되어 OAuth 2.0을 더 간단하게 구현할 수 있습니다. 앞으로 더 많은 기능이 라이브러리에 추가될 예정입니다.