OAuth 연결 유형은 암시적 흐름과 승인 코드 흐름의 두 가지 업계 표준 OAuth 2.0 흐름을 지원합니다. 암시적 코드 흐름에서는 Google이 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 로그인에 성공하면 유효 기간이 긴 액세스 토큰이 Google에 반환됩니다. 그러면 이 액세스 토큰이 어시스턴트에서 작업으로 전송되는 모든 요청에 포함됩니다.
다음과 같은 경우 OAuth 연결이 권장되는 계정 연결 솔루션입니다.
- OAuth 2.0 서버의 기존 구현이 있으며 토큰 교환 엔드포인트를 확장하여 ID 토큰에서 자동 연결 및 계정 생성을 위한 Google 프로토콜 지원을 추가할 수 없습니다 (즉, 이 엔드포인트에 대한 요청에
intent=get및intent=create매개변수 추가).
OAuth 연결이 적합한 솔루션인지 확인하려면 계정 연결 유형 선택 페이지를 참고하세요.
핵심 용어
OAuth 연결의 작동 방식을 읽기 전에 다음 용어를 숙지하세요.
user.verificationStatus: 현재 세션에 인증된 사용자가 있는지 나타내기 위해 시스템에서 설정한 속성입니다.user.accountLinkingStatus: 현재 세션의 사용자에게 연결된 ID가 있는지 나타내기 위해 시스템에서 설정한 속성입니다.계정 연결 시스템 장면: 계정 연결을 위한 확인 흐름을 구현하는 사전 정의된 장면이며 특정 사용 사례에 맞게 맞춤설정할 수 있습니다.
승인 코드 흐름: 이 OAuth 2.0 흐름이 진행되는 동안 Google은 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 로그인이 성공하면 서비스가 승인 코드를 만들어 Google에 반환합니다. Google이 이 승인 코드를 토큰 교환 엔드포인트로 보내 코드의 진위를 확인하고 액세스 토큰과 갱신 토큰을 반환합니다.
이 흐름에는 2개의 엔드포인트가 필요합니다.
- 승인 엔드포인트: 데이터 액세스에 대한 사용자의 동의를 찾거나 얻는 일을 담당하는 엔드포인트입니다. 이 엔드포인트는 다음을 수행합니다.
- 아직 로그인하지 않은 사용자에게 로그인 UI를 표시합니다.
- 요청된 액세스에 동의한 경우를 단기 승인 코드 형식으로 기록합니다.
- 토큰 교환 엔드포인트: 이 엔드포인트는 작업 사용자가 서비스에 액세스할 수 있도록 승인하는 암호화된 문자열 토큰을 가져오는 데 사용됩니다. 이 엔드포인트는 두 가지 유형의 교환을 담당합니다.
- 수명이 긴 갱신 토큰과 수명이 짧은 액세스 토큰으로 승인 코드를 교환합니다. 이러한 교환은 사용자가 계정 연결 흐름을 진행할 때 발생합니다.
- 수명이 긴 갱신 토큰을 수명이 짧은 액세스 토큰으로 교환합니다. 교환은 액세스 토큰이 만료되어 Google이 새로운 액세스 토큰을 필요로 할 때 발생합니다.
- 승인 엔드포인트: 데이터 액세스에 대한 사용자의 동의를 찾거나 얻는 일을 담당하는 엔드포인트입니다. 이 엔드포인트는 다음을 수행합니다.
암시적 코드 흐름: 이 OAuth 2.0 흐름 중에 Google은 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 로그인이 성공하면 유효 기간이 긴 액세스 토큰이 Google에 반환됩니다. 그러면 이 액세스 토큰은 어시스턴트에서 작업으로 전송되는 모든 요청에 포함됩니다. 이 흐름에는 승인 엔드포인트만 있으면 됩니다.
액세스 토큰: 사용자 데이터의 일부에 액세스할 수 있도록 서비스를 승인하는 토큰입니다. 액세스 토큰은 각 개별 사용자와 연결되며 추측할 수 없어야 합니다.
갱신 토큰: 단기 액세스 토큰이 만료되면 새 액세스 토큰으로 교환되는 토큰입니다.
사용 방법
이 섹션에서는 OAuth 승인 코드 및 암시적 흐름의 일반적인 흐름을 설명합니다. 다음 OAuth 연결 흐름 섹션에서는 OAuth에서 발생할 수 있는 다양한 흐름을 설명합니다.
승인 코드 흐름은 다음과 같이 요약할 수 있습니다.
- 작업이 사용자에게 계정을 서비스와 연결할지 묻습니다.
- 사용자가 계정 연결에 동의하면 Google이 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 흐름이 작업의 음성 전용 기기에서 시작되면 Google은 실행을 휴대전화로 전송합니다.
- 사용자는 로그인하고 (아직 로그인하지 않은 경우) API를 사용하여 자신의 데이터에 액세스할 수 있는 권한을 Google에 부여합니다 (아직 권한을 부여하지 않은 경우).
- 서비스는 승인 코드를 만들고 요청에 첨부된 승인 코드로 사용자의 브라우저를 다시 Google로 리디렉션하여 Google에 반환합니다.
- Google은 승인 코드를 토큰 교환 엔드포인트로 전송하여 코드의 진위를 확인하고 액세스 토큰 및 갱신 토큰을 반환합니다. 액세스 토큰은 서비스가 API에 액세스하기 위해 사용자 인증 정보로 허용하는 단기 토큰입니다. 갱신 토큰은 Google에서 액세스 토큰이 만료되면 새 액세스 토큰을 저장하고 얻기 위해 사용할 수 있는 수명이 긴 토큰입니다.
- 사용자가 계정 연결 흐름을 완료하면 어시스턴트에서 처리 웹훅으로 전송되는 모든 후속 요청에 액세스 토큰이 포함됩니다.
암시적 코드 흐름은 다음과 같이 요약할 수 있습니다.
- 작업이 사용자에게 계정을 서비스와 연결할지 묻습니다.
- 사용자가 계정 연결에 동의하면 Google이 사용자의 브라우저에서 승인 엔드포인트를 엽니다.
- 사용자는 로그인하고 (아직 로그인하지 않은 경우) API를 사용하여 자신의 데이터에 액세스할 수 있는 권한을 Google에 부여합니다 (아직 권한을 부여하지 않은 경우).
- 서비스는 액세스 토큰을 생성하고 요청에 첨부된 액세스 토큰으로 사용자의 브라우저를 다시 Google로 리디렉션하여 이를 Google에 반환합니다.
- 사용자가 계정 연결 과정을 완료하면 Google은 서비스의 API를 호출하고 각 요청에 액세스 토큰을 첨부합니다. 서비스에서는 액세스 토큰이 Google에 API 액세스 권한을 부여하는지 확인한 후 API 호출을 완료합니다.
기본 승인 코드 흐름은 다음과 같습니다.
- 작업이 사용자에게 계정을 서비스와 연결할지 묻습니다.
- 사용자가 계정 연결에 동의하면 Google이 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 흐름이 작업의 음성 전용 기기에서 시작되면 Google은 실행을 휴대전화로 전송합니다.
- 사용자는 로그인하고 (아직 로그인하지 않은 경우) API를 사용하여 자신의 데이터에 액세스할 수 있는 권한을 Google에 부여합니다 (아직 권한을 부여하지 않은 경우).
- 서비스는 승인 코드를 만들고 요청에 첨부된 단기 승인 코드로 사용자의 브라우저를 다시 Google로 리디렉션하여 Google에 반환합니다.
- Google은 승인 코드를 토큰 교환 엔드포인트로 전송하여 코드의 진위를 확인하고 액세스 토큰 및 갱신 토큰을 반환합니다. 액세스 토큰은 서비스가 API에 액세스하기 위해 사용자 인증 정보로 허용하는 단기 토큰입니다. 갱신 토큰은 Google에서 액세스 토큰이 만료되면 새 액세스 토큰을 저장하고 얻기 위해 사용할 수 있는 수명이 긴 토큰입니다.
- 사용자가 계정 연결 흐름을 완료하면 어시스턴트에서 처리 웹훅으로 전송되는 모든 후속 요청에 액세스 토큰이 포함됩니다.
OAuth 연결 흐름
이 섹션에서는 OAuth 연결에서 발생할 수 있는 다양한 흐름을 살펴봅니다.
각 흐름에는 사용자가 작업을 호출한 후의 일반적인 단계가 포함됩니다.
위의 흐름에서 계정 연결 시스템 장면으로 전환하고 맞춤설정된 근거를 제공합니다. 어시스턴트는 사용자에게 계정을 서비스와 연결해 줄지 묻고 요청된 권한이 포함된 화면을 표시합니다. 사용자가 동의하면 Google은 사용자를 브라우저에서 서비스의 승인 엔드포인트로 리디렉션합니다. 사용자가 로그인하거나 구성에 따라 새 계정을 만들고 데이터에 액세스할 수 있는 작업 권한을 부여합니다.
이 시점 이후의 흐름은 암시적 흐름 또는 승인 코드 흐름을 구현했는지 여부에 따라 다릅니다. 이러한 흐름은 다음 섹션에서 설명합니다.
흐름 1: 사용자가 암시적 흐름으로 로그인
사용자가 로그인하고 사용자 인증 정보가 확인되면 서비스는 수명이 긴 액세스 토큰을 만들어 Google에 반환합니다. 이 시점에서 작업의 사용자 ID는 사용자가 로그인한 계정에 연결되며 액세스 토큰은 Google이 서비스의 API에 수행하는 각 API 호출에 연결됩니다.
절차 2: 사용자가 승인 코드 흐름으로 로그인하기
사용자가 로그인하고 사용자 인증 정보가 확인되면 서비스에서 승인 코드를 만들어 Google로 반환합니다.
이 승인 코드는 액세스 토큰과 갱신 토큰을 모두 반환하는 토큰 교환 엔드포인트로 전송됩니다. 이 시점에서 작업의 사용자 ID는 사용자가 로그인한 계정에 연결되며, 어시스턴트에서 처리로 전송되는 후속 모든 요청에는 액세스 토큰이 포함됩니다.