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

이 참조에서는 Google 서드 파티 승인 JavaScript 라이브러리 API를 설명합니다. Google에서 승인 코드나 액세스 토큰을 로드하는 데 사용할 수 있습니다.

메서드: google.accounts.oauth2.initCodeClient

initCodeClient 메서드는 다음을 사용하여 코드 클라이언트를 초기화하고 반환합니다. 매개변수에서 구성을 확인할 수 있습니다.

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

데이터 유형: CodeClientConfig

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

속성
client_id 필수사항. 애플리케이션의 클라이언트 ID입니다. API 콘솔에서 이 값을 확인할 수 있습니다.
scope 필수사항. 사용자를 대신하여 애플리케이션이 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위의 목록입니다. 이 값은 Google에서 사용자에게 표시하는 동의 화면에 관한 정보를 제공합니다.
include_granted_scopes 선택사항이며 기본값은 true입니다. 애플리케이션에서 증분 사용 컨텍스트에서 추가 범위에 대한 액세스를 요청할 수 있는 권한을 부여합니다. 만약 이 매개변수의 값을 false로 설정하고 승인 요청이 승인되면 새 액세스 토큰은 scope에서 요청한 범위만 포함합니다. 이 CodeClientConfig
redirect_uri 리디렉션 UX에 필요합니다. 사용자가 인증 흐름을 완료하면 API 서버가 사용자를 리디렉션하는 위치를 결정합니다. 값은 API 콘솔에서 구성한 OAuth 2.0 클라이언트에 대해 승인된 리디렉션 URI 중 하나와 정확히 일치해야 하며 Google의 리디렉션 URI 유효성 검사 규칙을 준수해야 합니다. 이 속성은 팝업 UX에서 무시됩니다.
callback 팝업 UX에 필요합니다. 반환된 코드 응답을 처리하는 JavaScript 함수입니다. 이 속성은 리디렉션 UX에서 무시됩니다.
state 선택사항입니다. 리디렉션 UX에 권장됩니다. 애플리케이션이 승인 요청과 승인 서버의 응답 간 상태를 유지하기 위해 사용하는 문자열 값을 지정합니다.
enable_granular_consent 선택사항이며 기본값은 true입니다. false로 설정하면 Google 계정 권한이 더 상세해집니다. 2019년 이전에 생성된 OAuth 클라이언트 ID의 경우 사용 중지됩니다. enable_granular_consentenable_serial_consent가 모두 설정된 경우 enable_granular_consent만 적용됩니다. 값이 적용되고 enable_serial_consent 값은 무시됩니다.

더 세분화된 권한이 항상 사용 설정되므로 최신 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 모드입니다. 기본적으로 동의 절차가 팝업으로 열립니다. 유효한 값은 popup, redirect입니다.
select_account 선택사항이며 기본값은 'false'입니다. 사용자에게 계정을 선택하라는 불리언 값입니다.
error_callback 선택사항입니다. OAuth가 아닌 일부 오류를 처리하는 JavaScript 함수: 팝업 창을 열 수 없습니다. 또는 OAuth 응답이 반환합니다.

입력 매개변수의 `type` 필드에 자세한 이유가 제공됩니다.
  • popup_failed_to_open 팝업 창을 열지 못했습니다.
  • popup_closed. OAuth 전에 팝업 창이 닫힙니다. 반환됩니다.
  • unknown 기타 오류에 대한 자리표시자

데이터 유형: CodeClient

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

interface CodeClient {
  requestCode(): void;
}

데이터 유형: CodeResponse

CodeResponse JavaScript 객체는 다음에서 callback 메서드에 전달됩니다. 팝업 UX를 표시합니다. 리디렉션 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로 설정하고 승인 요청이 승인되면 새 액세스 토큰은 scope에서 요청한 범위만 포함합니다. 이 TokenClientConfig
prompt 선택사항이며 기본값은 'select_account'입니다. 공백으로 구분된 사용자에게 표시할 프롬프트의 대소문자 구분 목록입니다. 가능한 값은 다음과 같습니다. <ph type="x-smartling-placeholder">
    </ph>
  • 빈 문자열: 앱에서 처음 액세스를 요청할 때만 사용자에게 메시지가 표시됩니다. 다른 값과 함께 지정할 수 없습니다.
  • 'none' 인증 또는 동의 화면을 표시하지 않습니다. 다른 값과 함께 지정하면 안 됩니다.
  • 'consent' 사용자에게 동의하라는 메시지를 표시합니다.
  • 'select_account': 사용자에게 계정을 선택하라는 메시지를 표시합니다.
enable_granular_consent 선택사항이며 기본값은 true입니다. false로 설정하면 Google 계정 권한이 더 상세해집니다. 2019년 이전에 생성된 OAuth 클라이언트 ID의 경우 사용 중지됩니다. enable_granular_consentenable_serial_consent가 모두 설정된 경우 enable_granular_consent만 적용됩니다. 값이 적용되고 enable_serial_consent 값은 무시됩니다.

더 세분화된 권한이 항상 사용 설정되므로 최신 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가 아닌 일부 오류를 처리하는 JavaScript 함수: 팝업 창을 열 수 없습니다. 또는 OAuth 응답이 반환합니다.

입력 매개변수의 `type` 필드에 자세한 이유가 제공됩니다.
  • popup_failed_to_open 팝업 창을 열지 못했습니다.
  • popup_closed. OAuth 전에 팝업 창이 닫힙니다. 반환됩니다.
  • unknown 기타 오류에 대한 자리표시자

데이터 유형: TokenClient

클래스에는 공개 메서드 requestAccessToken만 있으며, 이 메서드는 OAuth 2.0 토큰 UX 흐름

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

데이터 유형: OverridableTokenClientConfig

다음 표에는 OverridableTokenClientConfig의 속성이 나열되어 있습니다. 데이터 유형입니다.

속성
scope 선택사항입니다. 리소스를 식별하는 공백으로 구분된 범위 목록 사용자 대신 애플리케이션에 액세스할 수 있습니다. 이러한 값은 Google에서 사용자에게 표시하는 동의 화면에 알립니다.
include_granted_scopes 선택사항이며 기본값은 true입니다. 애플리케이션에서 증분 사용 컨텍스트에서 추가 범위에 대한 액세스를 요청할 수 있는 권한을 부여합니다. 만약 이 매개변수의 값을 false로 설정하고 승인 요청이 승인되면 새 액세스 토큰은 scope에서 요청한 범위만 포함합니다. 이 OverridableTokenClientConfig
prompt 선택사항입니다. 공백으로 구분되며 대소문자를 구분하는 사용자에게 표시할 메시지 목록입니다.
enable_granular_consent 선택사항이며 기본값은 true입니다. false로 설정하면 Google 계정 권한이 더 상세해집니다. 2019년 이전에 생성된 OAuth 클라이언트 ID에는 사용 중지됩니다. enable_granular_consentenable_serial_consent를 모두 설정하면 enable_granular_consent만 사용 설정됩니다. 값이 적용되고 enable_serial_consent 값은 무시됩니다.

더 세분화된 권한이 항상 사용 설정되므로 최신 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 문자열 필수사항. 확인할 범위입니다.
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 메서드의 일반적인 오류는 다음과 같습니다. <ph type="x-smartling-placeholder">
    </ph>
  • invalid_token - revoke 메서드가 호출되기 전에 토큰이 이미 만료되었거나 취소되었습니다. 대부분의 경우 accessToken가 취소됩니다.
  • invalid_request - 토큰을 취소할 수 없습니다. 이때 accessToken는 유효한 Google OAuth 2.0 사용자 인증 정보입니다.
error_description 문자열. 성공 시 정의되지 않음. 사람이 읽을 수 있는 ASCII 텍스트는 error 속성입니다. 개발자는 이를 통해 확인할 수 있습니다 error_description 문자열은 영어로만 제공됩니다. error에 나열된 일반적인 오류의 경우 상응하는 error_description는 다음과 같습니다. <ph type="x-smartling-placeholder">
    </ph>
  • invalid_token - 토큰이 만료되거나 취소되었습니다.
  • invalid_request - 토큰을 취소할 수 없습니다.