OAuth 계정 연결 유형은 두 가지 업계 표준 OAuth 2.0 흐름, 즉 암시적 흐름과 승인 코드 흐름을 지원합니다. 암시적 코드 흐름에서는 Google이 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 로그인에 성공하면 유효 기간이 긴 액세스 토큰이 Google에 반환됩니다. 그러면 이 액세스 토큰은 어시스턴트에서 작업으로 전송되는 모든 요청에 포함됩니다.
다음과 같은 경우 OAuth가 권장되는 계정 연결 솔루션입니다.
OAuth 2.0 서버의 기존 구현이 있으며 토큰 교환 엔드포인트를 확장하여 ID 토큰에서 자동 연결 및 계정 생성을 위한 Google 프로토콜 지원을 추가할 수 없습니다 (즉, 이 엔드포인트에 대한 요청에 intent=get 및 intent=create 매개변수 추가).
계정 로그인 도우미 인텐트: 어시스턴트에서 계정 연결 흐름을 요청하기 위해 호출하는 도우미 인텐트입니다. 자세한 내용은 계정 로그인을 참고하세요.
컨텍스트 문자열: 계정 로그인 도우미 인텐트에 추가되는 맞춤설정된 문자열로, 사용자에게 계정을 연결해야 하는 이유를 알려줍니다.
승인 코드 흐름: 이 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에서 발생할 수 있는 다양한 흐름을 살펴봅니다.
각 흐름에는 사용자가 작업을 호출한 후의 일반적인 단계가 포함됩니다.
위의 흐름에서 actions.intent.SIGN_IN 도우미 인텐트를 호출하여 계정 연결 흐름을 시작합니다. 어시스턴트는 사용자에게 계정을 서비스와 연결할지 여부를 묻고 요청된 권한이 포함된 화면을 표시합니다. 사용자가 동의하면 Google은 사용자를 브라우저에서 서비스의 승인 엔드포인트로 리디렉션합니다. 사용자가 로그인하거나 구성에 따라 새 계정을 만들고 데이터에 액세스할 수 있는 작업 권한을 부여합니다.
이 시점 이후의 흐름은 암시적 흐름 또는 승인 코드 흐름을 구현했는지 여부에 따라 다릅니다. 이러한 흐름은 다음 섹션에서 설명합니다.
흐름 1: 사용자가 암시적 흐름으로 로그인
사용자가 로그인하고 사용자 인증 정보가 확인되면 서비스는 수명이 긴 액세스 토큰을 만들어 Google에 반환합니다. 이 시점에서 작업의 사용자 ID는 사용자가 로그인한 계정에 연결되며 액세스 토큰은 Google이 서비스의 API에 수행하는 각 API 호출에 연결됩니다.
절차 2: 사용자가 승인 코드 흐름으로 로그인하기
사용자가 로그인하고 사용자 인증 정보가 확인되면 서비스에서 승인 코드를 만들어 Google로 반환합니다.
이 승인 코드는 액세스 토큰과 갱신 토큰을 모두 반환하는 토큰 교환 엔드포인트로 전송됩니다. 이 시점에서 작업의 사용자 ID는 사용자가 로그인한 계정에 연결되며, 어시스턴트에서 처리로 전송되는 후속 모든 요청에는 액세스 토큰이 포함됩니다.
[null,null,["최종 업데이트: 2025-07-26(UTC)"],[[["\u003cp\u003eOAuth account linking, utilizing OAuth 2.0 implicit or authorization code flows, securely connects users' Google accounts with your service.\u003c/p\u003e\n"],["\u003cp\u003eIn the implicit flow, a long-lived access token is returned directly upon successful login; whereas, the authorization code flow involves an intermediary code exchange for enhanced security.\u003c/p\u003e\n"],["\u003cp\u003eOAuth is recommended if you already use OAuth 2.0 and cannot adapt your token exchange endpoint for Google's automatic linking protocols.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Assistant guides users through an account linking process, prompting for consent and redirecting to your authorization endpoint for sign-in and data access permission.\u003c/p\u003e\n"],["\u003cp\u003eAccess tokens, attached to subsequent requests, grant your service authorized access to user data, with refresh tokens ensuring continued access.\u003c/p\u003e\n"]]],[],null,["# OAuth concept guide (Dialogflow)\n\nThe OAuth account 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 the Assistant to your Action.\n\nOAuth 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 is the right solution for you, see the\n[Choose your account linking type](/assistant/df-asdk/identity/choose-type) page.\n\nKey terms\n---------\n\nBefore you read about how OAuth works, familiarize yourself with the following terms:\n\n- **Account sign-in helper intent:** A helper intent that you call to request an account linking flow from the Assistant. For more information, see [Account Sign-in](/assistant/df-asdk/helpers#account_sign-in).\n - **Context string:** A customized string that you add to the account sign-in helper intent that tells the user why you need them to link their account.\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 the 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 flows](#oauth_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 the 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 the Assistant to your fulfillment webhook contains an access token.\n\nOAuth flows\n-----------\n\nThis section goes over the various flows that can occur with OAuth.\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/df-asdk/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/df-asdk/simple-responses) that you create and customize. Lines drawn from *Assistant* to *User* represent prompts that are owned by the Assistant and have limited options for customization (requests that require permission are always owned by the Assistant). From the user's perspective, both kinds of responses are delivered from the Assistant.\n\nIn the flow above, you call the `actions.intent.SIGN_IN` helper intent to start\nthe account linking flow. The 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 the Assistant to your fulfillment contains an\naccess token."]]
