계정 연결 API

이 참조 페이지에서는 서비스가 Google과의 계정 연결을 지원하기 위해 구현해야 하는 API 엔드포인트를 설명합니다. 여기에는 OAuth 연결, 간소화된 계정 연결, 앱 전환이 포함됩니다.

기본 요건 및 표준

이러한 엔드포인트를 성공적으로 구현하려면 서비스가 다음 표준을 준수해야 합니다.

  • OAuth 2.0: RFC 6749를 준수합니다.
  • 토큰 취소: RFC 7009를 준수합니다.
  • JSON 웹 토큰 (JWT): RFC 7519를 준수합니다 (간소화된 연결에 필요).
  • HTTPS: 모든 엔드포인트는 보안 HTTPS 연결을 통해 제공되어야 합니다.

승인 엔드포인트

승인 엔드포인트는 사용자를 인증하고 Google과 계정을 연결하는 데 동의를 얻는 역할을 합니다.

  • URL: Actions Console 또는 Google Cloud Console에서 구성됩니다.
  • 메서드: GET

요청 매개변수

매개변수 설명
client_id Google에 할당한 클라이언트 ID입니다.
redirect_uri 이 요청에 대한 응답을 전송할 URL입니다.
state 리디렉션 URI에서 변경되지 않은 상태로 Google에 다시 전달되는 부기 값입니다.
response_type 승인 코드 플로우의 경우 code여야 합니다.
scope (선택사항) Google에서 요청하는 데이터의 범위를 공백으로 구분한 목록입니다.
user_locale (선택사항) Google 계정 언어 설정입니다. BCP-47 언어 태그 (예: en-US)를 사용하여 지정됩니다.
code_challenge (OAuth 2.1에 필요) 코드 확인자에서 파생된 챌린지입니다.
code_challenge_method (선택사항) 챌린지를 도출하는 데 사용된 방법입니다 (예: S256).

토큰 교환 엔드포인트

이 엔드포인트는 승인 코드를 토큰으로 교환하고 만료된 액세스 토큰을 갱신하는 역할을 합니다.

  • URL: Actions Console 또는 Google Cloud Console에서 구성됩니다.
  • 메서드: POST
  • Content-Type: application/x-www-form-urlencoded

토큰의 승인 코드 교환

초기 토큰 교환 요청에는 다음 매개변수가 사용됩니다.

요청 매개변수

매개변수 설명
client_id Google에 할당한 클라이언트 ID입니다.
client_secret Google에 할당한 클라이언트 보안 비밀번호입니다.
grant_type authorization_code이어야 합니다.
code 승인 엔드포인트에서 수신한 승인 코드입니다.
redirect_uri 초기 요청에 사용된 것과 동일한 리디렉션 URI입니다.
code_verifier (PKCE에 필요) 원래 암호화된 무작위 문자열입니다.

갱신 토큰을 액세스 토큰으로 교환

액세스 토큰을 새로고침할 때는 다음 매개변수가 사용됩니다.

요청 매개변수

매개변수 설명
client_id Google에 할당한 클라이언트 ID입니다.
client_secret Google에 할당한 클라이언트 보안 비밀번호입니다.
grant_type refresh_token이어야 합니다.
refresh_token 이전에 Google에 발급된 갱신 토큰입니다.

응답 (JSON)

HTTPS 응답 본문에 JSON 객체가 포함된 성공 응답을 반환합니다.

OpenAPI 3.1 스키마

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • HTTP 상태: 200 OK
  • Content-Type: application/json;charset=UTF-8
필드 설명
token_type 필수사항. bearer여야 합니다.
access_token 필수사항. 서비스의 API에 액세스하는 데 사용되는 단기 토큰입니다.
refresh_token authorization_code grant_type에 필요합니다. 새 액세스 토큰을 획득하는 데 사용되는 장기 토큰입니다.
expires_in 필수사항. 액세스 토큰의 남은 수명(초)입니다.

오류 응답

토큰 엔드포인트에 대한 요청이 실패하면 다음 필드가 포함된 JSON 응답과 함께 HTTP 400 Bad Request 오류를 반환합니다.

  • HTTP 상태: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
오류 필드 (JSON) 설명
error 필수사항. invalid_grant여야 합니다.
error_description (선택사항) 추가 정보를 제공하는 사람이 읽을 수 있는 텍스트입니다.

간소화된 연결 인텐트 처리

서비스에서 간소화된 계정 연결 (Google로 로그인하는 OAuth)을 지원하는 경우 토큰 교환 엔드포인트는 JSON 웹 토큰 (JWT) 어설션을 추가로 지원하고 필수 check 및 get 인텐트와 선택적 create 인텐트를 구현해야 합니다.

이러한 요청에는 다음 매개변수가 사용됩니다.

요청 매개변수

매개변수 설명
intent 요청되는 구체적인 간소화된 연결 인텐트입니다(check, get 또는 선택사항인 create).
grant_type 이러한 요청의 경우 이 매개변수의 값은 항상 urn:ietf:params:oauth:grant-type:jwt-bearer입니다.
assertion Google 사용자의 ID에 대한 서명된 어설션을 제공하는 JSON 웹 토큰 (JWT)입니다. JWT에는 사용자의 Google 계정 ID, 이름, 이메일 주소가 포함된 정보가 포함됩니다.

서버는 JWT 검증 섹션에 나열된 기준을 사용하여 이 JWT를 검증해야 합니다.
client_id Google에 할당한 클라이언트 ID입니다.
client_secret Google에 할당한 클라이언트 보안 비밀번호입니다.
scope 선택사항: Google이 사용자에게 요청하도록 구성한 범위입니다. 일반적으로 get 및 create 의도 중에 표시됩니다.
response_type create 의도에 필요: token로 설정해야 합니다.

JWT 검증

간소화된 연결의 보안을 보장하려면 서버가 다음 기준을 사용하여 assertion (JWT)를 검증해야 합니다.

  • 서명: Google의 JWK 엔드포인트에서 제공되는 Google의 공개 키에 대해 서명을 확인합니다.
  • 발급기관 (iss): https://accounts.google.com여야 합니다.
  • 잠재고객 (aud): 통합에 할당된 Google API 클라이언트 ID와 일치해야 합니다.
  • 만료 (exp): 미래여야 합니다.

check 인텐트에 대한 응답

intent=check가 포함된 요청은 디코딩된 JWT 어설션의 sub 또는 email 클레임으로 식별되는 Google 계정이 사용자 데이터베이스에 있는지 확인합니다.

  • HTTP 상태: 200 OK (계정 있음) 또는 404 Not Found (계정 없음)
  • Content-Type: application/json;charset=UTF-8
필드 설명
account_found 필수사항. 계정이 있으면 true, 그렇지 않으면 false입니다.

get 인텐트에 대한 응답

intent=get를 사용한 요청은 기존 Google 계정의 액세스 토큰을 요청합니다.

  • HTTP 상태: 200 OK
  • Content-Type: application/json;charset=UTF-8

성공 응답 JSON 객체는 성공적인 표준 토큰 교환 응답 (access_token, refresh_token 등을 반환)과 정확히 동일한 구조를 사용합니다.

계정을 연결할 수 없는 경우 HTTP 401 오류가 반환됩니다.

  • HTTP 상태: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
오류 필드 (JSON) 설명
error 필수사항. linking_error여야 합니다.
login_hint (선택사항) 대체 OAuth 연결 흐름에 전달할 사용자의 이메일 주소입니다.

create 의도에 대한 응답 (선택사항)

create 인텐트는 선택사항입니다. 서비스에서 간소화된 연결을 사용한 계정 생성을 지원하는 경우 intent=create를 사용한 요청은 JWT에 제공된 정보로 새 사용자 계정 생성을 시작합니다.

  • HTTP 상태: 200 OK
  • Content-Type: application/json;charset=UTF-8

성공 응답 JSON 객체는 성공적인 표준 토큰 교환 응답 (access_token, refresh_token 등을 반환)과 정확히 동일한 구조를 사용합니다.

사용자가 이미 존재하거나 서비스에서 계정 생성을 지원하지 않는 경우 Google이 표준 OAuth 연결 흐름으로 대체하도록 HTTP 401 오류가 반환됩니다.

  • HTTP 상태: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
오류 필드 (JSON) 설명
error 필수사항. linking_error여야 합니다.
login_hint 대체 OAuth 연결 흐름에 전달할 사용자의 이메일 주소입니다.

UserInfo 엔드포인트 (선택사항)

OpenID Connect Core 1.0 사양에 지정된 대로 연결된 사용자에 관한 기본 프로필 정보를 검색하는 데 사용됩니다. '간소화된 연결' 또는 '원탭 로그인'과 같은 기능에 필요합니다.

  • 메서드: GET
  • 인증: Authorization: Bearer ACCESS_TOKEN

응답 (JSON)

HTTPS 응답 본문에 JSON 객체가 포함된 성공 응답을 반환합니다.

  • HTTP 상태: 200 OK
  • Content-Type: application/json;charset=UTF-8

응답 필드

필드 설명
sub 필수사항. 시스템에서 사용자를 식별하는 고유 ID입니다.
email 필수사항. 사용자의 이메일 주소
email_verified 필수사항. 이메일 주소가 인증되었는지 여부를 나타내는 불리언입니다.
given_name (선택사항) 사용자의 이름입니다.
family_name (선택사항) 사용자의 성입니다.
name (선택사항) 사용자의 전체 이름입니다.
picture (선택사항) 사용자 프로필 사진의 URL입니다.

오류 응답

액세스 토큰이 유효하지 않거나 만료된 경우 HTTP 401 Unauthorized 오류를 반환합니다. WWW-Authenticate 응답 헤더도 포함해야 합니다.

연결 프로세스 중에 반환된 실패 응답 (4xx 또는 5xx)은 복구할 수 없는 것으로 간주됩니다. 이러한 경우 Google은 가져온 토큰을 삭제하며 사용자는 계정 연결 프로세스를 다시 시작해야 합니다.

토큰 취소 엔드포인트 (선택사항)

사용자가 Google 표시 경로에서 계정을 연결 해제할 때 Google이 서비스에 알리도록 허용합니다. 이 엔드포인트는 RFC 7009에 설명된 요구사항을 충족해야 합니다.

  • 메서드: POST
  • Content-Type: application/x-www-form-urlencoded

요청 매개변수

매개변수 설명
client_id 요청 출처를 Google로 식별하는 문자열입니다. 이 문자열은 시스템 내에서 Google의 고유 식별자로 등록되어야 합니다.
client_secret 서비스를 위해 Google에 등록한 비밀번호 문자열입니다.
token 취소할 토큰입니다.
token_type_hint (선택사항) 취소되는 토큰의 유형에 관한 힌트입니다(access_token 또는 refresh_token). 지정하지 않으면 기본값은 access_token입니다.

응답

토큰이 성공적으로 삭제되거나 토큰이 이미 유효하지 않은 경우 성공 응답을 반환합니다.

  • HTTP 상태: 200 OK
  • Content-Type: application/json;charset=UTF-8

오류 응답

어떤 이유로든 토큰을 삭제할 수 없는 경우 (예: 데이터베이스를 사용할 수 없음) HTTP 503 오류를 반환합니다. Google은 나중에 또는 Retry-After 헤더에 따라 요청을 다시 시도합니다.

  • HTTP 상태: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • 헤더: Retry-After: <HTTP-date / delay-seconds>