Google 계정 승인 JavaScript API 참조

이 참조에서는 Google에서 승인 코드 또는 액세스 토큰을 가져오는 데 사용되는 Google 계정 승인 JavaScript API를 설명합니다.

메서드: google.accounts.oauth2.initCodeClient

initCodeClient 메서드는 매개변수의 구성으로 코드 클라이언트를 초기화하고 반환합니다.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig) 

데이터 유형: CodeClientConfig

다음 표에는 CodeClientConfig 데이터 유형의 속성이 나와 있습니다.

속성
client_id 필수사항. 애플리케이션의 클라이언트 ID입니다. 이 값은 API 콘솔에서 확인할 수 있습니다.
scope 필수사항. 사용자를 대신하여 애플리케이션이 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위의 목록입니다. 이러한 값은 Google이 사용자에게 표시하는 동의 화면에 정보를 제공합니다.
include_granted_scopes 선택사항으로, 기본값은 true입니다. 애플리케이션이 단계별 승인을 사용하여 컨텍스트에서 추가 범위에 대한 액세스를 요청할 수 있도록 지원합니다. 이 매개변수의 값을 false로 설정하고 승인 요청이 승인되면 새 액세스 토큰은 이 CodeClientConfig에서 요청된 scope에 해당하는 범위만 포함합니다.
redirect_uri 리디렉션 UX에 필요합니다. 사용자가 승인 흐름을 완료한 후 API 서버가 사용자를 리디렉션하는 위치를 결정합니다. 이 값은 API 콘솔에서 구성한 OAuth 2.0 클라이언트의 승인된 리디렉션 URI 중 하나와 정확히 일치해야 하며 Google의 리디렉션 URI 유효성 검사 규칙을 준수해야 합니다. 이 속성은 팝업 UX에서 무시됩니다.
callback 팝업 UX에 필요합니다. 반환된 코드 응답을 처리하는 JavaScript 함수입니다. 이 속성은 리디렉션 UX에서 무시됩니다.
state 선택사항입니다. 리디렉션 UX에 권장됩니다. 애플리케이션이 승인 요청과 승인 서버의 응답 간에 상태를 유지하는 데 사용하는 문자열 값을 지정합니다.
enable_granular_consent 지원 중단되었으며 설정해도 효과가 없습니다. 동의 동작에 관한 자세한 내용은 세부 권한을 참고하세요.
enable_serial_consent 지원 중단되었으며 설정해도 효과가 없습니다. 동의 동작에 관한 자세한 내용은 세부 권한을 참고하세요.
login_hint 선택사항입니다. 애플리케이션이 요청을 승인해야 하는 사용자를 알고 있는 경우 이 속성을 사용하여 Google에 로그인 힌트를 제공할 수 있습니다. 성공하면 계정 선택이 건너뛰어집니다. 타겟 사용자의 이메일 주소 또는 ID 토큰 sub 필드 값입니다. 자세한 내용은 OpenID Connect 문서의 login_hint 필드를 참고하세요.
hd 선택사항입니다. 애플리케이션이 사용자가 속한 Workspace 도메인을 알고 있는 경우 이를 사용하여 Google에 힌트를 제공하세요. 성공하면 사용자 계정이 제공된 도메인으로 제한되거나 미리 선택됩니다. 자세한 내용은 OpenID Connect 문서의 hd 필드를 참고하세요.
ux_mode 선택사항입니다. 승인 흐름에 사용할 UX 모드입니다. 기본적으로 동의 흐름이 팝업으로 열립니다. 유효한 값은 popup, redirect입니다.
select_account 선택사항이며 기본값은 'false'입니다. 사용자에게 계정을 선택하라는 메시지를 표시하는 불리언 값입니다.
error_callback 선택사항입니다. 팝업 창이 열리지 않거나 OAuth 응답이 반환되기 전에 닫히는 등 일부 비 OAuth 오류를 처리하는 JavaScript 함수입니다.

입력 매개변수의 `type` 필드에 자세한 이유가 나와 있습니다.
  • popup_failed_to_open 팝업 창을 열 수 없습니다.
  • popup_closed OAuth 응답이 반환되기 전에 팝업 창이 닫혔습니다.
  • 기타 오류의 unknown 자리표시자입니다.

데이터 유형: CodeClient

이 클래스에는 OAuth 2.0 코드 UX 흐름을 시작하는 public 메서드 requestCode가 하나만 있습니다.

interface CodeClient {   requestCode(): void; } 

데이터 유형: CodeResponse

팝업 UX에서 CodeResponse JavaScript 객체가 callback 메서드에 전달됩니다. 리디렉션 UX에서 CodeResponse는 URL 매개변수로 전달됩니다.

다음 표에는 CodeResponse 데이터 유형의 속성이 나와 있습니다.

속성
code 성공적인 토큰 응답의 승인 코드입니다.
scope 사용자가 승인한 범위를 공백으로 구분한 목록입니다.
state 애플리케이션이 승인 요청과 응답 간에 상태를 유지하는 데 사용하는 문자열 값입니다.
error 단일 ASCII 오류 코드입니다.
error_description 발생한 오류를 클라이언트 개발자가 이해하는 데 도움이 되는 추가 정보를 제공하는 사람이 읽을 수 있는 ASCII 텍스트입니다.
error_uri 오류에 관한 정보가 포함된 사람이 읽을 수 있는 웹페이지를 식별하는 URI로, 클라이언트 개발자에게 오류에 관한 추가 정보를 제공하는 데 사용됩니다.

메서드: google.accounts.oauth2.initTokenClient

initTokenClient 메서드는 매개변수의 구성으로 토큰 클라이언트를 초기화하고 반환합니다.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig) 

데이터 유형: TokenClientConfig

다음 표에는 TokenClientConfig 데이터 유형의 속성이 나와 있습니다.

속성
client_id 필수사항. 애플리케이션의 클라이언트 ID입니다. 이 값은 API 콘솔에서 확인할 수 있습니다.
callback 필수사항. 반환된 토큰 응답을 처리하는 JavaScript 함수입니다.
scope 필수사항. 사용자를 대신하여 애플리케이션이 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위의 목록입니다. 이러한 값은 Google이 사용자에게 표시하는 동의 화면에 정보를 제공합니다.
include_granted_scopes 선택사항으로, 기본값은 true입니다. 애플리케이션이 단계별 승인을 사용하여 컨텍스트에서 추가 범위에 대한 액세스를 요청할 수 있도록 지원합니다. 이 매개변수의 값을 false로 설정하고 승인 요청이 승인되면 새 액세스 토큰은 이 TokenClientConfig에서 요청된 scope에 해당하는 범위만 포함합니다.
prompt 선택사항이며 기본값은 'select_account'입니다. 사용자에게 표시할 프롬프트의 공백으로 구분된 대소문자 구분 목록입니다. 가능한 값은 다음과 같습니다.
  • 빈 문자열 앱에서 액세스를 요청하는 첫 번째 경우에만 사용자에게 메시지가 표시됩니다. 다른 값과 함께 지정할 수 없습니다.
  • 'none' 인증 또는 동의 화면을 표시하지 않습니다. 다른 값과 함께 지정하면 안 됩니다.
  • 'consent' 사용자에게 동의를 요청합니다.
  • 'select_account' 사용자에게 계정을 선택하라는 메시지를 표시합니다.
enable_granular_consent 지원 중단되었으며 설정해도 효과가 없습니다. 동의 동작에 관한 자세한 내용은 세부 권한을 참고하세요.
enable_serial_consent 지원 중단되었으며 설정해도 효과가 없습니다. 동의 동작에 관한 자세한 내용은 세부 권한을 참고하세요.
login_hint 선택사항입니다. 애플리케이션이 요청을 승인해야 하는 사용자를 알고 있는 경우 이 속성을 사용하여 Google에 로그인 힌트를 제공할 수 있습니다. 성공하면 계정 선택이 건너뛰어집니다. 타겟 사용자의 이메일 주소 또는 ID 토큰 sub 필드 값입니다. 자세한 내용은 OpenID Connect 문서의 login_hint 필드를 참고하세요.
hd 선택사항입니다. 애플리케이션이 사용자가 속한 Workspace 도메인을 알고 있는 경우 이를 사용하여 Google에 힌트를 제공하세요. 성공하면 사용자 계정이 제공된 도메인으로 제한되거나 미리 선택됩니다. 자세한 내용은 OpenID Connect 문서의 hd 필드를 참고하세요.
state 선택사항입니다. 권장하지 않음 애플리케이션이 승인 요청과 승인 서버의 응답 간에 상태를 유지하는 데 사용하는 문자열 값을 지정합니다.
error_callback 선택사항입니다. 팝업 창이 열리지 않거나 OAuth 응답이 반환되기 전에 닫히는 등 일부 비 OAuth 오류를 처리하는 JavaScript 함수입니다.

입력 매개변수의 `type` 필드에 자세한 이유가 나와 있습니다.
  • popup_failed_to_open 팝업 창을 열 수 없습니다.
  • popup_closed OAuth 응답이 반환되기 전에 팝업 창이 닫혔습니다.
  • 기타 오류의 unknown 자리표시자입니다.

데이터 유형: TokenClient

이 클래스에는 OAuth 2.0 토큰 UX 흐름을 시작하는 공개 메서드 requestAccessToken가 하나만 있습니다.

interface TokenClient {   requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void; } 
인수
overrideConfig OverridableTokenClientConfig 선택사항입니다. 이 메서드에서 재정의할 구성입니다.

데이터 유형: OverridableTokenClientConfig

다음 표에는 OverridableTokenClientConfig 데이터 유형의 속성이 나와 있습니다.

속성
scope 선택사항입니다. 애플리케이션이 사용자를 대신하여 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위 목록입니다. 이러한 값은 Google이 사용자에게 표시하는 동의 화면에 정보를 제공합니다.
include_granted_scopes 선택사항으로, 기본값은 true입니다. 애플리케이션이 단계별 승인을 사용하여 컨텍스트에서 추가 범위에 대한 액세스를 요청할 수 있도록 지원합니다. 이 매개변수의 값을 false로 설정하고 승인 요청이 승인되면 새 액세스 토큰은 이 OverridableTokenClientConfig에서 요청된 scope에 해당하는 범위만 포함합니다.
prompt 선택사항입니다. 사용자에게 표시할 프롬프트의 공백으로 구분된 대소문자 구분 목록입니다.
enable_granular_consent 지원 중단되었으며 설정해도 효과가 없습니다. 동의 동작에 관한 자세한 내용은 세부 권한을 참고하세요.
enable_serial_consent 지원 중단되었으며 설정해도 효과가 없습니다. 동의 동작에 관한 자세한 내용은 세부 권한을 참고하세요.
login_hint 선택사항입니다. 애플리케이션이 요청을 승인해야 하는 사용자를 알고 있는 경우 이 속성을 사용하여 Google에 로그인 힌트를 제공할 수 있습니다. 성공하면 계정 선택이 건너뛰어집니다. 타겟 사용자의 이메일 주소 또는 ID 토큰 sub 필드 값입니다. 자세한 내용은 OpenID Connect 문서의 login_hint 필드를 참고하세요.
state 선택사항입니다. 권장하지 않음 애플리케이션이 승인 요청과 승인 서버의 응답 간에 상태를 유지하는 데 사용하는 문자열 값을 지정합니다.

데이터 유형: TokenResponse

TokenResponse JavaScript 객체가 팝업 UX의 콜백 메서드에 전달됩니다.

다음 표에는 TokenResponse 데이터 유형의 속성이 나와 있습니다.

속성
access_token 성공적인 토큰 응답의 액세스 토큰입니다.
expires_in 액세스 토큰의 수명(초)입니다.
hd 로그인한 사용자가 속한 호스팅 도메인입니다.
prompt TokenClientConfig 또는 OverridableTokenClientConfig에 의해 지정된 가능한 값 목록에서 사용된 프롬프트 값입니다.
token_type 발급된 토큰의 유형입니다.
scope 사용자가 승인한 범위를 공백으로 구분한 목록입니다.
state 애플리케이션이 승인 요청과 응답 간에 상태를 유지하는 데 사용하는 문자열 값입니다.
error 단일 ASCII 오류 코드입니다.
error_description 발생한 오류를 클라이언트 개발자가 이해하는 데 도움이 되는 추가 정보를 제공하는 사람이 읽을 수 있는 ASCII 텍스트입니다.
error_uri 오류에 관한 정보가 포함된 사람이 읽을 수 있는 웹페이지를 식별하는 URI로, 클라이언트 개발자에게 오류에 관한 추가 정보를 제공하는 데 사용됩니다.

메서드: google.accounts.oauth2.hasGrantedAllScopes

사용자가 지정된 범위 또는 범위를 모두 부여했는지 확인합니다.

google.accounts.oauth2.hasGrantedAllScopes(                                             tokenResponse: TokenResponse,                                             firstScope: string, ...restScopes: string[]                                           ): boolean; 
인수
tokenResponse TokenResponse 필수사항. TokenResponse 객체
firstScope 문자열 필수사항. 확인할 범위입니다.
restScopes 문자열[] 선택사항입니다. 확인할 다른 범위입니다.
반환 값
부울 모든 범위가 부여된 경우 true입니다.

메서드: google.accounts.oauth2.hasGrantedAnyScope

사용자가 지정된 범위 중 하나를 부여했는지 확인합니다.

google.accounts.oauth2.hasGrantedAnyScope(                                            tokenResponse: TokenResponse,                                            firstScope: string, ...restScopes: string[]                                          ): boolean; 
인수
tokenResponse TokenResponse 필수사항. TokenResponse 객체
firstScope 문자열 필수사항. 확인할 범위입니다.
restScopes 문자열[] 선택사항입니다. 확인할 다른 범위입니다.
반환 값
부울 범위 중 하나라도 부여된 경우 true입니다.

메서드: google.accounts.oauth2.revoke

revoke 메서드는 사용자가 앱에 부여한 모든 범위를 취소합니다. 권한을 취소하려면 유효한 액세스 토큰이 필요합니다.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void; 
인수
accessToken 문자열 필수사항. 유효한 액세스 토큰입니다.
callback 함수 선택사항입니다. RevocationResponse 핸들러

데이터 유형: RevocationResponse

RevocationResponse JavaScript 객체가 콜백 메서드에 전달됩니다.

다음 표에는 RevocationResponse 데이터 유형의 속성이 나와 있습니다.

속성
successful 부울. 성공 시 true, 실패 시 false
error 문자열. 성공 시 정의되지 않습니다. 단일 ASCII 오류 코드입니다. 여기에는 표준 OAuth 2.0 오류 코드가 포함되지만 이에 국한되지 않습니다. revoke 메서드의 일반적인 오류는 다음과 같습니다.
  • invalid_token - revoke 메서드가 호출되기 전에 토큰이 이미 만료되었거나 취소되었습니다. 대부분의 경우 accessToken와 연결된 권한이 취소된 것으로 간주할 수 있습니다.
  • invalid_request - 토큰을 취소할 수 없습니다. accessToken이 유효한 Google OAuth 2.0 사용자 인증 정보인지 확인해야 합니다.
error_description 문자열. 성공 시 정의되지 않습니다. 사람이 읽을 수 있는 ASCII 텍스트는 error 속성에 관한 추가 정보를 제공합니다. 개발자는 이를 사용하여 발생한 오류를 더 잘 이해할 수 있습니다. error_description 문자열은 영어로만 제공됩니다. error에 나열된 일반적인 오류의 경우 해당 error_description는 다음과 같습니다.
  • invalid_token - 토큰이 만료되었거나 취소되었습니다.
  • invalid_request - 토큰을 취소할 수 없습니다.