Łączenie kont za pomocą protokołu OAuth (Dialogflow)

Typ połączenia OAuth obsługuje dwa standardy branżowe przepływów OAuth 2.0: przepływy kodu implicit i autoryzacji.

W pośrednim przepływie kodu Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Po udanym logowaniu zwracasz token dostępu o długim czasie do Google. Ten token dostępu jest teraz dołączany do każdego żądania wysyłanego przez Asystenta do działania.

W ramach procesu kodu autoryzacji potrzebujesz 2 punktów końcowych:

• Punkt końcowy autoryzacji, który odpowiada za wyświetlanie interfejsu logowania użytkownikom, którzy nie są jeszcze zalogowani, i rejestrowanie zgody w żądanym terminie w postaci kodu o ograniczonym czasie ważności.
• Punkt końcowy giełdy tokenów odpowiedzialny za 2 typy giełd:
  1. Wymienia kod autoryzacji tokena długoterminowego i tokena dostępu o ograniczonym czasie ważności. Ta wymiana ma miejsce, gdy użytkownik przechodzi przez proces łączenia kont.
  2. Wymienia długotrwały token odświeżania na token dostępu o ograniczonym czasie ważności. Ta giełda ma miejsce, gdy Google potrzebuje nowego tokena dostępu, ponieważ wygasł.

Implementacja niejawnego przepływu kodu jest prostsza, ale Google zaleca, aby tokeny dostępu wydane z wykorzystaniem niejawnego przepływu nigdy nie wygasały, ponieważ korzystanie z tożsamości w wyniku takiego działania wymusza na użytkowniku ponowne połączenie konta. Jeśli ze względów bezpieczeństwa zależy Ci na wygaśnięciu tokena, rozważ użycie kodu uwierzytelniania.

Uwaga: wybierz przepływ OAuth2, który chcesz zaimplementować. W razie potrzeby treść przewodnika zostanie ponownie załadowana, aby dostosować się do wybranych przez Ciebie ustawień.

Kod autoryzacji Przewidujący przepływ

Wdrażanie łączenia kont OAuth

Uwaga: jeśli wdrażasz łączenie kont w celu obsługi informacji finansowych, pamiętaj, że do akcji mogą obowiązywać dodatkowe zasady. Weryfikacja działania powiązanego z kontem pod kątem informacji finansowych może potrwać do 6 tygodni, więc należy uwzględnić ten czas podczas planowania harmonogramu publikacji. Aby ułatwić proces weryfikacji, zanim prześlesz akcję do sprawdzenia, upewnij się, że przestrzegasz zasad dotyczących usług finansowych.

Konfigurowanie projektu

Aby skonfigurować projekt do korzystania z łączenia z kontem OAuth, wykonaj te czynności:

1. Otwórz Konsolę Actions i wybierz projekt, którego chcesz użyć.
2. Kliknij kartę Programowanie i wybierz Łączenie kont.
3. Włącz przełącznik obok opcji Łączenie kont.
4. W sekcji Tworzenie konta wybierz Nie, chcę zezwolić na tworzenie konta tylko na mojej stronie internetowej.

5. W sekcji Typ połączenia wybierz OAuth i OAuth.

   

6. W sekcji Informacje o kliencie:

   • Przypisz wartość do Identyfikatora klienta wydanego przez Actions to Google, aby identyfikować żądania pochodzące od Google.
   • Wstaw adresy URL punktów końcowych autoryzacji i Token Exchange.

Uwaga: jeśli chcesz, aby Twój identyfikator klienta był wysyłany jako ciąg zakodowany w base64, kliknij strzałkę obok opcji Skonfiguruj klienta (opcjonalnie) i zaznacz pole Google ma przesyłać identyfikator klienta i obiekt tajny za pomocą nagłówka uwierzytelniania podstawowego HTTP.

6. Kliknij Zapisz.

Wdrażanie serwera OAuth

Aby obsługiwać przepływ niejawny OAuth 2.0, Twoja usługa udostępnia punkt końcowy autoryzacji za pomocą protokołu HTTPS. Ten punkt końcowy odpowiada za uwierzytelnianie i uzyskiwanie od użytkowników zgody na dostęp do danych. Punkt końcowy autoryzacji wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani, i zapisuje zgodę na przyznanie dostępu.

Gdy akcja musi wywołać jeden z autoryzowanych interfejsów API Twojej usługi, Google używa tego punktu końcowego, aby uzyskać od użytkowników uprawnienia do wywoływania tych interfejsów API w ich imieniu.

Typowa sesja przepływu niejawnego OAuth 2.0 zainicjowana przez Google ma taki przepływ:

1. Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Użytkownik loguje się, jeśli jeszcze nie jest zalogowany, i przyznaje Google uprawnienia dostępu do swoich danych za pomocą Twojego interfejsu API, jeśli jeszcze tego nie zrobił.
2. Usługa tworzy token dostępu i zwraca go do Google, przekierowując przeglądarkę użytkownika z powrotem do Google z tokenem dostępu dołączonym do żądania.
3. Google wywołuje interfejsy API Twojej usługi i do każdego żądania dołącza token dostępu. Twoja usługa sprawdza, czy token dostępu przyznaje Google autoryzację dostępu do interfejsu API, a następnie wykonuje wywołanie interfejsu API.

Obsługa żądań autoryzacji

Gdy akcja musi przeprowadzić łączenie kont w ramach niejawnego przepływu o protokołu OAuth2, Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem zawierającym te parametry:

Parametry punktu końcowego autoryzacji
client_id	Identyfikator klienta przypisany przez Ciebie do Google.
redirect_uri	Adres URL, na który wysyłasz odpowiedź na to żądanie.
state	Wartość księgowa, która jest zwracana do Google bez zmian w identyfikatorze URI przekierowania.
response_type	Typ wartości do zwrócenia w odpowiedzi. W przypadku przepływu niejawnego OAuth 2.0 typ odpowiedzi to zawsze token.

Jeśli na przykład punkt końcowy autoryzacji jest dostępny pod adresem https://myservice.example.com/auth, żądanie może wyglądać tak:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

Aby punkt końcowy autoryzacji obsługiwał żądania logowania, wykonaj te czynności:

1. Sprawdź wartości client_id i redirect_uri, aby zapobiec przyznaniu dostępu do niezamierzonych lub błędnie skonfigurowanych aplikacji klienckich:

   • Sprawdź, czy client_id jest zgodny z identyfikatorem klienta przypisanym przez Ciebie do Google.
   • Sprawdź, czy adres URL określony przez parametr redirect_uri ma taki format:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID to identyfikator znajdujący się na stronie Ustawienia projektu w Konsoli Actions.

2. Sprawdź, czy użytkownik jest zalogowany w Twojej usłudze. Jeśli użytkownik nie jest zalogowany, dokończ proces logowania lub rejestracji w usłudze.

3. Wygeneruj token dostępu, którego Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Token dostępu może być dowolną wartością ciągu znaków, ale musi w unikalny sposób reprezentować użytkownika oraz klienta, dla którego jest przeznaczony. Token nie może dać się odgadnąć.

4. Wyślij odpowiedź HTTP, która przekierowuje przeglądarkę użytkownika pod adres URL określony w parametrze redirect_uri. We fragmencie adresu URL uwzględnij wszystkie te parametry:

   • access_token: wygenerowany przed chwilą token dostępu;
   • token_type: ciąg znaków bearer.
   • state: niezmodyfikowana wartość stanu z pierwotnego żądania. Oto przykład wynikowego adresu URL:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Moduł obsługi przekierowań OAuth 2.0 Google otrzyma token dostępu i sprawdzi, czy wartość state się nie zmieniła. Gdy Google uzyska token dostępu do Twojej usługi, będzie dołączać go do kolejnych wywołań akcji w ramach żądania AppRequest.

Rozpocznij proces uwierzytelniania

Ostrzeżenie: na początku rozmowy z akcją nie wyświetlaj użytkownikom wymaganego prośby o połączenie kont. Zamiast tego zorganizuj nieuwierzytelnionym użytkownikom tryb gościa, aby pokazać, jak działa akcja, i poproś o połączenie kont tylko wtedy, gdy jest to konieczne. Jeśli użytkownicy regularnie opuszczają akcję z powodu problemów z połączeniem kont, Google nie będzie aktywnie promować tego działania, co może zmniejszyć ruch generowany przez akcję.

Aby rozpocząć proces uwierzytelniania, użyj intencji pomocniczej logowania na konto. Poniższe fragmenty kodu opisują, jak wysłać odpowiedź w Dialogflow i pakiecie Actions SDK na potrzeby tego narzędzia pomocniczego.

Dialogflow:

Node.js

const {dialogflow, SignIn} = require('actions-on-google');
const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
});
// Intent that starts the account linking flow.
app.intent('Start Signin', (conv) => {
  conv.ask(new SignIn('To get your account details'));
});

Java

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

JSON

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "PLACEHOLDER"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}",
      "systemIntent": {
        "intent": "actions.intent.SIGN_IN",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec",
          "optContext": "To get your account details"
        }
      }
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{}"
      }
    }
  ]
}

Pakiet SDK Actions:

Node.js

const {actionssdk, SignIn} = require('actions-on-google');
const app = actionssdk({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
});
// Intent that starts the account linking flow.
app.intent('actions.intent.TEXT', (conv) => {
  conv.ask(new SignIn('To get your account details'));
});

Java

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

JSON

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "PLACEHOLDER"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.SIGN_IN",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec",
            "optContext": "To get your account details"
          }
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{}}"
}

Obsługiwanie próśb o dostęp do danych

Jeśli żądanie Asystenta zawiera token dostępu, najpierw sprawdź, czy token dostępu jest prawidłowy (i nie wygasł), a następnie pobierz powiązane konto użytkownika z bazy danych.