웹사이트용 Google 서드 파티 승인 자바스크립트 라이브러리 - API 참조

이 참조에서는 Google에서 승인 코드 또는 액세스 토큰을 로드하는 데 사용할 수 있는 Google 3P Authorization JavaScript Library 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에 필요합니다. 반환된 코드 응답을 처리하는 자바스크립트 함수 이 속성은 리디렉션 UX에서 무시됩니다.
state 선택사항입니다. 리디렉션 UX에 권장됩니다. 애플리케이션이 승인 요청과 승인 서버 응답 사이의 상태를 유지하기 위해 사용하는 문자열 값을 지정합니다.
enable_granular_consent 선택사항. 기본값은 true입니다. false로 설정하면 2019년 이전에 생성된 OAuth 클라이언트 ID에 대해 보다 세분화된 Google 계정 권한이 사용 중지됩니다. enable_granular_consentenable_serial_consent가 모두 설정된 경우 enable_granular_consent 값만 적용되고 enable_serial_consent 값은 무시됩니다.

최신 OAuth 클라이언트 ID에는 더 세분화된 권한이 항상 사용 설정되어 있으므로 새로운 OAuth 클라이언트 ID에는 영향이 없습니다.
enable_serial_consent 지원 중단되었습니다. 대신 enable_granular_consent를 사용해야 합니다. 이는 enable_granular_consent와 효과가 같습니다. enable_serial_consent를 사용하는 기존 애플리케이션은 계속 사용할 수 있지만 다음 애플리케이션 업데이트에서 enable_granular_consent를 사용하도록 코드를 업데이트하는 것이 좋습니다.
login_hint 선택사항입니다. 애플리케이션이 요청을 승인해야 하는 사용자를 알고 있는 경우 이 속성을 사용하여 Google에 로그인 힌트를 제공할 수 있습니다. 성공하면 계정 선택을 건너뜁니다. 대상 사용자의 이메일 주소 또는 ID 토큰 sub 필드 값입니다. 자세한 내용은 OpenID Connect 문서의 login_hint 필드를 참조하세요.
hd 선택사항입니다. 애플리케이션에서 사용자가 속한 Workspace 도메인을 알고 있는 경우 이 도메인을 사용하여 Google에 힌트를 제공합니다. 성공하면 사용자 계정이 제공된 도메인으로 제한되거나 미리 선택됩니다. 자세한 내용은 OpenID Connect 문서의 hd 필드를 참조하세요.
ux_mode 선택사항입니다. 승인 흐름에 사용할 UX 모드입니다. 기본적으로 팝업에서 동의 절차가 열립니다. 유효한 값은 popupredirect입니다.
select_account 선택사항. 기본값은 'false'입니다. 사용자에게 계정을 선택하라는 메시지를 표시하는 부울 값입니다.
error_callback 선택사항입니다. 팝업 창이 열리지 않거나 OAuth 응답이 반환되기 전에 닫히는 등 OAuth가 아닌 일부 오류를 처리하는 자바스크립트 함수입니다.

입력 매개변수의 `type` 필드는 자세한 이유를 제공합니다.
  • popup_failed_to_open 팝업 창을 열 수 없습니다.
  • popup_closed: OAuth 응답이 반환되기 전에 팝업 창이 닫힙니다.
  • unknown: 다른 오류에 대한 자리표시자입니다.

데이터 유형: CodeClient

클래스에는 OAuth 2.0 코드 UX 흐름을 시작하는 공개 메서드 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 필수사항. 반환된 토큰 응답을 처리하는 자바스크립트 함수
scope 필수사항. 사용자를 대신하여 애플리케이션이 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위의 목록입니다. 이러한 값은 Google에서 사용자에게 표시하는 동의 화면을 결정합니다.
include_granted_scopes 선택사항. 기본값은 true입니다. 애플리케이션에서 증분 승인을 사용하여 컨텍스트 내에서 추가 범위에 대한 액세스를 요청할 수 있습니다. 이 매개변수의 값을 false로 설정하고 승인 요청이 승인되면 새 액세스 토큰은 이 TokenClientConfig에서 scope가 요청한 모든 범위에만 적용됩니다.
prompt 선택사항. 기본값은 'select_account'입니다. 공백으로 구분된 대소문자를 구분하는 프롬프트 목록으로, 사용자에게 표시할 프롬프트입니다. 가능한 값은 다음과 같습니다.
  • 빈 문자열 앱에서 처음으로 액세스를 요청할 때만 사용자에게 메시지가 표시됩니다. 다른 값과 함께 지정할 수 없습니다.
  • 'none' 인증 또는 동의 화면을 표시하지 않습니다. 다른 값으로 지정해서는 안 됩니다.
  • 'consent' 사용자에게 동의를 요청하는 메시지를 표시합니다.
  • 'select_account' 사용자에게 계정을 선택하라는 메시지를 표시합니다.
enable_granular_consent 선택사항. 기본값은 true입니다. false로 설정하면 2019년 이전에 생성된 OAuth 클라이언트 ID에 대해 보다 세분화된 Google 계정 권한이 사용 중지됩니다. enable_granular_consentenable_serial_consent가 모두 설정된 경우 enable_granular_consent 값만 적용되고 enable_serial_consent 값은 무시됩니다.

최신 OAuth 클라이언트 ID에는 더 세분화된 권한이 항상 사용 설정되어 있으므로 새로운 OAuth 클라이언트 ID에는 영향이 없습니다.
enable_serial_consent 지원 중단되었습니다. 대신 enable_granular_consent를 사용해야 합니다. 이는 enable_granular_consent와 효과가 같습니다. enable_serial_consent를 사용하는 기존 애플리케이션은 계속 사용할 수 있지만 다음 애플리케이션 업데이트에서 enable_granular_consent를 사용하도록 코드를 업데이트하는 것이 좋습니다.
login_hint 선택사항입니다. 애플리케이션이 요청을 승인해야 하는 사용자를 알고 있는 경우 이 속성을 사용하여 Google에 로그인 힌트를 제공할 수 있습니다. 성공하면 계정 선택을 건너뜁니다. 대상 사용자의 이메일 주소 또는 ID 토큰 sub 필드 값입니다. 자세한 내용은 OpenID Connect 문서의 login_hint 필드를 참조하세요.
hd 선택사항입니다. 애플리케이션에서 사용자가 속한 Workspace 도메인을 알고 있는 경우 이 도메인을 사용하여 Google에 힌트를 제공합니다. 성공하면 사용자 계정이 제공된 도메인으로 제한되거나 미리 선택됩니다. 자세한 내용은 OpenID Connect 문서의 hd 필드를 참조하세요.
state 선택사항입니다. 권장하지 않음 애플리케이션이 승인 요청과 승인 서버 응답 사이의 상태를 유지하기 위해 사용하는 문자열 값을 지정합니다.
error_callback 선택사항입니다. 팝업 창이 열리지 않거나 OAuth 응답이 반환되기 전에 닫히는 등 OAuth가 아닌 일부 오류를 처리하는 자바스크립트 함수입니다.

입력 매개변수의 `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 선택사항. 기본값은 true입니다. false로 설정하면 2019년 이전에 생성된 OAuth 클라이언트 ID에 대해 보다 세분화된 Google 계정 권한이 사용 중지됩니다.enable_granular_consentenable_serial_consent가 모두 설정되면 enable_granular_consent 값만 적용되고 enable_serial_consent 값은 무시됩니다.

최신 OAuth 클라이언트 ID에는 더 세분화된 권한이 항상 사용 설정되어 있으므로 새로운 OAuth 클라이언트 ID에는 영향이 없습니다.
enable_serial_consent 지원 중단되었습니다. 대신 enable_granular_consent를 사용해야 합니다. 이는 enable_granular_consent와 효과가 같습니다. enable_serial_consent를 사용하는 기존 애플리케이션은 계속 사용할 수 있지만 다음 애플리케이션 업데이트에서 enable_granular_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 string 필수사항. 확인할 범위입니다.
restScopes 문자열[] 선택사항입니다. 확인할 다른 범위입니다.
반환 값
boolean 모든 범위가 부여되면 true입니다.

메서드: google.accounts.oauth2.hasGrantedAnyScope

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

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

메서드: google.accounts.oauth2.revoke

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

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

데이터 유형: RevocationResponse

RevocationResponse 자바스크립트 객체가 콜백 메서드에 전달됩니다.

다음 표에는 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 - 토큰을 취소할 수 없습니다.