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

참고: OAuth 2.0을 처음 사용하는 경우 시작하기 전에 OAuth 2.0 개요를 살펴보세요. 이 개요에는 Google에서 지원하는 OAuth 2.0 흐름이 요약되어 있어 애플리케이션에 적합한 흐름을 선택했는지 확인하세요.

이 문서에서는 스마트폰, 태블릿, 기기, 운영체제와 같은 기기에 설치된 애플리케이션을 컴퓨터는 Google의 OAuth 2.0 엔드포인트를 사용하여 Google API

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

설치된 앱은 개별 기기에 배포되며, 이러한 앱은 보안은 비밀을 지킬 수 없습니다 사용자가 앱에 있는 동안 또는 사용자가 있을 때 Google API에 액세스할 수 있습니다. 앱이 백그라운드에서 실행되고 있는지 확인합니다.

이 승인 흐름은 웹 서버 애플리케이션입니다. 가장 큰 차이점은 이러한 요청을 처리하기 위해 시스템 브라우저를 열고 로컬 리디렉션 URI를 Google 인증 서버에서 보내는 응답입니다.

대안

모바일 앱의 경우 Android 또는 iOS Google 로그인 클라이언트 라이브러리는 인증 및 사용자 승인을 처리하며, 구현될 가능성이 더 높습니다.

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

라이브러리 및 샘플

OAuth 2.0 흐름을 구현하는 데 도움이 되는 다음 라이브러리와 샘플을 사용하는 것이 좋습니다. 다음 사항을 참조하세요.

• Android용 AppAuth 라이브러리
• iOS용 AppAuth 라이브러리
• 앱용 OAuth: Windows 샘플

기본 요건

프로젝트에 API 사용 설정

Google API를 호출하는 모든 애플리케이션은 API Console

프로젝트에 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가 목록에 표시되지 않으면 검색을 사용하여 제품을 찾거나 제품이 속한 제품군에서 모두 보기를 클릭합니다.
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에서 제공하는 클라이언트 유형과 리디렉션 방법을 설명합니다. 있습니다. 캠페인에 권장되는 클라이언트 유형을 선택하세요. 애플리케이션의 이름을 지정하고 양식의 다른 필드를 있습니다.

Android

1. Android 애플리케이션 유형을 선택합니다.
2. OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트의 Credentials page 클라이언트 식별
3. Android 앱의 패키지 이름을 입력합니다. 이 값은 <manifest> 요소의 package 속성 앱 매니페스트 파일에 있습니다.
4. 앱 배포의 SHA-1 서명 인증서 지문을 입력합니다.
   • 앱에서 Google Play 앱 서명을 사용하려면 SHA-1을 복사합니다. Play Console 앱 서명 페이지의 디지털 지문입니다.
   • 자체 키 저장소와 서명 키를 관리하는 경우 keytool 유틸리티를 사용합니다. 인증서 정보를 사람이 읽을 수 있는 형식으로 인쇄하기 위해 Java에 포함되어 있습니다. 이 SHA1 값을 Certificate fingerprints 섹션에 있는 keytool 출력 자세한 내용은 클라이언트 인증 Android용 Google API 문서를 참조하세요.
5. (선택사항) Android 소유권 확인 애플리케이션입니다.
6. 만들기를 클릭합니다.

iOS

1. iOS 애플리케이션 유형을 선택합니다.
2. OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트의 Credentials page 클라이언트 식별
3. 앱의 번들 식별자를 입력합니다. 번들 ID는 CFBundleIdentifier 키를 설정합니다 (info.plist). 값은 일반 창이나 서명 및 Google Cloud 콘솔의 Xcode 프로젝트 편집기 번들 ID는 앱의 앱 정보 페이지 Apple의 App Store Connect 사이트를 참고하세요.
4. (선택사항)

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

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

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

5. (선택사항)

   팀 ID를 입력합니다. 자세한 내용은 팀 ID 찾기 를 참조하세요.

6. 만들기를 클릭합니다.

UWP

1. 범용 Windows 플랫폼 애플리케이션 유형을 선택합니다.
2. OAuth 클라이언트의 이름을 입력합니다. 이 이름은 프로젝트의 Credentials page 클라이언트 식별
3. 앱의 12자 Microsoft Store ID를 입력합니다. 이 값은 Microsoft 파트너 센터 에 앱 ID 앱 관리 섹션의 페이지로 이동하세요.
4. 만들기를 클릭합니다.

UWP 앱의 경우 커스텀 URI 스킴은 39자(영문 기준) 이하여야 합니다.

커스텀 URI 스킴 (Android, iOS, UWP)

커스텀 URI 스킴은 딥 링크의 한 형태로서 맞춤 정의된 스키마를 사용하여 앱을 엽니다.

중요: 맞춤 URI 스킴은 새 Chrome 앱에서 더 이상 지원되지 않으며 앱 명의 도용 위험이 있으므로 신규 Android 클라이언트에서 기본적으로 사용 중지됩니다.

Android에서 커스텀 URI 스킴을 사용하지 않는 대안

사용 Android용 Google 로그인 SDK 앱에 직접 OAuth 2.0 응답을 제공하므로 리디렉션 URI를 사용할 수 있습니다.

Android용 Google 로그인 SDK로 이전하는 방법

현재 Android에서 OAuth 통합에 맞춤 스키마를 사용하고 있다면 계정에 권장되는 Google 로그인을 사용하도록 완전히 이전하려면 아래 작업을 완료하세요. Android SDK:

1. Google 로그인 SDK를 사용하도록 코드를 업데이트하세요.
2. Google API 콘솔에서 맞춤 스키마 지원을 사용 중지합니다.

참고: 채택 시간을 고려하여 코드 업데이트를 완료하고 배포해야 합니다. 기존 사용자 기반 또는 이전 기기)에서 맞춤 스키마에 대한 지원을 사용 중지하기 전에 Google API 콘솔에서 사용자가 invalid_request 오류 메시지 앱을 사용할 때 발생합니다.

Google 로그인 Android SDK로 이전하려면 다음 단계를 따르세요.

1. Google 로그인 Android SDK를 사용하도록 코드를 업데이트합니다.
   1. 코드를 검사하여 현재 위치 식별 Google의 OAuth 2.0 서버에 요청 전송 커스텀 스키마를 사용하는 경우 요청이 다음과 같이 표시됩니다. <ph type="x-smartling-placeholder">

        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>
        

      </ph> com.example.app:/oauth2redirect는 예로 들 수 있습니다 자세한 내용은 형식에 대한 자세한 내용은 redirect_uri 매개변수 정의를 참조하세요. 커스텀 URI 스킴 값입니다.
   2. scope 및 client_id 요청 매개변수를 기록해 둡니다. Google 로그인 SDK를 구성해야 합니다.
      참고: 서드 파티 라이브러리를 사용하는 경우 라이브러리의 이 정보를 찾을 수 있습니다.
   3. Android 앱에 Google 로그인 통합 시작하기 안내에 따라 SDK를 설정하세요. 이 재사용할 때와 마찬가지로 백엔드 서버의 OAuth 2.0 클라이언트 ID 가져오기 단계를 수행합니다. 이전 단계에서 가져온 client_id입니다.
   4. 서버 측 API 액세스 사용 설정 참조하세요. 여기에는 다음 단계가 포함됩니다.
      1. getServerAuthCode 메서드를 사용하여 다음에 대한 인증 코드를 검색합니다. 권한을 요청할 범위입니다.
      2. 앱의 백엔드로 인증 코드를 전송하여 액세스 및 새로고침 토큰입니다.
      3. 가져온 액세스 토큰을 사용하여 사용자 대신 Google API를 호출합니다.
      참고: 애플리케이션에 오프라인 액세스가 필요하지 않은 경우 이 안내를 따르세요.
2. Google API 콘솔에서 맞춤 스키마 지원을 중지합니다.
   1. OAuth 2.0 사용자 인증 정보 Android 클라이언트를 선택합니다.
   2. 고급 설정 섹션으로 이동하여 커스텀 URI 스킴 사용 설정 체크박스를 선택한 다음 저장을 클릭하여 커스텀 URI 스킴 지원을 중지합니다.

커스텀 URI 스킴 사용 설정

권장되는 다른 방법이 효과가 없다면 다음 안내에 따라 Android 클라이언트를 실행합니다.

1. OAuth 2.0 사용자 인증 정보 목록 및 Android 클라이언트를 선택합니다.
2. 고급 설정 섹션으로 이동하여 커스텀 URI 스킴 사용 설정 체크박스를 선택한 다음 저장을 클릭하여 사용 설정합니다. 커스텀 URI 스킴 지원을 제공합니다.

Chrome 앱에서 커스텀 URI 스킴을 사용하지 않는 대안

사용 Chrome ID API 앱에 직접 OAuth 2.0 응답을 제공하므로 리디렉션 URI를 사용할 수 있습니다.

앱 소유권 확인 (Android, Chrome)

애플리케이션의 소유권을 확인하여 앱 명의 도용의 위험을 줄일 수 있습니다.

Android

참고: Android 앱 소유권 확인은 현재 Google Play에서만 사용할 수 있습니다. 있습니다.

인증 절차를 완료하려면 Google Play 개발자 계정을 사용하세요. Google Play 스토어 앱이 있고 앱이 Google Play Console 다음 인증을 완료하려면 다음 요구사항을 충족해야 합니다.

• Google Play Console에 동일한 이름의 등록된 애플리케이션이 있어야 합니다. 패키지 이름 및 SHA-1 서명 인증서 지문을 Android OAuth 클라이언트로 확인할 수 있습니다
• 다음에서 앱에 대한 관리자 권한이 있어야 합니다. Google Play Console 자세히 알아보기 자세히 알아보세요.

Android 클라이언트의 Verify App Ownership(앱 소유권 확인) 섹션에서 소유권 확인 버튼을 클릭하여 인증 절차를 완료합니다.

확인이 완료되면 완료를 확인하는 알림이 표시됩니다. 다음 단계를 따르세요. 그렇지 않으면 오류 메시지가 표시됩니다.

인증 실패 문제를 해결하려면 다음을 시도해 보세요.

• 확인하려는 앱이 Google Play Console에 등록된 앱인지 확인합니다.
• 다음에서 앱에 대한 관리자 권한이 있는지 Google Play Console

Chrome

인증 절차를 완료하려면 Chrome 웹 스토어 개발자 계정을 사용해야 합니다. 인증을 완료하려면 다음 요구사항을 충족해야 합니다.

• 에 등록된 아이템이 Chrome 웹 스토어 개발자 대시보드 Chrome 확장 프로그램 OAuth 클라이언트와 동일한 항목 ID를 사용해야 합니다. 확인할 수 있습니다
• Chrome 웹 스토어 항목의 게시자여야 합니다. 자세히 알아보기 에 대해 자세히 알아보세요.

Chrome 확장 프로그램 클라이언트의 앱 소유권 확인 섹션에서 다음을 클릭합니다. 소유권 확인 버튼을 클릭하여 확인 절차를 완료합니다.

참고: 인증 절차를 완료하려면 몇 분 정도 기다린 후 권한을 부여할 수 있습니다.

확인이 완료되면 완료를 확인하는 알림이 표시됩니다. 다음 단계를 따르세요. 그렇지 않으면 오류 메시지가 표시됩니다.

인증 실패 문제를 해결하려면 다음을 시도해 보세요.

• Chrome 웹 스토어 개발자 대시보드에 Chrome 확장 프로그램 OAuth 클라이언트와 동일한 항목 ID를 사용해야 합니다.
• 앱의 게시자인지 확인합니다. 개별 게시자이거나 앱 그룹 게시자 또는 앱 그룹 게시자의 구성원입니다. 자세히 알아보기 에 대해 자세히 알아보세요.
• 그룹 게시자 목록을 방금 업데이트한 경우 그룹 게시자 멤버십이 있는지 확인하세요. Chrome 웹 스토어 개발자 대시보드에서 동기화됩니다. 자세히 알아보기 게시자 멤버십 목록 동기화에 대해 자세히 알아보세요.

루프백 IP 주소 (macOS, Linux, Windows 데스크톱)

중요: 루프백 IP 주소 리디렉션 옵션은 Android, Chrome 앱, iOS OAuth 클라이언트 유형에서 지원 중단되었습니다. 루프백 IP 검토 주소 이전 가이드를 참고하세요.

이 URL을 사용하여 승인 코드를 받으려면 애플리케이션이 로컬 웹 서버입니다 이는 많은 플랫폼에서 가능한 것은 아니지만 모든 플랫폼에서 가능합니다. 하지만 플랫폼에서 이는 승인 코드를 가져오기 위한 권장 메커니즘입니다.

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

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

참고: redirect_uri 매개변수 정의 루프백 IP 주소에 대해 자세히 알아볼 수 있습니다 또한 루프백 IP 대신 localhost를 사용하지만 이 구성은 다음과 같은 문제를 일으킬 수 있습니다. 클라이언트 방화벽을 설치합니다 전부는 아니지만 대부분의 방화벽은 루프백 통신을 허용합니다.

직접 복사/붙여넣기

중요: 수동 복사/붙여넣기 옵션( OOB (대역 외) 리디렉션 방법으로 더 이상 지원되지 않습니다. OOB 이전 가이드를 검토합니다. 를 참조하세요.

액세스 범위 식별

범위를 사용 설정하면 애플리케이션이 필요한 리소스에 대한 액세스만 요청할 수 있으며 사용자가 애플리케이션에 부여하는 액세스 수준을 제어할 수 있게 해줍니다. 따라서 요청된 범위 수와 사용자 동의 획득

OAuth 2.0 승인을 구현하기 전에 해당 범위를 식별하는 것이 좋습니다. 앱에 액세스 권한이 있어야 합니다

참고: 증분 승인은 설치된 앱 또는 제공합니다.

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

공개 애플리케이션이 인증 프로세스를 완료해야 합니다. 확인되지 않음 앱이 화면에 표시되는 경우 관련 서류를 제출해야 합니다. 인증 요청을 하여 삭제합니다. 자세히 알아보기: 인증되지 않은 앱 에 대한 답변을 얻을 수 있습니다. 고객센터의 앱 인증 관련 자주 묻는 질문(FAQ)을 확인하세요.

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 (권장)	코드 챌린지는 코드의 Base64URL (패딩 없음)으로 인코딩된 SHA256 해시입니다. 인증 기관입니다. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
일반	코드 챌린지는 위에서 생성된 코드 인증자와 동일한 값입니다. code_challenge = code_verifier

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

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

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

매개변수
client_id	필수 애플리케이션의 클라이언트 ID입니다. 이 값은 API Console Credentials page입니다.
redirect_uri	필수 Google 인증 서버가 앱에 응답을 보내는 방법을 결정합니다. 현재 몇 가지 리디렉션 옵션을 사용할 수 있으며, 특정 리디렉션 방법이 있는 승인 사용자 인증 정보 염두에 두세요. 값은 OAuth 2.0에 대해 승인된 리디렉션 URI 중 하나와 정확히 일치해야 합니다. GCP 콘솔에서 생성한 API Console Credentials page입니다. 이 값이 redirect_uri_mismatch 오류가 발생합니다. 아래 표에서는 다음에 적합한 redirect_uri 매개변수 값을 보여줍니다. 다음과 같습니다. redirect_uri 값 커스텀 URI 스킴 com.example.app:redirect_uri_path 또는 com.googleusercontent.apps.123:redirect_uri_path com.example.app는 관리할 수 있습니다. 맞춤 스키마에 유효하려면 마침표가 있어야 합니다. com.googleusercontent.apps.123는 클라이언트 ID를 찾습니다. redirect_uri_path는 선택적 경로 구성요소입니다. 예를 들면 다음과 같습니다. /oauth2redirect입니다. 경로는 단일 슬래시를 사용합니다. 참고 : 맞춤 URI 스킴은 Chrome 앱에서 더 이상 지원되지 않으며 Android에서는 기본적으로 사용 중지되어 있습니다. 자세히 알아보기 Android 및 Chrome 앱용 맞춤 스키마 대안에 대한 정보 루프백 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_method의 값 다음을 포함하는 요청에 없으면 기본값은 plain입니다. code_challenge입니다. 이 매개변수에 지원되는 유일한 값은 S256 또는 plain
state	권장 애플리케이션이 승인 요청 및 승인 서버의 응답을 나타냅니다. 서버는 name=value 쌍으로 전송하는 정확한 값을 URL 부분 식별자 (#) 의 redirect_uri 사용자가 애플리케이션의 액세스할 수 있습니다. 이 매개변수는 사용자를 nonce 전송, 교차 사이트 요청 완화 등 애플리케이션의 올바른 리소스 사용 있습니다. state를 사용하여 redirect_uri을 추측할 수 있으므로 값은 수신 연결이 18개월 또는 30일 동안의 인증 요청에 사용할 수 있습니다. 임의의 문자열을 생성하거나 쿠키 또는 쿠키의 해시를 인코딩하는 경우 클라이언트 상태를 캡처하는 다른 값이 있는 경우 요청과 응답이 동일한 브라우저에서 시작되었는지 확인해야 합니다. 일회성, 직간접적 공격, 지속적 공격, 크로스 사이트 요청 위조 자세한 내용은 OpenID Connect state 토큰을 만들고 확인하는 방법에 관한 예시를 참조하세요. 중요: OAuth 클라이언트는 OAuth2 사양 에 대해 자세히 알아보세요. 이를 달성하는 한 가지 방법은 state 매개변수를 사용하여 상태입니다.
login_hint	선택사항 애플리케이션이 인증을 시도하는 사용자를 알고 있는 경우 이 매개변수를 사용할 수 있습니다. Google 인증 서버에 힌트를 제공합니다. 서버는 힌트를 사용하여 로그인 양식의 이메일 입력란을 미리 채우거나 적절한 멀티 로그인 세션을 선택합니다. 매개변수 값을 이메일 주소 또는 sub 식별자로 설정합니다. 사용자의 Google ID와 같습니다.

참고: 설치된 앱을 사용한 증분 승인은 다음 이유로 지원되지 않습니다. 클라이언트에서는 client_secret를 기밀로 유지할 수 없습니다.

샘플 승인 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 관리자에게 문의하세요 Google Workspace 관리자 도움말 보기 어떤 서드 파티 및 Google Workspace 데이터에 액세스하는 내부 앱 를 참조하세요. OAuth 클라이언트 ID에 액세스 권한이 명시적으로 부여될 때까지 범위를 제한합니다.

disallowed_useragent

승인 엔드포인트는 Google에서 허용하지 않는 삽입된 user-agent 내부에 표시되며 OAuth 2.0 정책

Android

Android 개발자가 android.webkit.WebView 개발자는 대신 다음과 같은 Android 라이브러리를 사용해야 합니다. Android용 Google 로그인 또는 OpenID Foundation Android용 AppAuth.

Android 앱이 추가된 사용자 에이전트 및 사용자가 Google OAuth 2.0 승인 엔드포인트로 이동한 다음 확인할 수 있습니다. 개발자는 일반 링크가 운영체제의 일부로 Android App Links 핸들러 또는 기본 브라우저 앱을 사용할 수 있습니다. 이 Android 맞춤 탭 라이브러리도 지원되는 옵션입니다.

iOS

iOS 및 macOS 개발자가 WKWebView 개발자는 대신 다음과 같은 iOS 라이브러리를 사용해야 합니다. iOS용 Google 로그인 또는 OpenID Foundation iOS용 AppAuth.

iOS 또는 macOS 앱에서 삽입된 사용자 에이전트 및 사용자가 Google의 OAuth 2.0 승인 엔드포인트로 이동하여 확인할 수 있습니다. 개발자는 일반 링크가 운영체제의 일부로 범용 링크 핸들러 또는 기본 브라우저 앱을 사용할 수 있습니다. 이 SFSafariViewController 라이브러리도 지원되는 옵션입니다.

org_internal

요청에 포함된 OAuth 클라이언트 ID가 구체적인 Google Cloud 조직. 이 구성 옵션에 대한 자세한 내용은 사용자 유형 섹션을 참조하세요.

invalid_grant

만약 코드 확인기와 challenge의 경우 code_callenge 매개변수가 잘못되었거나 누락되었습니다. code_challenge 매개변수가 올바르게 설정됨

액세스 토큰을 새로고침할 때 토큰이 만료되었거나 무효화되었습니다. 사용자를 다시 인증하고 새 토큰을 받기 위해 사용자 동의를 요청합니다. 계속 진행하는 경우 이 오류를 보려면 애플리케이션이 올바르게 구성되었는지 확인하고 요청에 올바른 토큰과 매개변수를 사용합니다. 그렇지 않으면 사용자 계정에 사용 중지할 수 있습니다.

redirect_uri_mismatch

승인 요청에서 전달된 redirect_uri이(가) 승인된 OAuth 클라이언트 ID의 리디렉션 URI입니다. 승인된 리디렉션 URI는 Google API Console Credentials page

전달된 redirect_uri는 클라이언트 유형에 맞지 않을 수 있습니다.

redirect_uri 매개변수는 더 이상 지원되지 않습니다 자세한 내용은 이전 가이드를 참고하여 통합할 수 있습니다

invalid_request

요청한 내용에 문제가 있습니다. 다음과 같은 여러 가지 이유가 있을 수 있습니다.

• 요청의 형식이 올바르지 않습니다.
• 요청에 필수 매개변수가 누락되었습니다.
• 요청이 Google에서 지원하지 않는 승인 방법을 사용합니다. OAuth 확인 통합은 권장되는 통합 방법을 사용합니다.
• 리디렉션 URI에 사용자 지정 스키마가 사용됨 : 오류 메시지가 표시될 경우 맞춤 URI 스킴은 Chrome 앱 또는 커스텀 URI 스킴에서 지원되지 않습니다. Android 클라이언트에 사용 설정되어 있지 않으면 맞춤 URI를 사용 중이라는 의미입니다. 스키마는 Chrome 앱에서 지원되지 않으며 Android 커스텀 URI 스킴 자세히 알아보기 대안

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

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

사용자가 애플리케이션에 대한 액세스 권한을 부여하면 승인 코드를 갱신 토큰이 있어야 합니다.

5단계: 새로고침 및 액세스를 위해 승인 코드 교환 토큰

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

필드
client_id	API Console에서 가져온 클라이언트 ID Credentials page입니다.
client_secret	API Console에서 가져온 클라이언트 보안 비밀번호 Credentials page입니다.
code	초기 요청에서 반환된 승인 코드입니다.
code_verifier	생성한 코드 인증 도구 1단계:
grant_type	OAuth 2.0 사양이면 이 필드의 값을 authorization_code로 설정해야 합니다.
redirect_uri	API Console Credentials page 해당 client_id입니다.

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

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	참고: 이 속성은 요청에 ID 범위가 포함된 경우에만 반환됩니다. 예를 들면 openid, profile, email입니다. 값은 다음에 대한 디지털 서명된 ID 정보가 포함된 JSON 웹 토큰 (JWT)입니다. 있습니다.
refresh_token	새 액세스 토큰을 가져오는 데 사용할 수 있는 토큰입니다. 갱신 토큰은 사용자가 액세스를 취소합니다. 설치된 애플리케이션에 대해 항상 갱신 토큰이 반환됩니다.
scope	access_token에서 부여한 액세스 권한의 범위(목록으로 표시) 공백으로 구분되고 대소문자를 구분하는 문자열.
token_type	반환되는 토큰의 유형입니다. 현재 이 필드의 값은 항상 Bearer

중요: 애플리케이션은 두 토큰을 모두 안전하고 애플리케이션의 여러 호출 간에 액세스할 수 있는 장기 위치입니다. 이 갱신 토큰을 사용하면 애플리케이션이 현재 사용 중인 액세스 토큰을 만료됩니다. 따라서 애플리케이션이 갱신 토큰을 분실하면 애플리케이션에서 새 갱신 토큰을 얻을 수 있도록 OAuth 2.0 동의 흐름

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

{
  "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 호출

애플리케이션이 액세스 토큰을 획득한 후에는 이 토큰을 사용하여 Google API를 호출함으로써 API에서 요구하는 액세스 범위가 부여된 경우 사용자 계정이 생성됩니다. 이렇게 하려면 access_token 쿼리 중 하나를 포함하여 API에 대한 요청에 액세스 토큰 생성 매개변수 또는 Authorization HTTP 헤더 Bearer 값을 사용할 수 있습니다. 가능하면 쿼리 문자열은 서버 로그에 표시되는 경향이 있으므로 HTTP 헤더를 사용하는 것이 좋습니다. 최대 클라이언트 라이브러리를 사용하여 Google API에 대한 호출을 설정할 수 있는 경우 (예: Drive Files API 호출).

모든 Google API를 사용해 보고 OAuth 2.0 플레이그라운드.

HTTP GET 예시

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

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 명령줄 애플리케이션을 사용하여 이러한 명령어를 테스트할 수 있습니다. 다음은 예를 들면 다음과 같습니다 (권장).

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",
  "token_type": "Bearer"
}

발급되는 갱신 토큰의 수에는 제한이 있습니다. 1회 한도 클라이언트/사용자 조합 및 모든 클라이언트의 사용자당 1회의 조합을 제공합니다. 갱신 토큰을 저장해야 합니다. 장기 스토리지에 저장하고 유효한 상태로 유지되는 한 계속 사용할 수 있습니다. 애플리케이션이 너무 많은 갱신 토큰을 요청하면 한도에 도달할 수 있으며, 이 경우 이전 갱신 토큰이 작동이 중지됩니다

토큰 취소

사용자가 애플리케이션에 부여된 액세스 권한을 취소하려고 하는 경우도 있습니다. 사용자는 액세스 권한을 취소할 수 있습니다. 방문 계정 설정을 탭합니다. 자세한 내용은 삭제 서드 파티 사이트의 사이트 또는 앱 액세스 섹션 및 내 계정에 액세스할 수 있는 앱 지원 문서를 참조하세요.

또한 애플리케이션에서 프로그래밍 방식으로 주어진 액세스 권한을 취소할 수도 있습니다. 프로그래매틱 취소는 사용자가 구독을 취소하거나 또는 앱에 필요한 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 네이티브 앱에는 여기에 설명된 여러 권장사항이 설명되어 있습니다.