OAuth 연결 유형은 암시적 흐름과 승인 코드 흐름의 두 가지 업계 표준 OAuth 2.0 흐름을 지원합니다. 암시적 코드 흐름에서는 Google이 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 로그인에 성공하면 유효 기간이 긴 액세스 토큰이 Google에 반환됩니다. 그러면 이 액세스 토큰이 어시스턴트에서 작업으로 전송되는 모든 요청에 포함됩니다.
다음과 같은 경우 OAuth 연결이 권장되는 계정 연결 솔루션입니다.
OAuth 2.0 서버의 기존 구현이 있으며 토큰 교환 엔드포인트를 확장하여 ID 토큰에서 자동 연결 및 계정 생성을 위한 Google 프로토콜 지원을 추가할 수 없습니다 (즉, 이 엔드포인트에 대한 요청에 intent=get 및 intent=create 매개변수 추가).
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는 사용자가 로그인한 계정에 연결되며, 어시스턴트에서 처리로 전송되는 후속 모든 요청에는 액세스 토큰이 포함됩니다.
[null,null,["최종 업데이트: 2025-07-25(UTC)"],[[["\u003cp\u003eOAuth linking in Google Assistant uses OAuth 2.0 for account linking, supporting both implicit and authorization code flows.\u003c/p\u003e\n"],["\u003cp\u003eImplicit flow directly returns a long-lived access token upon successful sign-in, while the authorization code flow involves an intermediary authorization code for enhanced security.\u003c/p\u003e\n"],["\u003cp\u003eAccount linking with OAuth is recommended when you have an existing OAuth 2.0 server and cannot modify its token exchange endpoint to accommodate Google's protocols.\u003c/p\u003e\n"],["\u003cp\u003eThe authorization code flow involves an authorization endpoint for user consent and a token exchange endpoint for acquiring access and refresh tokens.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Assistant provides system properties like \u003ccode\u003euser.verificationStatus\u003c/code\u003e and \u003ccode\u003euser.accountLinkingStatus\u003c/code\u003e to indicate the user's verification and linking status, respectively.\u003c/p\u003e\n"]]],["OAuth linking utilizes the implicit and authorization code flows. In the implicit flow, after user sign-in, a long-lived access token is returned to Google, included in all subsequent requests. The authorization code flow involves Google receiving a short-lived authorization code after user sign-in, which is exchanged for an access and refresh token at the token exchange endpoint. Both flows begin with the user agreeing to link accounts and granting data access permission. After these steps, each service interaction from assistant will contain an access token.\n"],null,["# OAuth linking concept guide\n\nThe *OAuth linking* type supports two industry-standard OAuth 2.0 flows:\nthe *implicit* and *authorization code* flows. In the implicit code flow, Google\nopens your authorization endpoint in the user's browser. After successful sign-in,\nyou return a long-lived access token to Google. This access token is then included\nin every request sent from Assistant to your Action.\n\nOAuth linking is the recommended account linking solution if the following applies:\n\n- You have an existing implementation of an OAuth 2.0 server, and you cannot extend your token exchange endpoint to add support for Google's protocols for automatic linking and account creation from an ID token (i.e., add the `intent=get` and `intent=create` parameters in requests to this endpoint).\n\nTo verify that OAuth linking is the right solution for you, see the\n[Choose your account linking type](/assistant/identity/choose-type) page.\n\nKey terms\n---------\n\nBefore you read about how OAuth linking works, familiarize yourself with the following terms:\n\n- **`user.verificationStatus`:** A property set by the system to indicate if the\n current session has a verified user.\n\n- **`user.accountLinkingStatus`:** A property set by the system to indicate if the\n user in the current session has a linked identity.\n\n- **Account linking system scene:** A predefined scene that implements the confirmation\n flow for account linking, and can be customized to fit specific use cases.\n\n- **Authorization code flow:** During this OAuth 2.0 flow, Google opens your\n authorization endpoint in the user's browser. If sign-in is successful,\n your service creates an *authorization code* and returns it to Google.\n Google sends this authorization code to your token exchange endpoint, which\n verifies the authenticity of the code and returns an access token and refresh token.\n\n This flow requires two endpoints:\n - **Authorization endpoint:** The endpoint that is responsible for finding or obtaining consent from users for data access. This endpoint does the following:\n 1. Presents the sign-in UI to your users that aren't already signed in.\n 2. Records consent to the requested access in the form of a short-lived authorization code.\n - **Token exchange endpoint:** This endpoint is used to obtain encrypted strings called *tokens* that authorize the Action user to access your service. This endpoint is responsible for two types of exchanges:\n 1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.\n 2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.\n- **Implicit code flow:** During this OAuth 2.0 flow, Google opens your authorization\n endpoint in the user's browser. If sign-in is successful, you return a\n long-lived access token to Google. This access token is then included in\n every request sent from Assistant to your Action. This flow requires\n only an authorization endpoint.\n\n- **Access token:** A token that authorizes your service to access parts of\n a user's data. Access tokens are associated with each individual user\n and should be unguessable.\n\n- **Refresh token:** A token that is exchanged for a new access token once a\n short-lived access token has expired.\n\nHow it works\n------------\n\nThis section describes the general flow for the OAuth authorization code and\nimplicit flows. The following section, [OAuth linking flows](#oauth_linking_flows),\ndescribes the various flows that can occur with OAuth.\n\nThe authorization code flow can be summarized as follows:\n\n1. Your Action asks the user if they want to link their account with your service.\n2. After the user agrees to link accounts, Google opens your authorization endpoint in the user's browser. If the flow started on a voice-only device for an Action, Google would transfer the execution to a phone.\n3. The user signs in (if not signed in already) and grants Google permission to access their data with your API (if they haven't already granted permission).\n4. Your service creates an *authorization code* and returns it to Google by redirecting the user's browser back to Google with the authorization code attached to the request.\n5. Google sends the authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an *access token* and a *refresh token*. The access token is a short-lived token that your service accepts as credentials to access APIs. The refresh token is a long-lived token that Google can store and use to acquire new access tokens when they expire.\n6. After the user has completed the account linking flow, every subsequent request sent from Assistant to your fulfillment webhook contains an access token.\n\nThe implicit code flow can be summarized as follows:\n\n1. Your Action asks the user if they want to link their account with your service.\n2. After the user agrees to link accounts, Google opens your authorization endpoint in the user's browser.\n3. The user signs in (if not signed in already) and grants Google permission to access their data with your API (if they haven't already granted permission).\n4. Your service creates an access token and returns it to Google by redirecting the user's browser back to Google with the access token attached to the request.\n5. After the user has completed the account linking flow, Google calls your service's APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.\n\nThe fundamental authorization code flow is as follows:\n\n1. Your Action asks the user if they want to link their account with your service.\n2. After the user agrees to link accounts, Google opens your authorization endpoint in the user's browser. If the flow started on a voice-only device for an Action, Google would transfer the execution to a phone.\n3. The user signs in (if not signed in already) and grants Google permission to access their data with your API (if they haven't already granted permission).\n4. Your service creates an *authorization code* and returns it to Google by redirecting the user's browser back to Google with the short-lived authorization code attached to the request.\n5. Google sends the authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an *access token* and a *refresh token*. The access token is a short-lived token that your service accepts as credentials to access APIs. The refresh token is a long-lived token that Google can store and use to acquire new access tokens when they expire.\n6. After the user has completed the account linking flow, every subsequent request sent from Assistant to your fulfillment webhook contains an access token.\n\nOAuth linking flows\n-------------------\n\nThis section goes over the various flows that can occur with OAuth linking.\n| **Note:** The following flows assume the user agrees to link their account with your service and grant Google permission to access their data with your API. If a user doesn't give consent, provide them a way to continue in your Action with an alternate, limited flow. For more information, see [Best practices](/assistant/identity/best-practices).\n\nEach flow contains these common steps after the user invokes your Action:\n\n| **Note:** A line from *Webhook* to *User* represents a [simple response](/assistant/conversational/prompts-simple) that you create and customize. Lines drawn from *Assistant* to *User* represent prompts that are owned by Assistant and have limited options for customization (requests that require permission are always owned by Assistant). From the user's perspective, both kinds of responses are delivered from Assistant.\n\nIn the flow above, you transition to the account linking system scene and provide\na customized rationale. Assistant asks the user if they want to link\ntheir account with your service and shows them a screen with the requested\npermissions. When the user consents, Google then redirects the user to your\nservice's authorization endpoint in the browser. The user signs in (or,\ndepending on your configuration, creates a new account) and grants your Action\npermission to access their data.\n\nThe flows after this point differ based on whether or not you implemented\nthe implicit flow or authorization code flow. These flows are described in\nthe following sections.\n\n### Flow 1: User signs in with implicit flow\n\n| **Note:** This diagram builds off of the **Common steps** diagram above.\n\nAfter the user logs in and their credentials are verified, your service creates\na long-lived access token and returns it to Google. At this point, the user's\nidentity in your Action is linked to the account they signed in with, and the\naccess token is attached to each API call Google makes to your service's APIs.\n\n### Flow 2: User signs in with authorization code flow\n\n| **Note:** This diagram builds off of the **Common steps** diagram above.\n\nAfter the user logs in and their credentials are verified, your service creates\nan authorization code and returns it to Google.\n\nThis authorization code is sent to your token exchange endpoint, which returns\nboth an access token and a refresh token. At this point, the user's identity\nin your Action is linked to whatever account they signed in with, and every\nsubsequent request sent from Assistant to your fulfillment contains an\naccess token."]]
