모바일 및 데스크톱 앱용 OAuth 2.0

이 개요에는 Google에서 지원하는 OAuth 2.0 흐름이 요약되어 있으며, 애플리케이션에 적합한 흐름을 선택했는지 확인할 수 있습니다.

이 문서에서는 스마트폰, 태블릿, 컴퓨터와 같은 기기에 설치된 애플리케이션에서 Google API에 대한 액세스를 승인하기 위해 OAuth 2.0 엔드포인트를 사용하는 방법을 설명합니다.

OAuth 2.0을 사용하면 사용자가 사용자 이름과 비밀번호, 기타 정보를 비공개로 유지하면서 애플리케이션과 특정 데이터를 공유할 수 있습니다. 예를 들어 애플리케이션은 OAuth 2.0을 사용하여 Google Drive에 파일을 저장할 사용자 권한을 얻을 수 있습니다.

설치된 앱은 개별 기기에 배포되며 이러한 앱은 보안 비밀을 유지할 수 없다고 가정합니다. 사용자가 앱에 있거나 앱이 백그라운드에서 실행 중일 때 Google API에 액세스할 수 있습니다.

이 승인 흐름은 웹 서버 애플리케이션에 사용되는 흐름과 비슷합니다. 주요 차이점은 설치된 앱이 시스템 브라우저를 열고 Google의 승인 서버의 응답을 처리하기 위해 로컬 리디렉션 URI를 제공해야 한다는 것입니다.

대안

모바일 앱의 경우 Android 또는 iOS용 Google 로그인을 사용하는 것이 좋습니다. Google 로그인 클라이언트 라이브러리는 인증 및 사용자 승인을 처리하며, 여기에 설명된 하위 수준 프로토콜보다 구현하기가 더 간단할 수 있습니다.

시스템 브라우저를 지원하지 않는 기기에서 실행되거나 TV, 게임 콘솔, 카메라, 프린터와 같이 입력 기능이 제한된 앱은 TV 및 AMP 기기용 OAuth 2.0 또는 TV 및 제한된 입력 장치용 로그인을 참고하세요.

라이브러리 및 샘플

다음 라이브러리와 샘플을 사용하여 이 문서에 설명된 OAuth 2.0 흐름을 구현하는 것이 좋습니다.

기본 요건

프로젝트에 API 사용 설정

Google API를 호출하는 모든 애플리케이션은 API Console에서 이러한 API를 사용 설정해야 합니다.

프로젝트에 API를 사용 설정하려면 다음 단계를 따르세요.

  1. Open the API Library ( Google API Console)
  2. If prompted, select a project, or create a new one.
  3. API Library 에는 사용 가능한 모든 API가 제품군 및 인기도별로 분류되어 있습니다. 사용 설정하려는 API가 목록에 없는 경우 검색을 사용하여 찾거나 해당 API 제품군이 속한 제품군에서 모두 보기를 클릭합니다.
  4. 사용 설정하려는 API를 선택한 다음 사용 설정 버튼을 클릭합니다.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

승인 사용자 인증 정보 만들기

OAuth 2.0을 사용하여 Google API에 액세스하는 모든 애플리케이션에는 Google OAuth 2.0 서버에 대한 애플리케이션을 식별하는 승인 사용자 인증 정보가 있어야 합니다. 다음 단계에서는 프로젝트의 사용자 인증 정보를 만드는 방법을 설명합니다. 그러면 애플리케이션이 사용자 인증 정보를 사용하여 해당 프로젝트에서 사용 설정한 API에 액세스할 수 있습니다.

  1. Go to the Credentials page.
  2. 사용자 인증 정보 만들기 > OAuth 클라이언트 ID를 클릭합니다.
  3. 다음 섹션에서는 Google의 승인 서버에서 지원하는 클라이언트 유형과 리디렉션 방법을 설명합니다. 애플리케이션에 권장되는 클라이언트 유형을 선택하고, OAuth 클라이언트의 이름을 지정하고, 양식의 다른 필드를 적절하게 설정합니다.

맞춤 URI 스키마 (Android, iOS, UWP)

Android 앱, iOS 앱, UWP(Universal Windows Platform) 앱에는 맞춤 URI 스키마를 사용하는 것이 좋습니다.

Android
  1. Android 애플리케이션 유형을 선택합니다.
  2. OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트를 식별하기 위해 프로젝트에 표시되며 Credentials page 에 해당합니다.
  3. Android 앱의 패키지 이름을 입력합니다. 이 값은 앱 매니페스트 파일의 <manifest> 요소의 package 속성에 정의되어 있습니다.
  4. 앱 배포의 SHA-1 서명 인증서 디지털 지문을 입력합니다.
    • 앱이 Google Play 앱 서명을 사용하는 경우 Play Console의 앱 서명 페이지에서 SHA-1 디지털 지문을 복사합니다.
    • 자체 키 저장소와 서명 키를 관리하는 경우, 자바에 포함된 keytool 유틸리티를 사용하여 사람이 읽을 수 있는 형식으로 인증서 정보를 인쇄합니다. keytool 출력의 Certificate fingerprints 섹션에 SHA1 값을 복사합니다. 자세한 내용은 Android용 Google API 문서의 클라이언트 인증을 참조하세요.
  5. 만들기를 클릭합니다.
iOS
  1. iOS 애플리케이션 유형을 선택합니다.
  2. OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트를 식별하기 위해 프로젝트에 표시되며 Credentials page 에 해당합니다.
  3. 앱의 번들 식별자를 입력합니다. 번들 ID는 앱의 정보 속성 목록 리소스 파일 (info.plist)에 있는 CFBundleIdentifier 키 값입니다. 이 값은 Xcode 프로젝트 편집기의 일반 창 또는 서명 및 기능 창에 가장 일반적으로 표시됩니다. 번들 ID는 Apple App Store Connect 사이트에서 앱의 앱 정보 페이지의 일반 정보 섹션에도 표시됩니다.
  4. (선택사항)

    앱이 Apple의 App Store에 게시된 경우 앱의 App Store ID를 입력합니다. 스토어 ID는 모든 Apple App Store URL에 포함되는 숫자 문자열입니다.

    1. iOS 또는 iPadOS 기기에서 Apple App Store 앱을 엽니다.
    2. 앱을 검색합니다.
    3. 공유 버튼 (정사각형 및 위쪽 화살표 기호)을 선택합니다.
    4. 링크 복사를 선택합니다.
    5. 링크를 텍스트 편집기에 붙여넣습니다. App Store ID는 URL의 마지막 부분입니다.

      예: https://apps.apple.com/app/google/id284815942

  5. (선택사항)

    팀 ID를 입력합니다. 자세한 내용은 Apple 개발자 계정 문서의 팀 ID 찾기를 참고하세요.

  6. 만들기를 클릭합니다.
UWP : 초광대역
  1. 범용 Windows 플랫폼 애플리케이션 유형을 선택합니다.
  2. OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트를 식별하기 위해 프로젝트에 표시되며 Credentials page 에 해당합니다.
  3. 앱의 12자 Microsoft Store ID를 입력합니다. 이 값은 관리 파트너 센터의 앱 관리 섹션에 있는 앱 ID 페이지에서 확인할 수 있습니다.
  4. 만들기를 클릭합니다.

UWP 앱의 경우 맞춤 URI 스키마는 39자(영문 기준) 이하여야 합니다.

루프백 IP 주소 (macOS, Linux, Windows Desktop)

이 URL을 사용하여 승인 코드를 받으려면 애플리케이션이 로컬 웹 서버에서 수신 대기해야 합니다. 전부는 아니지만 대부분의 플랫폼에서 가능합니다. 그러나 플랫폼에서 지원하는 경우 승인 코드를 가져오는 데 권장되는 메커니즘입니다.

앱이 승인 응답을 수신하면 최상의 사용성을 위해 사용자에게 브라우저를 닫고 앱으로 돌아가도록 안내하는 HTML 페이지를 표시하여 응답해야 합니다.

권장 사용 사례 macOS, Linux, Windows 데스크톱 (유니버설 Windows 플랫폼 제외) 앱
양식 값 애플리케이션 유형을 데스크톱 앱으로 설정합니다.

수동 복사/붙여넣기

액세스 범위 확인

범위를 사용하면 애플리케이션에서 필요한 리소스에 대한 액세스만 요청하는 동시에 사용자가 애플리케이션에 부여하는 액세스 양을 제어할 수 있습니다. 따라서 요청된 범위 수와 사용자 동의 획득 가능성 사이에는 반비례적인 관계가 있을 수 있습니다.

OAuth 2.0 승인을 구현하기 전에 앱에 액세스 권한이 필요한 범위를 식별하는 것이 좋습니다.

OAuth 2.0 API 범위 문서에는 Google API에 액세스하는 데 사용할 수 있는 범위의 전체 목록이 포함되어 있습니다.

OAuth 2.0 액세스 토큰 가져오기

다음 단계에서는 애플리케이션이 Google의 OAuth 2.0 서버와 상호작용하여 사용자를 대신하여 API 요청을 실행하는 데 대한 사용자의 동의를 얻는 방법을 보여줍니다. 애플리케이션에서 사용자 승인이 필요한 Google API 요청을 실행하기 전에 동의를 얻어야 합니다.

1단계: 코드 검증 및 인증 요청 생성

Google은 설치된 앱 흐름의 보안을 강화하기 위해 PKCE(Proof Key for Code Exchange) 프로토콜을 지원합니다. 모든 인증 요청에 고유한 코드 검증이 생성되며, \'code_challenge"라는 변환된 값이 승인 서버에 전송되어 승인 코드를 가져옵니다.

코드 인증기 만들기

code_verifier는 예약되지 않은 문자 [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"를 사용하며 최소 4자(영문 기준) 및 4자(영문 기준)의 고 엔트로피 암호화 임의 문자열입니다.

코드 인증기는 값을 추측하기 어렵도록 엔트로피가 충분히 있어야 합니다.

코드 챌린지 만들기

코드 챌린지를 만드는 방법에는 두 가지가 지원됩니다.

코드 챌린지 생성 방법
S256 (권장) 코드 챌린지는 코드 인증 도구의 SHA256 해시로 인코딩된 Base64URL (패딩 없음)입니다.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
일반 코드 챌린지는 위에서 생성된 코드 인증과 동일한 값입니다.
code_challenge = code_verifier

2단계: Google OAuth 2.0 서버에 요청 보내기

사용자 승인을 받으려면 https://accounts.google.com/o/oauth2/v2/auth의 인증 서버에 요청을 보내세요. 이 엔드포인트는 활성 세션 조회를 처리하고, 사용자를 인증하고, 사용자 동의를 받습니다. 엔드포인트는 SSL을 통해서만 액세스할 수 있으며 SSL을 사용하지 않는 연결을 거부합니다.

승인 서버는 설치된 애플리케이션에 대해 다음과 같은 쿼리 문자열 매개변수를 지원합니다.

매개변수
client_id 필수

애플리케이션의 클라이언트 ID입니다. 이 값은 API Console Credentials page에서 확인할 수 있습니다.

redirect_uri 필수

Google의 승인 서버가 앱에 응답을 보내는 방법을 결정합니다. 설치된 앱에 사용할 수 있는 몇 가지 리디렉션 옵션이 있으며, 특정 리디렉션 방법을 염두에 두고 승인 사용자 인증 정보를 설정합니다.

값이 클라이언트에 구성된 OAuth 2.0 클라이언트에 대해 승인된 리디렉션 URI 중 하나와 정확히 일치해야 합니다. API Console Credentials page이 값이 승인된 URI와 일치하지 않으면 redirect_uri_mismatch 오류가 발생합니다.

아래 표는 각 메서드에 적합한 redirect_uri 매개변수 값을 보여줍니다.

redirect_uri
맞춤 URI 스키마 com.example.app:redirect_uri_path

또는

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app은 개발자가 제어하는 도메인의 역방향 DNS 표기법입니다. 맞춤 스키마에 올바른 기간이 포함되어야 합니다.
  • com.googleusercontent.apps.123는 클라이언트 ID의 역방향 DNS 표기법입니다.
  • redirect_uri_path은 선택적 경로 구성요소입니다(예: /oauth2redirect). 경로는 일반 HTTP URL과 달리 단일 슬래시로 시작해야 합니다.
루프백 IP 주소 http://127.0.0.1:port 또는 http://[::1]:port

플랫폼에서 관련 루프백 IP 주소를 쿼리하고 임의의 가용 포트에서 HTTP 리스너를 시작합니다. port이 앱에서 수신 대기하는 실제 포트 번호로 대체합니다.

모바일 앱에서 루프백 IP 주소 리디렉션 옵션을 지원 중단합니다.

response_type 필수

Google OAuth 2.0 엔드포인트가 승인 코드를 반환하는지 여부를 결정합니다.

설치된 애플리케이션의 매개변수 값을 code로 설정합니다.

scope 필수

애플리케이션이 사용자를 대신하여 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위 목록입니다. 이러한 값은 Google에서 사용자에게 표시하는 동의 화면에 알립니다.

범위를 사용하면 애플리케이션에서 필요한 리소스에 대한 액세스만 요청할 수 있으며, 사용자가 애플리케이션에 부여하는 액세스 양을 제어할 수 있습니다. 따라서 요청된 범위 수와 사용자 동의 획득 가능성 사이에는 반비례적인 관계가 있습니다.

code_challenge 권장

승인 코드 교환 중에 서버 측 챌린지로 사용할 인코딩된 code_verifier를 지정합니다. 자세한 내용은 위의 코드 챌린지 만들기 섹션을 참조하세요.

code_challenge_method 권장

승인 코드 교환 중에 사용할 code_verifier를 인코딩하는 데 사용된 메서드를 지정합니다. 이 매개변수는 위에서 설명한 code_challenge 매개변수와 함께 사용해야 합니다. code_challenge가 포함된 요청에 없는 경우 code_challenge_method 값은 기본적으로 plain입니다. 이 매개변수에 지원되는 값은 S256 또는 plain입니다.

state 권장

애플리케이션이 승인 요청과 승인 서버 응답 사이의 상태를 유지하는 데 사용하는 문자열 값을 지정합니다. 사용자가 애플리케이션의 액세스 요청에 동의하거나 거부한 후 서버는 redirect_uri의 URL 프래그먼트 식별자(#)에 name=value 쌍으로 전송하는 정확한 값을 반환합니다.

이 매개변수는 사용자를 애플리케이션의 올바른 리소스로 안내하거나, nonce를 전송하고, 교차 사이트 요청 위조를 줄이는 등의 다양한 목적으로 사용할 수 있습니다. redirect_uri를 추측할 수 있으므로 state 값을 사용하면 수신 연결이 인증 요청의 결과임을 보장할 수 있습니다. 무작위 문자열을 생성하거나 클라이언트 상태를 캡처하는 쿠키 또는 다른 값의 해시를 인코딩하는 경우, 응답을 검사하여 요청 및 응답이 동일한 브라우저에서 시작되었는지 추가로 확인할 수 있으므로 교차 사이트 요청 위조와 같은 공격으로부터 보호할 수 있습니다. state 토큰을 만들고 확인하는 방법의 예는 OpenID Connect 문서를 참조하세요.

login_hint 선택사항

애플리케이션에서 인증하려는 사용자를 알고 있다면 이 매개변수를 사용하여 Google 인증 서버에 힌트를 제공할 수 있습니다. 서버는 힌트를 사용하여 로그인 양식의 이메일 필드를 입력하거나 적절한 멀티 로그인 세션을 선택하여 로그인 과정을 간소화합니다.

매개변수 값을 사용자의 Google ID에 해당하는 이메일 주소 또는 sub 식별자로 설정합니다.

샘플 승인 URL

아래 탭에는 다양한 리디렉션 URI 옵션의 샘플 승인 URL이 나와 있습니다.

URL은 redirect_uri 매개변수의 값을 제외하고 동일합니다. URL에는 필수 response_typeclient_id 매개변수, 선택적 state 매개변수도 포함되어 있습니다. 각 URL은 가독성을 위해 줄바꿈과 공백을 포함합니다.

맞춤 URI 스키마

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

루프백 IP 주소

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

3단계: 사용자에게 동의 요청 메시지 표시

이 단계에서는 사용자가 애플리케이션에 요청된 액세스 권한을 부여할지 결정합니다. 이 단계에서 애플리케이션의 이름과 사용자에게 권한을 부여할 액세스 권한을 요청하는 Google API 서비스와 사용자에게 부여할 액세스 범위 요약을 보여주는 동의 창이 표시됩니다. 그러면 사용자는 애플리케이션에서 요청한 하나 이상의 범위에 대한 액세스 권한을 부여하거나 요청을 거부할 수 있습니다.

애플리케이션이 액세스 권한을 부여받았는지 여부를 나타내는 Google의 OAuth 2.0 서버의 응답을 기다리는 동안 이 단계에서 아무것도 할 필요가 없습니다. 이 응답은 다음 단계에 설명되어 있습니다.

오류

Google의 OAuth 2.0 승인 엔드포인트에 대한 요청에는 예상 인증 및 승인 흐름 대신 사용자에게 표시되는 오류 메시지가 표시될 수 있습니다. 일반적인 오류 코드 및 권장 해결 방법은 다음과 같습니다.

admin_policy_enforced

Google Workspace 관리자의 정책으로 인해 Google 계정에서 하나 이상의 요청을 요청할 수 없습니다. 액세스 권한이 명시적으로 OAuth 클라이언트 ID에 부여될 때까지 관리자가 모든 범위 또는 민감한 범위 및 제한된 범위에 대한 액세스를 제한할 수 있는 방법에 대한 자세한 내용은 Google Workspace 관리자 도움말인 Google Workspace 데이터에 액세스할 수 있는 타사 앱 및 내부 앱 제어를 참고하세요.

disallowed_useragent

Google의 OAuth 2.0 정책에서 허용하지 않는 삽입된 사용자 에이전트 안에 승인 엔드포인트가 표시됩니다.

Android

Android 개발자가 android.webkit.WebView에서 승인 요청을 열면 이 오류 메시지가 표시될 수 있습니다. 대신 개발자는 Android용 Google 로그인 또는 OpenID Foundation의 Android용 AppAuth와 같은 Android 라이브러리를 사용해야 합니다.

Android 앱에서 삽입된 사용자 에이전트에서 일반 웹 링크를 열고 사용자가 사이트에서 Google의 OAuth 2.0 승인 엔드포인트로 이동하면 이 오류가 발생할 수 있습니다. 개발자는 Android App Links 핸들러 또는 기본 브라우저 앱을 둘 다 포함하는 운영체제의 기본 링크 핸들러에서 일반 링크를 열 수 있도록 허용해야 합니다. Android 맞춤 탭 라이브러리도 지원됩니다.

iOS

iOS 및 macOS 개발자의 경우 WKWebView에서 승인 요청을 열면 이 오류가 발생할 수 있습니다. 개발자는 iOS용 Google 로그인 또는 OpenID Foundation의 iOS용 AppAuth와 같은 iOS 라이브러리를 사용해야 합니다.

iOS 또는 macOS 앱에서 삽입된 사용자 에이전트로 일반 웹 링크가 열리고 사용자가 사이트에서 Google의 OAuth 2.0 승인 엔드포인트로 이동하면 이 오류가 발생할 수 있습니다. 개발자는 범용 링크 핸들러나 기본 브라우저 앱을 둘 다 포함하는 운영체제의 기본 링크 핸들러에서 일반 링크를 열 수 있도록 허용해야 합니다. SFSafariViewController 라이브러리도 지원됩니다.

org_internal

요청의 OAuth 클라이언트 ID는 특정 Google Cloud 조직에서 Google 계정에 대한 액세스를 제한하는 프로젝트의 일부입니다. 이 구성 옵션에 대한 자세한 내용은 OAuth 동의 화면 설정 도움말의 사용자 유형 섹션을 참조하세요.

redirect_uri_mismatch

승인 요청에서 전달된 redirect_uri가 OAuth 클라이언트 ID에 대해 승인된 리디렉션 URI와 일치하지 않습니다. Google API Console Credentials page에서 승인된 리디렉션 URI를 검토합니다.

전달된 redirect_uri은(는) 클라이언트 유형에 대해 유효하지 않을 수 있습니다.

4단계: OAuth 2.0 서버 응답 처리하기

애플리케이션에서 승인 응답을 수신하는 방법은 사용하는 리디렉션 URI 스키마에 따라 다릅니다. 스키마에 관계없이 응답에 승인 코드(code) 또는 오류(error)가 포함됩니다. 예를 들어 error=access_denied는 사용자가 요청을 거부했음을 나타냅니다.

사용자가 애플리케이션에 대한 액세스 권한을 부여하면 다음 단계에 설명된 대로 액세스 코드를 갱신 토큰과 갱신 토큰으로 교환할 수 있습니다.

5단계: 갱신 및 액세스 토큰을 위한 승인 코드 교환

승인 토큰을 액세스 토큰으로 교환하려면 https://oauth2.googleapis.com/token 엔드포인트를 호출하고 다음 매개변수를 설정합니다.

필드
client_id API Console Credentials page에서 가져온 클라이언트 ID입니다.
client_secret Credentials page에서 가져온 API Console 클라이언트 보안 비밀번호
code 초기 요청에서 반환된 승인 코드입니다.
code_verifier 1단계에서 만든 코드 인증기
grant_type OAuth 2.0 사양에 정의된 대로 이 필드 값을 authorization_code로 설정해야 합니다.
redirect_uri 지정된 client_id의 API ConsoleCredentials page 에서 프로젝트에 나열된 리디렉션 URI 중 하나입니다.

다음 스니펫은 샘플 요청을 보여줍니다.

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google은 수명이 짧은 액세스 토큰과 갱신 토큰이 포함된 JSON 객체를 반환하여 이 요청에 응답합니다.

응답에는 다음 필드가 포함됩니다.

필드
access_token Google API 요청을 승인하기 위해 애플리케이션에서 전송하는 토큰입니다.
expires_in 액세스 토큰의 남은 기간(초)입니다.
id_token 참고: 이 속성은 요청에 openid, profile 또는 email와 같은 ID 범위가 포함된 경우에만 반환됩니다. 값은 디지털 서명 사용자 관련 사용자 정보가 포함된 JSON 웹 토큰 (JWT)입니다.
refresh_token 새 액세스 토큰을 얻는 데 사용할 수 있는 토큰입니다. 갱신 토큰은 사용자가 액세스 권한을 취소할 때까지 유효합니다. 갱신 토큰은 설치된 애플리케이션에 대해 항상 반환됩니다.
scope access_token에서 부여하는 액세스 범위이며 공백으로 구분된 대소문자를 구분하는 문자열 목록으로 표현됩니다.
token_type 반환된 토큰의 유형입니다. 현재 이 필드의 값은 항상 Bearer로 설정되어 있습니다.

다음 스니펫은 샘플 응답을 보여줍니다.

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Google API 호출

애플리케이션이 액세스 토큰을 획득한 후 API에 필요한 액세스 범위가 부여된 경우 특정 사용자 계정을 대신하여 Google API를 호출하는 데 토큰을 사용할 수 있습니다. 이를 위해 access_token 쿼리 매개변수 또는 Authorization HTTP 헤더 Bearer 값을 포함하여 API 요청에 액세스 토큰을 포함합니다. 쿼리 문자열은 서버 로그에 표시되는 경향이 있으므로 HTTP 헤더를 사용하는 것이 좋습니다. 대부분의 경우 클라이언트 라이브러리를 사용하여 Google API 호출을 설정할 수 있습니다 (예: Drive 파일 API 호출).

OAuth 2.0 Playground에서 모든 Google API를 사용해 보고 범위를 확인할 수 있습니다.

HTTP GET 예시

Authorization: Bearer HTTP 헤더를 사용한 drive.files 엔드포인트 (Drive Files API) 호출은 다음과 같습니다. 다음과 같이 자체 액세스 토큰을 지정해야 합니다.

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

다음은 access_token 쿼리 문자열 매개변수를 사용하여 인증된 사용자를 대상으로 동일한 API를 호출한 내역입니다.

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl

이 명령어는 curl 명령줄 애플리케이션으로 테스트할 수 있습니다. 다음은 HTTP 헤더 옵션을 사용하는 예입니다 (권장).

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

또는 쿼리 문자열 매개변수 옵션을 선택할 수도 있습니다.

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

액세스 토큰 갱신

액세스 토큰은 주기적으로 만료되어 관련 API 요청에 대해 잘못된 사용자 인증 정보가 됩니다. 토큰과 연결된 범위에 대한 오프라인 액세스를 요청한 경우 사용자에게 권한을 요청하지 않고 (사용자가 없는 경우 포함) 액세스 토큰을 새로고침할 수 있습니다.

액세스 토큰을 새로고침하기 위해 애플리케이션은 다음 매개변수를 포함하는 HTTPS POST 요청을 승인 서버 (https://oauth2.googleapis.com/token)로 전송합니다.

필드
client_id API Console에서 가져온 클라이언트 ID입니다.
client_secret API Console에서 가져온 클라이언트 보안 비밀번호 (Android, iOS 또는 Chrome 애플리케이션으로 등록된 클라이언트의 요청에는 client_secret 적용되지 않습니다.)
grant_type OAuth 2.0 사양에 정의된 대로 이 필드의 값을 refresh_token로 설정해야 합니다.
refresh_token 승인 코드 교환에서 반환된 갱신 토큰입니다.

다음 스니펫은 샘플 요청을 보여줍니다.

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

사용자가 애플리케이션에 부여된 액세스 권한을 취소하지 않는 한 토큰 서버는 새 액세스 토큰이 포함된 JSON 객체를 반환합니다. 다음 스니펫은 샘플 응답을 보여줍니다.

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

발급될 갱신 토큰 수에는 제한이 있습니다. 하나는 클라이언트/사용자 조합당 한 개이며, 다른 하나는 모든 클라이언트에서 사용자에게 적용됩니다. 갱신 토큰을 장기 저장소에 저장하고 유효한 기간 동안 계속 사용해야 합니다. 애플리케이션에서 갱신 토큰을 너무 많이 요청하면 이 한도에 도달할 수 있으며, 이러한 경우 이전 갱신 토큰이 작동하지 않습니다.

토큰 취소

때에 따라 사용자는 애플리케이션에 부여된 액세스 권한을 취소하려고 할 수 있습니다. 사용자는 계정 설정으로 이동하여 액세스 권한을 취소할 수 있습니다. 자세한 내용은 계정 액세스 권한이 있는 타사 사이트 및 앱 또는 사이트의 액세스 권한 삭제 섹션 지원 문서를 참고하세요.

애플리케이션이 지정된 액세스 권한을 프로그래매틱 방식으로 취소할 수도 있습니다. 사용자가 구독을 취소하거나 애플리케이션을 삭제하거나 앱에서 필요한 API 리소스가 크게 변경된 경우 프로그래매틱 해지가 중요합니다. 즉, 이전에 애플리케이션에 부여된 권한이 삭제되도록 하는 API 요청이 삭제 프로세스의 일부에 포함될 수 있습니다.

프로그래매틱 방식으로 토큰을 취소하기 위해 애플리케이션은 https://oauth2.googleapis.com/revoke을 요청하고 토큰을 매개변수로 포함합니다.

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

토큰은 액세스 토큰 또는 갱신 토큰일 수 있습니다. 토큰이 액세스 토큰이고 해당하는 갱신 토큰이 있으면 갱신 토큰도 취소됩니다.

취소가 성공적으로 처리된 경우 응답의 HTTP 상태 코드는 200입니다. 오류 조건에서는 HTTP 상태 코드 400이 오류 코드와 함께 반환됩니다.

추가 자료

네이티브 앱용 IETF 최신 권장사항(OAuth 2.0)에 여기서 설명하는 권장사항이 자세히 설명되어 있습니다.