이 페이지는 Cloud Translation API를 통해 번역되었습니다.
Switch to English

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

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

시작하려면 Google API Console 에서 OAuth 2.0 클라이언트 자격 증명을 가져 옵니다 . 그런 다음 클라이언트 애플리케이션은 Google Authorization Server에서 액세스 토큰을 요청하고 응답에서 토큰을 추출한 다음 액세스하려는 Google API로 토큰을 보냅니다. Google과 함께 OAuth 2.0을 사용하는 대화 형 데모 (자신의 클라이언트 자격 증명을 사용하는 옵션 포함)를 보려면 OAuth 2.0 Playground 를 사용해보세요.

이 페이지는 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 애플리케이션에는 비밀이 필요하지 않지만 웹 서버 애플리케이션에는 필요합니다.

2. Google 인증 서버에서 액세스 토큰을 얻습니다.

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

이 요청을하는 방법에는 여러 가지가 있으며 구축중인 응용 프로그램 유형에 따라 다릅니다. 예를 들어 JavaScript 애플리케이션은 브라우저가 Google로 리디렉션되는 브라우저를 사용하여 액세스 토큰을 요청하는 반면 브라우저가없는 기기에 설치된 애플리케이션은 웹 서비스 요청을 사용합니다.

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

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

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

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 매개 변수 이름을 작성하지 않는 것이 좋은 REST 관행입니다. 쿼리 문자열 지원은 2021 년 6 월 1 일에 더 이상 사용되지 않습니다.

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

5. 필요한 경우 액세스 토큰을 새로 고칩니다.

액세스 토큰의 수명은 제한되어 있습니다. 애플리케이션이 단일 액세스 토큰의 수명 이후에 Google API에 액세스해야하는 경우 새로 고침 토큰을 얻을 수 있습니다. 새로 고침 토큰을 사용하면 애플리케이션이 새 액세스 토큰을 얻을 수 있습니다.

시나리오

웹 서버 애플리케이션

Google OAuth 2.0 엔드 포인트는 PHP, Java, 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, UWP (유니버설 Windows 플랫폼) 또는 데스크톱 앱을 애플리케이션 유형으로 선택합니다.

이 프로세스는 클라이언트 ID 및 경우에 따라 애플리케이션의 소스 코드에 포함하는 클라이언트 암호를 생성합니다. (이 맥락에서 클라이언트 시크릿은 분명히 시크릿으로 취급되지 않습니다.)

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

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

애플리케이션은 Google Authorization Server에 토큰 요청을 보내고, 인증 코드를 받고, 코드를 토큰으로 교환하고, 토큰을 사용하여 Google API 엔드 포인트를 호출합니다.

자세한 내용 은 설치된 애플리케이션에 OAuth 2.0 사용을 참조하십시오.

클라이언트 측 (JavaScript) 애플리케이션

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

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

결과는 클라이언트가 Google API 요청에 포함하기 전에 유효성을 검사해야하는 액세스 토큰입니다. 토큰이 만료되면 애플리케이션이 프로세스를 반복합니다.

JS 애플리케이션은 Google Authorization Server에 토큰 요청을 보내고, 토큰을 받고, 토큰의 유효성을 검사하고, 토큰을 사용하여 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와 하나의 개인 키를 사용하여 서명 된 JWT를 만들고 적절한 형식으로 액세스 토큰 요청을 구성합니다. 그런 다음 애플리케이션은 액세스 토큰을 반환하는 Google OAuth 2.0 인증 서버로 토큰 요청을 보냅니다. 애플리케이션은 토큰을 사용하여 Google API에 액세스합니다. 토큰이 만료되면 애플리케이션이 프로세스를 반복합니다.

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

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

토큰 크기

토큰은 다음 한도까지 크기가 다를 수 있습니다.

  • 인증 코드 : 256 바이트
  • 액세스 토큰 : 2048 바이트
  • 새로 고침 토큰 : 512 바이트

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

토큰 만료 새로 고침

부여 된 새로 고침 토큰이 더 이상 작동하지 않을 가능성을 예상하는 코드를 작성해야합니다. 다음 이유 중 하나로 인해 새로 고침 토큰이 작동하지 않을 수 있습니다.

  • 사용자가 앱의 액세스 권한을 취소했습니다 .
  • 새로 고침 토큰이 6 개월 동안 사용되지 않았습니다.
  • 사용자가 비밀번호를 변경했으며 새로 고침 토큰에 Gmail 범위가 포함되어 있습니다.
  • 사용자 계정이 허용 된 (라이브) 새로 고침 토큰의 최대 수를 초과했습니다.
  • 사용자는 세션 제어 정책이 적용되는 Google Cloud Platform 조직에 속해 있습니다.

외부 사용자 유형에 대해 구성된 OAuth 동의 화면이 있고 게시 상태가 '테스트 중'인 Google Cloud Platform 프로젝트는 7 일 후에 만료되는 새로 고침 토큰이 발급됩니다.

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

또한 사용자 계정 또는 서비스 계정이 모든 클라이언트에서 가질 수있는 총 새로 고침 토큰 수에 더 큰 제한이 있습니다. 대부분의 일반 사용자는이 제한을 초과하지 않지만 구현을 테스트하는 데 사용되는 개발자 계정이있을 수 있습니다.

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

Google Cloud Platform (GCP) 조직의 세션 제어 정책 다루기

GCP 조직의 관리자는 GCP 세션 제어 기능을 사용하여 GCP 리소스에 액세스하는 동안 사용자를 자주 재 인증해야 할 수 있습니다. 이 정책은 Google Cloud Console, Google Cloud SDK (gcloud CLI라고도 함) 및 Cloud Platform 범위가 필요한 타사 OAuth 애플리케이션에 대한 액세스에 영향을줍니다. 사용자에게 세션 제어 정책이있는 경우 세션 기간이 만료되면 API 호출이 새로 고침 토큰이 취소 된 경우와 유사한 오류가 발생합니다. 세션 기간은 매우 제한 될 수 있으므로 (1 시간에서 24 시간 사이)이 시나리오는 인증 세션을 다시 시작하여 적절하게 처리해야합니다.

마찬가지로 서버 간 배포를 위해 사용자 자격 증명을 사용하거나 사용하도록 권장해서는 안됩니다. 사용자 자격 증명이 장기 실행 작업 또는 작업을 위해 서버에 배포되고 고객이 이러한 사용자에게 세션 제어 정책을 적용하는 경우 세션 기간이 만료 될 때 사용자를 다시 인증 할 방법이 없으므로 서버 응용 프로그램이 실패합니다.

고객이이 기능을 배포하는 데 도움이되는 방법에 대한 자세한 내용은이 관리자 중심 도움말 문서를 참조하십시오.

클라이언트 라이브러리

다음 클라이언트 라이브러리는 인기있는 프레임 워크와 통합되어 OAuth 2.0 구현이 더 간단 해집니다. 시간이 지남에 따라 더 많은 기능이 라이브러리에 추가 될 것입니다.