웹사이트용 Google 서드 파티 승인 자바스크립트 라이브러리 - 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 Console에서 구성한 OAuth 2.0 클라이언트에 대해 승인된 리디렉션 URI 중 하나와 정확히 일치해야 하며 리디렉션 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

CodeResponse JavaScript 객체가 팝업 UX의 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 - 토큰을 취소할 수 없습니다.