이 문서에서는 휴대전화, 태블릿, 컴퓨터와 같은 기기에 설치된 애플리케이션이 Google의 OAuth 2.0 엔드포인트를 사용하여 Google API에 대한 액세스를 승인하는 방법을 설명합니다.
OAuth 2.0을 사용하면 사용자가 사용자 이름, 비밀번호, 기타 정보를 비공개로 유지하면서 특정 데이터를 애플리케이션과 공유할 수 있습니다. 예를 들어 애플리케이션은 OAuth 2.0을 사용하여 사용자로부터 Google Drive에 파일을 저장할 권한을 얻을 수 있습니다.
설치된 앱은 개별 기기에 배포되며 이러한 앱은 비밀을 유지할 수 없다고 가정됩니다. 사용자는 앱에 있는 동안 또는 앱이 백그라운드에서 실행 중일 때 Google API에 액세스할 수 있습니다.
이 승인 흐름은 웹 서버 애플리케이션에 사용되는 흐름과 유사합니다. 주요 차이점은 설치된 앱이 Google의 승인 서버의 응답을 처리하기 위해 시스템 브라우저를 열고 로컬 리디렉션 URI를 제공해야 한다는 점입니다.
대안
모바일 앱의 경우 Android 또는 iOS용 Google 로그인을 사용하는 것이 좋습니다. Google 로그인 클라이언트 라이브러리는 인증 및 사용자 승인을 처리하며, 여기에 설명된 하위 수준 프로토콜보다 구현하기가 더 간단할 수 있습니다.
시스템 브라우저를 지원하지 않거나 입력 기능이 제한된 기기(예: TV, 게임 콘솔, 카메라, 프린터)에서 실행되는 앱의 경우 TV 및 기기용 OAuth 2.0 또는 TV 및 제한된 입력 기기에서 로그인을 참고하세요.
라이브러리 및 샘플
이 문서에 설명된 OAuth 2.0 흐름을 구현하는 데 도움이 되는 다음 라이브러리와 샘플을 사용하는 것이 좋습니다.
- Android용 AppAuth 라이브러리
- iOS용 AppAuth 라이브러리
- 앱용 OAuth: Windows 샘플
기본 요건
프로젝트에 API 사용 설정
Google API를 호출하는 모든 애플리케이션은 API Console에서 이러한 API를 사용 설정해야 합니다.
프로젝트에 API를 사용 설정하려면 다음 단계를 따르세요.
- Google API Console의Open the API Library
- If prompted, select a project, or create a new one.
- API Library 에는 사용 가능한 모든 API가 제품군 및 인기도별로 분류되어 있습니다. 사용 설정하려는 API가 목록에 없는 경우 검색을 사용하여 찾거나 해당 API가 속한 제품군에서 모두 보기를 클릭합니다.
- 사용 설정하려는 API를 선택한 다음 사용 설정 버튼을 클릭합니다.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
승인 사용자 인증 정보 만들기
OAuth 2.0을 사용하여 Google API에 액세스하는 모든 애플리케이션에는 Google의 OAuth 2.0 서버에 애플리케이션을 식별하는 승인 사용자 인증 정보가 있어야 합니다. 다음 단계에서는 프로젝트의 사용자 인증 정보를 만드는 방법을 설명합니다. 그러면 애플리케이션에서 사용자 인증 정보를 사용하여 해당 프로젝트에 대해 사용 설정한 API에 액세스할 수 있습니다.
- Go to the Credentials page.
- 사용자 인증 정보 만들기 > OAuth 클라이언트 ID를 클릭합니다.
- 다음 섹션에서는 Google의 승인 서버에서 지원하는 클라이언트 유형을 설명합니다. 애플리케이션에 권장되는 클라이언트 유형을 선택하고 OAuth 클라이언트의 이름을 지정한 후 양식의 다른 입력란을 적절하게 설정합니다.
Android
- Android 애플리케이션 유형을 선택합니다.
- OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트의 Credentials page 에 표시되어 클라이언트를 식별합니다.
- Android 앱의 패키지 이름을 입력합니다. 이 값은 앱 매니페스트 파일의
<manifest>요소의package속성에 정의되어 있습니다. - 앱 배포의 SHA-1 서명 인증서 지문을 입력합니다.
- 앱에서 Google Play 앱 서명을 사용하는 경우 Play Console의 앱 서명 페이지에서 SHA-1 지문을 복사합니다.
- 자체 키 저장소와 서명 키를 관리하는 경우 Java에 포함된 keytool 유틸리티를 사용하여 사람이 읽을 수 있는 형식으로 인증서 정보를 출력합니다. keytool 출력의
Certificate fingerprints섹션에 있는SHA1값을 복사합니다. 자세한 내용은 Android용 Google API 문서의 클라이언트 인증을 참고하세요.
- (선택사항) Android 애플리케이션의 소유권을 확인합니다.
- 만들기를 클릭합니다.
iOS
- iOS 애플리케이션 유형을 선택합니다.
- OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트의 Credentials page 에 표시되어 클라이언트를 식별합니다.
- 앱의 번들 식별자를 입력합니다. 번들 ID는 앱의 정보 속성 목록 리소스 파일 (info.plist)에 있는 CFBundleIdentifier 키의 값입니다. 이 값은 일반적으로 Xcode 프로젝트 편집기의 일반 창 또는 서명 및 기능 창에 표시됩니다. 번들 ID는 Apple의 App Store Connect 사이트에서 앱의 앱 정보 페이지에 있는 일반 정보 섹션에도 표시됩니다.
앱 체크 기능을 사용하는 경우 번들 ID를 변경할 수 없으므로 앱에 올바른 번들 ID를 사용하고 있는지 확인하세요.
- (선택사항)
앱이 Apple App Store에 게시된 경우 앱의 App Store ID를 입력합니다. 스토어 ID는 모든 Apple App Store URL에 포함된 숫자 문자열입니다.
- iOS 또는 iPadOS 기기에서 Apple App Store 앱을 엽니다.
- 앱을 검색합니다.
- 공유 버튼 (정사각형 및 위쪽 화살표 기호)을 선택합니다.
- 링크 복사를 선택합니다.
- 텍스트 편집기에 링크를 붙여넣습니다. App Store ID는 URL의 마지막 부분입니다.
예:
https://apps.apple.com/app/google/id284815942
- (선택사항)
팀 ID를 입력합니다. 자세한 내용은 Apple 개발자 계정 문서의 팀 ID 찾기를 참고하세요.
참고: 클라이언트에 앱 체크를 사용 설정하는 경우 팀 ID 필드가 필요합니다. - (선택사항)
iOS 앱에 앱 체크를 사용 설정합니다. 앱 체크를 사용 설정하면 Apple의 App Attest 서비스가 OAuth 클라이언트에서 발생한 OAuth 2.0 요청이 진짜이며 앱에서 발생했는지 확인하는 데 사용됩니다. 이렇게 하면 앱 명의 도용 위험을 줄일 수 있습니다. iOS 앱에 앱 체크를 사용 설정하는 방법 자세히 알아보기
- 만들기를 클릭합니다.
UWP
- 범용 Windows 플랫폼 애플리케이션 유형을 선택합니다.
- OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트의 Credentials page 에 표시되어 클라이언트를 식별합니다.
- 앱의 12자리 Microsoft Store ID를 입력합니다. 이 값은 Microsoft 파트너 센터의 앱 관리 섹션에 있는 앱 ID 페이지에서 확인할 수 있습니다.
- 만들기를 클릭합니다.
UWP 앱의 경우 맞춤 URI 구성표는 39자(영문 기준) 이하여야 합니다.
액세스 범위 식별
범위를 사용 설정하면 애플리케이션은 필요한 리소스에 대한 액세스만 요청하고 사용자는 애플리케이션에 부여하는 액세스 양을 제어할 수 있습니다. 따라서 요청된 범위 수와 사용자 동의 얻을 가능성 사이에는 역관계가 있을 수 있습니다.
OAuth 2.0 승인을 구현하기 전에 앱에서 액세스 권한이 필요한 범위를 지정하는 것이 좋습니다.
OAuth 2.0 API 범위 문서에는 Google API에 액세스하는 데 사용할 수 있는 전체 범위 목록이 포함되어 있습니다.
OAuth 2.0 액세스 토큰 가져오기
다음 단계에서는 애플리케이션이 Google의 OAuth 2.0 서버와 상호작용하여 사용자를 대신하여 API 요청을 실행하기 위한 사용자의 동의를 얻는 방법을 보여줍니다. 애플리케이션이 사용자 승인이 필요한 Google API 요청을 실행하려면 동의를 받아야 합니다.
1단계: 코드 인증자 및 챌린지 생성
Google은 설치된 앱 흐름을 더 안전하게 만들기 위해 PKCE(코드 교환용 증명 키) 프로토콜을 지원합니다. 모든 승인 요청에 대해 고유한 코드 검사기가 생성되고 'code_challenge'라는 변환된 값이 승인 서버로 전송되어 승인 코드를 가져옵니다.
코드 검사기 만들기
code_verifier는 예약되지 않은 문자 [A-Z] / [a-z] / [0-9] / '-' / '.' / '_' / '~'을 사용하는 높은 엔트로피 암호화 무작위 문자열로, 최소 길이는 43자, 최대 길이는 128자입니다.
코드 검사기에는 값을 추측하는 것이 비현실적이 되도록 충분한 엔트로피가 있어야 합니다.
코드 챌린지 만들기
코드 챌린지를 만드는 두 가지 방법이 지원됩니다.
| 코드 챌린지 생성 방법 | |
|---|---|
| S256 (권장) | 코드 챌린지는 코드 검사기의 SHA256 해시를 Base64URL로 인코딩한 것입니다 (패딩 없음).
|
| plain | 코드 챌린지는 위에 생성된 코드 검사기와 동일한 값입니다.
|
2단계: Google OAuth 2.0 서버에 요청 전송
사용자 승인을 얻으려면 https://accounts.google.com/o/oauth2/v2/auth의 Google 승인 서버에 요청을 전송합니다. 이 엔드포인트는 활성 세션 조회를 처리하고 사용자를 인증하며 사용자 동의를 얻습니다. 엔드포인트는 SSL을 통해서만 액세스할 수 있으며 HTTP (SSL 아님) 연결은 거부합니다.
인증 서버는 설치된 애플리케이션에 대해 다음과 같은 쿼리 문자열 매개변수를 지원합니다.
| 매개변수 | |||||||
|---|---|---|---|---|---|---|---|
client_id |
필수
애플리케이션의 클라이언트 ID입니다. 이 값은 API Console Credentials page에서 확인할 수 있습니다. |
||||||
redirect_uri |
필수
Google의 승인 서버가 앱에 응답을 전송하는 방법을 결정합니다. 설치된 앱에 사용할 수 있는 리디렉션 옵션은 여러 가지가 있으며 특정 리디렉션 방법을 고려하여 승인 사용자 인증 정보를 설정합니다. 이 값은 클라이언트의 API Console
Credentials page에서 구성한 OAuth 2.0 클라이언트에 승인된 리디렉션 URI 중 하나와 정확하게 일치해야 합니다. 이 값이 승인된 URI와 일치하지 않으면 아래 표에는 각 메서드에 적절한
|
||||||
response_type |
필수
Google OAuth 2.0 엔드포인트가 승인 코드를 반환하는지 여부를 결정합니다. 설치된 애플리케이션의 매개변수 값을 |
||||||
scope |
필수
애플리케이션이 사용자를 대신하여 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위 목록입니다. 이러한 값은 Google에서 사용자에게 표시하는 동의 화면에 정보를 제공합니다. 범위를 사용 설정하면 애플리케이션은 필요한 리소스에 대한 액세스만 요청하고 사용자는 애플리케이션에 부여하는 액세스 양을 제어할 수 있습니다. 따라서 요청된 범위 수와 사용자 동의 얻을 가능성 사이에는 역관계가 있습니다. |
||||||
code_challenge |
권장
승인 코드 교환 중에 서버 측 챌린지로 사용될 인코딩된 |
||||||
code_challenge_method |
권장
승인 코드 교환 중에 사용될 |
||||||
state |
권장
애플리케이션이 인증 요청과 인증 서버의 응답 간에 상태를 유지하는 데 사용하는 문자열 값을 지정합니다.
서버는 사용자가 애플리케이션의 액세스 요청에 동의하거나 거부한 후 이 매개변수는 사용자를 애플리케이션의 올바른 리소스로 안내하고, nonce를 전송하고, 교차 사이트 요청 위조를 완화하는 등 다양한 목적으로 사용할 수 있습니다. |
||||||
login_hint |
선택사항
애플리케이션이 인증하려는 사용자를 알고 있는 경우 이 매개변수를 사용하여 Google 인증 서버에 힌트를 제공할 수 있습니다. 서버는 힌트를 사용하여 로그인 양식의 이메일 입력란을 미리 채우거나 적절한 멀티 로그인 세션을 선택하여 로그인 흐름을 간소화합니다. 매개변수 값을 사용자의 Google ID와 동일한 이메일 주소 또는 |
||||||
샘플 승인 URL
아래 탭에는 다양한 리디렉션 URI 옵션의 샘플 승인 URL이 표시됩니다.
URL은 redirect_uri 매개변수의 값을 제외하고 동일합니다. URL에는 필수 response_type 및 client_id 매개변수와 선택적 state 매개변수도 포함됩니다. 각 URL에는 가독성을 위해 줄바꿈과 공백이 포함되어 있습니다.
커스텀 URI 스킴
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& 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=email%20profile& 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에서 사용자에게 동의 메시지 표시
이 단계에서 사용자는 애플리케이션에 요청된 액세스 권한을 부여할지 결정합니다. 이 단계에서 Google은 애플리케이션의 이름과 사용자의 승인 사용자 인증 정보에 대한 액세스 권한을 요청하는 Google API 서비스, 부여할 액세스 범위의 요약을 보여주는 동의 창을 표시합니다. 그러면 사용자는 애플리케이션에서 요청한 하나 이상의 범위에 대한 액세스 권한을 부여하는 데 동의하거나 요청을 거부할 수 있습니다.
이 단계에서 애플리케이션은 액세스 권한이 부여되었는지 나타내는 Google OAuth 2.0 서버의 응답을 기다리므로 아무것도 할 필요가 없습니다. 이 응답은 다음 단계에서 설명합니다.
오류
Google의 OAuth 2.0 승인 엔드포인트에 대한 요청이 예상되는 인증 및 승인 흐름 대신 사용자 대상 오류 메시지를 표시할 수 있습니다. 일반적인 오류 코드와 권장 해결 방법은 다음과 같습니다.
admin_policy_enforced
Google 계정이 Google Workspace 관리자의 정책으로 인해 요청된 하나 이상의 범위를 승인할 수 없습니다. 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 동의 화면 설정 도움말의 사용자 유형 섹션을 참고하세요.
invalid_grant
코드 인증자 및 챌린지를 사용하는 경우 code_callenge 매개변수가 잘못되었거나 누락되었습니다. code_challenge 매개변수가 올바르게 설정되어 있는지 확인합니다.
액세스 토큰을 갱신할 때 토큰이 만료되었거나 무효화되었을 수 있습니다. 사용자를 다시 인증하고 새 토큰을 가져오기 위해 사용자의 동의를 요청합니다. 이 오류가 계속 표시되면 애플리케이션이 올바르게 구성되었는지, 요청에 올바른 토큰과 매개변수를 사용하고 있는지 확인하세요. 그렇지 않으면 사용자 계정이 삭제되었거나 사용 중지되었을 수 있습니다.
redirect_uri_mismatch
승인 요청에 전달된 redirect_uri가 OAuth 클라이언트 ID의 승인된 리디렉션 URI와 일치하지 않습니다. Google API Console Credentials page에서 승인된 리디렉션 URI를 검토합니다.
전달된 redirect_uri가 클라이언트 유형에 유효하지 않을 수 있습니다.
redirect_uri 매개변수는 지원 중단되었으며 더 이상 지원되지 않는 OAuth 대역 외 (OOB) 흐름을 참조할 수 있습니다. 이전 가이드를 참고하여 통합을 업데이트하세요.
invalid_request
요청에 문제가 있습니다. 다음과 같은 여러 가지 이유로 이 문제가 발생할 수 있습니다.
- 요청 형식이 올바르지 않음
- 요청에 필수 매개변수가 누락되었습니다.
- 요청에서 Google에서 지원하지 않는 승인 방법을 사용합니다. OAuth 통합에서 권장되는 통합 방법을 사용하는지 확인
- 리디렉션 URI에 맞춤 스킴이 사용됨 : Chrome 앱에서 맞춤 URI 스킴이 지원되지 않음 또는 Android 클라이언트에 맞춤 URI 스킴이 사용 설정되지 않음 오류 메시지가 표시되면 Chrome 앱에서 지원되지 않고 Android에서 기본적으로 사용 중지된 맞춤 URI 스킴을 사용하고 있는 것입니다. 커스텀 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 |
API Console Credentials page에서 가져온 클라이언트 보안 비밀번호입니다. |
code |
초기 요청에서 반환된 승인 코드입니다. |
code_verifier |
1단계에서 만든 코드 검사기 |
grant_type |
OAuth 2.0 사양에 정의된 대로 이 필드의 값은 authorization_code로 설정해야 합니다. |
redirect_uri |
지정된 client_id의 API Console
Credentials 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 범위가 포함된 경우에만 반환됩니다. 값은 사용자에 대한 디지털 서명된 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 https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
6단계: 사용자가 부여한 범위 확인하기
한 번에 여러 범위를 요청하면 사용자가 앱에서 요청하는 모든 범위를 부여하지 않을 수 있습니다. 앱은 항상 사용자가 부여한 범위를 확인하고 관련 기능을 사용 중지하여 범위 거부를 처리해야 합니다. 자세한 내용은 세분화된 권한을 처리하는 방법을 참고하세요.
사용자가 애플리케이션에 특정 범위에 대한 액세스 권한을 부여했는지 확인하려면 액세스 토큰 응답의 scope 필드를 검사합니다. access_token에 의해 부여된 액세스 범위로, 공백으로 구분되고 대소문자가 구분되는 문자열 목록으로 표현됩니다.
예를 들어 다음 샘플 액세스 토큰 응답은 사용자가 애플리케이션에 읽기 전용 Drive 활동 및 Calendar 일정 권한에 대한 액세스 권한을 부여했음을 나타냅니다.
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Google API 호출
애플리케이션이 액세스 토큰을 획득한 후 API에 필요한 액세스 범위가 부여된 경우 이 토큰을 사용하여 지정된 사용자 계정을 대신하여 Google API를 호출할 수 있습니다. 이렇게 하려면 access_token 쿼리 매개변수 또는 Authorization HTTP 헤더 Bearer 값을 포함하여 API 요청에 액세스 토큰을 포함합니다. 가능하면 HTTP 헤더를 사용하는 것이 좋습니다. 쿼리 문자열은 서버 로그에 표시되는 경향이 있기 때문입니다. 대부분의 경우 클라이언트 라이브러리를 사용하여 Google API 호출을 설정할 수 있습니다 (예: Drive Files API를 호출하는 경우).
OAuth 2.0 플레이그라운드에서 모든 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 요청을 Google의 승인 서버 (https://oauth2.googleapis.com/token)로 전송합니다.
| 필드 | |
|---|---|
client_id |
API Console에서 가져온 클라이언트 ID입니다. |
client_secret |
API Console에서 가져온 클라이언트 보안 비밀입니다.
(client_secret는 Android, iOS 또는 Chrome 애플리케이션으로 등록된 클라이언트의 요청에는 적용되지 않습니다.)
|
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 https://www.googleapis.com/auth/calendar.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가 오류 코드와 함께 반환됩니다.
앱 리디렉션 방법
맞춤 URI 스킴 (Android, iOS, UWP)
맞춤 URI 스키마는 맞춤 정의 스키마를 사용하여 앱을 여는 딥 링크의 한 형태입니다.
Android에서 커스텀 URI 스킴을 사용하는 대안
OAuth 2.0 응답을 앱에 직접 전송하여 리디렉션 URI가 필요하지 않은 Android용 Google 로그인 SDK를 사용하세요.
Android용 Google 로그인 SDK로 이전하는 방법
Android에서 OAuth 통합에 맞춤 스키마를 사용하는 경우 권장되는 Android용 Google Sign-In SDK 사용으로 완전히 이전하려면 다음 작업을 완료해야 합니다.
- Google 로그인 SDK를 사용하도록 코드를 업데이트합니다.
- Google API 콘솔에서 맞춤 스키마 지원을 사용 중지합니다.
Google 로그인 Android SDK로 이전하려면 다음 단계를 따르세요.
-
Google 로그인 Android SDK를 사용하도록 코드를 업데이트합니다.
-
코드를 검토하여 Google OAuth 2.0 서버에 요청을 전송하는 위치를 확인합니다. 맞춤 스키마를 사용하는 경우 요청은 다음과 같습니다.
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect는 위 예시의 맞춤 스킴 리디렉션 URI입니다. 맞춤 URI 스킴 값의 형식에 관한 자세한 내용은redirect_uri매개변수 정의를 참고하세요. -
Google 로그인 SDK를 구성하는 데 필요한
scope및client_id요청 매개변수를 기록합니다. -
Android 앱에 Google 로그인 통합 시작하기 안내에 따라 SDK를 설정합니다. 이전 단계에서 가져온
client_id를 재사용하므로 백엔드 서버의 OAuth 2.0 클라이언트 ID 가져오기 단계를 건너뛸 수 있습니다. -
서버 측 API 액세스 사용 설정 안내를 따릅니다. 이 작업에는 다음 단계가 포함됩니다.
-
getServerAuthCode메서드를 사용하여 권한을 요청하는 범위의 승인 코드를 가져옵니다. - 인증 코드를 앱의 백엔드로 전송하여 액세스 및 갱신 토큰으로 교환합니다.
- 가져온 액세스 토큰을 사용하여 사용자를 대신하여 Google API를 호출합니다.
-
-
코드를 검토하여 Google OAuth 2.0 서버에 요청을 전송하는 위치를 확인합니다. 맞춤 스키마를 사용하는 경우 요청은 다음과 같습니다.
-
Google API 콘솔에서 맞춤 스키마 지원을 사용 중지합니다.
- OAuth 2.0 사용자 인증 정보 목록으로 이동하여 Android 클라이언트를 선택합니다.
- 고급 설정 섹션으로 이동하여 커스텀 URI 스킴 사용 설정 체크박스를 선택 해제하고 저장을 클릭하여 맞춤 URI 스킴 지원을 사용 중지합니다.
커스텀 URI 스킴 사용 설정
권장 대안이 작동하지 않는 경우 아래 안내에 따라 Android 클라이언트에 맞춤 URI 스킴을 사용 설정할 수 있습니다.- OAuth 2.0 사용자 인증 정보 목록으로 이동하여 Android 클라이언트를 선택합니다.
- 고급 설정 섹션으로 이동하여 커스텀 URI 스킴 사용 설정 체크박스를 선택하고 저장을 클릭하여 커스텀 URI 스킴 지원을 사용 설정합니다.
Chrome 앱에서 커스텀 URI 스킴을 사용하는 대안
OAuth 2.0 응답을 앱에 직접 전송하여 리디렉션 URI가 필요하지 않도록 하는 Chrome Identity API를 사용합니다.
루프백 IP 주소 (macOS, Linux, Windows 데스크톱)
이 URL을 사용하여 승인 코드를 수신하려면 애플리케이션이 로컬 웹 서버에서 수신 대기 중이어야 합니다. 이는 일부 플랫폼에서만 가능합니다. 하지만 플랫폼에서 지원하는 경우 승인 코드를 가져오는 데 권장되는 메커니즘입니다.
앱이 승인 응답을 수신하면 최적의 사용성을 위해 사용자에게 브라우저를 닫고 앱으로 돌아가도록 안내하는 HTML 페이지를 표시하여 응답해야 합니다.
| 권장 사용 사례 | macOS, Linux, Windows 데스크톱 (범용 Windows 플랫폼 앱 제외) 앱 |
| 양식 값 | 애플리케이션 유형을 데스크톱 앱으로 설정합니다. |
수동 복사/붙여넣기 (지원 중단됨)
앱 보호
앱 소유권 확인 (Android, Chrome)
애플리케이션의 소유권을 확인하여 앱 명의 도용 위험을 줄일 수 있습니다.
Android
인증 절차를 완료하려면 Google Play 개발자 계정이 있고 앱이 Google Play Console에 등록된 경우 이 계정을 사용하면 됩니다. 인증을 완료하려면 다음 요구사항을 충족해야 합니다.
- Google Play Console에 확인을 완료하려는 Android OAuth 클라이언트와 동일한 패키지 이름 및 SHA-1 서명 인증서 지문이 있는 등록된 애플리케이션이 있어야 합니다.
- Google Play Console에서 앱에 대한 관리자 권한이 있어야 합니다. Google Play Console의 액세스 관리에 대해 자세히 알아보세요.
Android 클라이언트의 앱 소유권 확인 섹션에서 소유권 확인 버튼을 클릭하여 인증 절차를 완료합니다.
인증에 성공하면 인증 프로세스의 성공을 확인하는 알림이 표시됩니다. 그렇지 않으면 오류 메시지가 표시됩니다.
인증 실패를 해결하려면 다음을 시도해 보세요.
- 확인하려는 앱이 Google Play Console에 등록된 앱인지 확인합니다.
- Google Play Console에서 앱에 대한 관리자 권한이 있는지 확인합니다.
Chrome
인증 절차를 완료하려면 Chrome 웹 스토어 개발자 계정을 사용합니다. 인증을 완료하려면 다음 요구사항을 충족해야 합니다.
- 인증을 완료하려는 Chrome 확장 프로그램 OAuth 클라이언트와 동일한 항목 ID를 가진 항목이 Chrome 웹 스토어 개발자 대시보드에 등록되어 있어야 합니다.
- Chrome 웹 스토어 항목의 게시자여야 합니다. Chrome 웹 스토어 개발자 대시보드에서 액세스 관리에 대해 자세히 알아보세요.
Chrome 확장 프로그램 클라이언트의 앱 소유권 확인 섹션에서 소유권 확인 버튼을 클릭하여 확인 절차를 완료합니다.
참고: 계정에 액세스 권한을 부여한 후 인증 프로세스를 완료하기 전에 몇 분 정도 기다립니다.
인증에 성공하면 인증 프로세스의 성공을 확인하는 알림이 표시됩니다. 그렇지 않으면 오류 메시지가 표시됩니다.
인증 실패를 해결하려면 다음을 시도해 보세요.
앱 체크 (iOS만 해당)
앱 체크 기능은 Apple의 App Attest 서비스를 사용하여 Google OAuth 2.0 엔드포인트에 대한 요청이 인증된 애플리케이션에서 발생했는지 확인함으로써 iOS 애플리케이션을 무단 사용으로부터 보호하는 데 도움이 됩니다. 이렇게 하면 앱 명의 도용 위험을 줄일 수 있습니다.
iOS 클라이언트에 앱 체크 사용 설정
iOS 클라이언트에 앱 체크를 사용 설정하려면 다음 요구사항을 충족해야 합니다.- iOS 클라이언트의 팀 ID를 지정해야 합니다.
- 번들 ID에 와일드 카드를 사용하면 두 개 이상의 앱으로 확인될 수 있으므로 와일드 카드를 사용해서는 안 됩니다. 즉, 번들 ID에 별표 (*) 기호를 포함해서는 안 됩니다.
앱 체크를 사용 설정하면 OAuth 클라이언트의 수정 뷰에 클라이언트의 OAuth 요청과 관련된 측정항목이 표시됩니다. 앱 체크를 적용할 때까지는 확인되지 않은 소스의 요청이 차단되지 않습니다. 측정항목 모니터링 페이지의 정보를 통해 시정 조치를 시작할 시기를 결정할 수 있습니다.
iOS 앱에 App Check를 사용 설정할 때 App Check 기능과 관련된 오류가 표시될 수 있습니다. 이러한 오류를 수정하려면 다음을 시도해 보세요.
- 지정한 번들 ID와 팀 ID가 유효한지 확인합니다.
- 번들 ID에 와일드 카드를 사용하고 있지 않은지 확인합니다.
iOS 클라이언트에 앱 체크 적용
앱에 앱 체크를 사용 설정한다고 해서 인식되지 않는 요청이 자동으로 차단되지는 않습니다. 이 보호 조치를 적용하려면 iOS 클라이언트의 수정 뷰로 이동하세요. 페이지 오른쪽의 iOS용 Google ID 섹션에 앱 체크 측정항목이 표시됩니다. 이 측정항목에는 다음 정보가 포함됩니다.- 확인된 요청 수: 유효한 앱 체크 토큰이 있는 요청입니다. 앱 체크 적용을 사용 설정하면 이 카테고리의 요청만 성공합니다.
- 확인되지 않은 요청 수: 오래된 클라이언트 요청일 수 있음 - 앱 체크 토큰이 누락된 요청입니다. 이러한 요청은 앱 체크 구현이 포함되지 않은 이전 버전의 앱에서 전송되었을 수 있습니다.
- 확인되지 않은 요청 수: 알 수 없는 출처 요청 - 앱에서 전송된 것으로 보이지 않고 앱 체크 토큰이 없는 요청입니다.
- 확인되지 않은 요청 수: 잘못된 요청 - 앱을 가장하려는 허위 클라이언트 또는 에뮬레이션된 환경에서 전송되었을 수 있는 잘못된 앱 체크 토큰이 포함된 요청
App Check를 적용하려면 ENFORCE 버튼을 클릭하고 선택한 내용을 확인합니다. 적용이 활성화되면 클라이언트의 확인되지 않은 모든 요청이 거부됩니다.
참고: 적용을 사용 설정한 후 변경사항이 적용되기까지 최대 15분이 걸릴 수 있습니다.
iOS 클라이언트의 앱 체크 적용 해제
앱에 앱 체크를 적용 해제하면 시정 조치가 중지되고 확인되지 않은 요청을 포함하여 클라이언트에서 Google OAuth 2.0 엔드포인트로 전송되는 모든 요청이 허용됩니다.
iOS 클라이언트의 App Check를 적용 해제하려면 iOS 클라이언트의 수정 뷰로 이동하여 UNENFORCE 버튼을 클릭하고 선택사항을 확인합니다.
참고: App Check 적용을 해제한 후 변경사항이 적용되기까지 최대 15분이 걸릴 수 있습니다.
iOS 클라이언트의 앱 체크 사용 중지
앱에서 앱 체크를 사용 중지하면 모든 앱 체크 모니터링 및 시정 조치가 중지됩니다. 클라이언트의 측정항목을 계속 모니터링할 수 있도록 앱 체크를 시정 조치하지 않도록 하는 것이 좋습니다.
iOS 클라이언트에서 앱 체크를 사용 중지하려면 iOS 클라이언트의 수정 뷰로 이동하여 Firebase 앱 체크를 사용해 OAuth 클라이언트가 악용되지 않도록 보호 전환 버튼을 사용 중지합니다.
참고: 앱 체크를 사용 중지한 후 변경사항이 적용되기까지 최대 15분이 걸릴 수 있습니다.
추가 자료
IETF 권장사항 네이티브 앱용 OAuth 2.0에서는 여기에 설명된 많은 권장사항을 수립합니다.
계정 간 보안 구현
사용자 계정을 보호하기 위해 취해야 할 추가 조치는 Google의 교차 계정 보호 서비스를 활용하여 교차 계정 보호를 구현하는 것입니다. 이 서비스를 사용하면 사용자 계정의 주요 변경사항에 관한 정보를 애플리케이션에 제공하는 보안 이벤트 알림을 구독할 수 있습니다. 그런 다음 이 정보를 사용하여 이벤트에 응답하는 방법에 따라 조치를 취할 수 있습니다.
Google의 교차 계정 보호 서비스에서 앱으로 전송하는 이벤트 유형의 예는 다음과 같습니다.
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
계정 간 보안을 구현하는 방법과 사용 가능한 이벤트의 전체 목록에 관한 자세한 내용은 계정 간 보안으로 사용자 계정 보호하기 페이지 를 참고하세요.