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

구글 API는 사용 하여 OAuth 2.0 프로토콜 인증 및 권한 부여를 들어. Google은 웹 서버, 클라이언트 측, 설치 및 제한된 입력 장치 애플리케이션에 대한 시나리오와 같은 일반적인 OAuth 2.0 시나리오를 지원합니다.

시작하려면에서의 OAuth 2.0 클라이언트 자격 증명을 취득 Google API Console . 그런 다음 클라이언트 애플리케이션은 Google Authorization Server에서 액세스 토큰을 요청하고 응답에서 토큰을 추출한 다음 액세스하려는 Google API로 토큰을 보냅니다. 구글의 OAuth 2.0을 사용하는 대화 형 데모의 경우와 실험 (당신의 자신의 클라이언트 자격 증명을 사용하는 옵션 포함) 의 OAuth 2.0 놀이터 .

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

기본 단계

모든 애플리케이션은 OAuth 2.0을 사용하여 Google API에 액세스할 때 기본 패턴을 따릅니다. 높은 수준에서 다음 5단계를 따릅니다.

OAuth를에게 2.0 자격 증명을 얻 1. Google API Console.

방문 Google API Console 구글과 애플리케이션 모두에 알려진 클라이언트 ID와 클라이언트 비밀로하여 OAuth 2.0 자격증을 얻을 수 있습니다. 값 집합은 구축 중인 애플리케이션 유형에 따라 다릅니다. 예를 들어 JavaScript 응용 프로그램에는 비밀이 필요하지 않지만 웹 서버 응용 프로그램에는 필요합니다.

2. Google Authorization Server에서 액세스 토큰을 얻습니다.

애플리케이션이 Google API를 사용하여 비공개 데이터에 액세스하려면 먼저 해당 API에 대한 액세스 권한을 부여하는 액세스 토큰을 얻어야 합니다. 단일 액세스 토큰으로 여러 API에 대한 다양한 수준의 액세스 권한을 부여할 수 있습니다. 가변 파라미터는 전화 scope 자원과 동작의 세트의 액세스 허용하는 토큰 제어. 액세스 토큰 요청하는 동안 응용 프로그램은 하나 개 이상의 값을 전송 scope 매개 변수입니다.

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

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

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

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

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

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

사용자가 요청된 모든 범위를 부여한 경우에도 요청에 포함된 범위가 응답에 포함된 범위와 일치하지 않을 수 있습니다. 액세스에 필요한 범위는 각 Google API의 설명서를 참조하십시오. API는 여러 범위 문자열 값을 단일 액세스 범위에 매핑하여 요청에 허용된 모든 값에 대해 동일한 범위 문자열을 반환할 수 있습니다. 예 : 구글 사람들의 API가의 범위를 반환 할 수 있습니다 https://www.googleapis.com/auth/contacts 응용 프로그램이 사용자의 범위를 허가 요청시 https://www.google.com/m8/feeds/ ; 구글 사람들의 API 방법 people.updateContact 의 허용 범위를 필요로 https://www.googleapis.com/auth/contacts .

4. 액세스 토큰을 API로 보냅니다.

응용 프로그램이 액세스 토큰을 획득 한 후, 그것은에서 구글 API에 토큰을 전송 HTTP 인증 요청 헤더 . 토큰을 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 Authorization Server에 토큰 요청을 보내고, 인증 코드를 수신하고, 코드를 토큰으로 교환하고, 토큰을 사용하여 Google API 엔드포인트를 호출합니다.

상세한 내용은 웹 서버 응용 프로그램에 대한 OAuth는 2.0을 사용 .

설치된 애플리케이션

Google OAuth 2.0 엔드포인트는 컴퓨터, 모바일 기기, 태블릿과 같은 기기에 설치된 애플리케이션을 지원합니다. 당신은을 통해 클라이언트 ID 생성 할 때 Google API Console , 이것이 설치된 응용 프로그램 지정, 다음 응용 프로그램 유형으로 안드로이드, 크롬 앱 아이폰 OS, 유니버설 윈도우 플랫폼 (UWP) 또는 데스크톱 응용 프로그램을 선택합니다.

이 프로세스를 통해 클라이언트 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 클라우드의에 의해 반환 된 토큰 보안 토큰 서비스 API는 구글 API의 OAuth 2.0 액세스 토큰과 유사하게 구성하지만 서로 다른 토큰 크기 제한이 있습니다. 자세한 내용은 참조 API 설명서를 .

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

새로고침 토큰 만료

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

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

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

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

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

여러 프로그램, 기계 또는 장치에 권한을 부여해야하는 경우, 하나의 해결 방법은 당신이 경우에 당신은 15 또는 20에 Google 계정 당 권한을 부여하는 것이 고객의 수를 제한하는 것입니다 구글 작업 공간 관리자 관리자 권한과 부가적인 사용자를 생성 할 수 있습니다, 일부 클라이언트를 승인하는 데 사용합니다.

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

그들은 GCP 리소스에 액세스하는 동안 GCP 조직의 관리자는 사용하여, 사용자의 빈번한 재 인증이 필요할 수 있습니다 Google 클라우드 세션 제어 기능을 . 이 정책의 영향은 Google 클라우드 콘솔의 액세스를 Google 클라우드 SDK (또한 gcloud의 CLI라고도 함), 그리고 클라우드 플랫폼의 범위를 필요로하는 타사 OAuth를 응용 프로그램입니다. 사용자가 세션 기간의 만료에 다음 장소에서 세션 제어 정책이있는 경우, 귀하의 API 호출이 취소되었습니다 토큰 새로 고침이 경우 무슨 일이 일어날 지와 유사한 오류가 밖으로 것 - 호출이 오류 유형과 실패 invalid_token ; 하위 오류 유형은 취소 토큰과 세션 제어 정책으로 인한 실패를 구별하는 데 사용할 수 있습니다. 세션 기간이 매우 제한될 수 있으므로(1시간에서 24시간 사이) 이 시나리오는 인증 세션을 다시 시작하여 정상적으로 처리되어야 합니다.

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

고객이이 기능을 배포하는 방법에 대한 자세한 내용은이 참조 관리자-초점을 맞춘 도움말.

클라이언트 라이브러리

다음 클라이언트 라이브러리는 인기 있는 프레임워크와 통합되어 OAuth 2.0을 더 간단하게 구현할 수 있습니다. 시간이 지남에 따라 더 많은 기능이 라이브러리에 추가됩니다.