Korzystanie z modelu tokena

Biblioteka JavaScript google.accounts.oauth2 ułatwia wyświetlenie prośby o zgodę użytkownika i uzyskanie tokena dostępu do współpracy z danymi. Opiera się on na procesie przyznawania uprawnień przy użyciu protokołu OAuth 2.0 i umożliwia bezpośrednie wywoływanie interfejsów API Google przy użyciu REST i CORS lub używanie biblioteki klienta interfejsów API Google dla JavaScriptu (znanej też jako gapi.client) w celu łatwego i elastycznego dostępu do bardziej złożonych interfejsów API.

Przed uzyskaniem w przeglądarce dostępu do zabezpieczonych danych o użytkownikach użytkownicy uruchamiają proces wyboru konta internetowego, logowania i uzyskiwania zgody na wykorzystanie danych przez Google, a na koniec udostępniają serwery OAuth Google i zwracają token dostępu.

W modelu autoryzacji opartym na tokenach nie ma potrzeby przechowywania tokenów odświeżania poszczególnych użytkowników na serwerze backendu.

Zalecamy stosowanie się do opisanego tu rozwiązania, a nie tylko do metod opisanych w przewodniku OAuth 2.0 for Internet-side Applications (Aplikacje po stronie klienta) OAuth.

Konfiguracja

Znajdź lub utwórz identyfikator klienta, wykonując czynności opisane w przewodniku Znajdowanie identyfikatora klienta Google API. Następnie dodaj bibliotekę klienta do stron w swojej witrynie, które będą wywoływać interfejsy API Google. Na koniec zainicjuj klienta tokena. Zwykle można to zrobić w module obsługi klienta onload.

Inicjowanie klienta tokena

Wywołaj initTokenClient(), aby zainicjować nowego klienta tokena za pomocą identyfikatora klienta aplikacji internetowej, opcjonalnie możesz dodać listę co najmniej 1 zakresu, do którego użytkownik musi mieć dostęp:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

Aktywowanie przepływu tokena OAuth 2.0

Aby wywołać proces UX tokena i uzyskać token dostępu, użyj metody requestAccessToken(). Google prosi użytkownika o wykonanie tych czynności:

• Wybierz ich konto.
• aby zalogować się na konto Google,
• wyrazić zgodę na dostęp aplikacji internetowej do każdego żądanego zakresu.

Gest użytkownika uruchamia przepływ tokena: <button onclick="client.requestAccessToken();">Authorize me</button>

Google zwraca wtedy TokenResponse z tokenem dostępu i listą zakresów, do których użytkownik przyznał dostęp (czyli błąd) modułowi wywołania zwrotnego.

Użytkownicy mogą zamknąć selektor konta lub okna logowania. W takim przypadku funkcja wywołania zwrotnego nie będzie wywoływana.

Jak obsługiwać zgodę

Projekt i działanie aplikacji należy wdrożyć dopiero po dokładnym sprawdzeniu zasad OAuth 2.0 Google. Te zasady obejmują m.in. pracę z wieloma zakresami oraz to, jak i jak obsługiwać zgody użytkowników.

Autoryzacja przyrostowa to zasada i metodologia projektowania aplikacji używana do żądania dostępu do zasobów za pomocą zakresów tylko wtedy, gdy jest to konieczne, a nie z góry i jednocześnie. Użytkownicy mogą zatwierdzać lub odrzucać udostępnianie poszczególnych zasobów wymaganych przez aplikację. Są to tzw. uprawnienia szczegółowe.

Podczas tego procesu Google wyświetla prośbę o zgodę użytkownika, wyświetlając informacje o każdym wybranym zakresie w zakresie. Użytkownik wybiera zasoby, które chce udostępnić aplikacji. Na koniec Google wywołuje funkcję wywołania zwrotnego, aby zwrócić token dostępu i zakresy zatwierdzone przez użytkownika. Dzięki aplikacji możesz bez trudu zarządzać różnymi możliwymi rezultatami przy użyciu szczegółowych uprawnień.

Autoryzacja przyrostowa

W przypadku aplikacji internetowych te 2 główne scenariusze przedstawiają przyrostową autoryzację przy użyciu:

• Pojedyncza aplikacja Ajax, często korzystająca z XMLHttpRequest z dynamicznym dostępem do zasobów.
• Wiele stron internetowych i zasobów jest zarządzanych osobno dla każdej strony.

Te 2 scenariusze przedstawiają przykłady i metodologie projektowania, ale nie są wyczerpujące i rekomendują sposób uzyskiwania zgody na używanie danych w aplikacjach. Prawdziwe aplikacje mogą wykorzystywać warianty lub kombinacje tych technik.

Ajax

Dodaj do swojej aplikacji obsługę przyrostowej autoryzacji, wysyłając wiele wywołań requestAccessToken() i używając parametru OverridableTokenClientConfig obiektu scope, aby zażądać poszczególnych zakresów w razie potrzeby i tylko w razie potrzeby. W tym przykładzie zasoby będą żądane i widoczne dopiero po rozwinięciu gestu użytkownika.

        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
      

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );
        

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );
        

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );
        

Każde wywołanie metody requestAccessToken wywołuje moment wyrażenia zgody przez użytkownika. Twoja aplikacja będzie mieć dostęp tylko do zasobów wymaganych przez sekcję rozwijaną przez użytkownika, przez co udostępnianie zasobów będzie ograniczone przez wybór użytkownika.

Wiele stron internetowych

Podczas projektowania autoryzacji przyrostowej wiele stron jest używanych do zażądania tylko tych zakresów, które są wymagane do załadowania strony, co zmniejsza stopień złożoności i musi wywoływać wiele wywołań w celu uzyskania zgody użytkownika oraz pobrania tokena dostępu.

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
          

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();
          

Każda strona prosi o wymagany zakres i otrzymuje token dostępu, wywołując w czasie wczytywania initTokenClient() i requestAccessToken(). W tym przypadku pojedyncze strony internetowe służą do wyraźnie wyodrębnienia funkcji i zasobów użytkownika według zakresu. W rzeczywistości rzeczywiste strony mogą żądać wielu powiązanych zakresów.

Uprawnienia szczegółowe

Wszystkie uprawnienia są obsługiwane w ten sam sposób we wszystkich scenariuszach. Po wywołaniu funkcji requestAccessToken() przez wywołanie zwrotne i zwróceniu tokena dostępu sprawdź, czy użytkownik zatwierdził żądane zakresy za pomocą atrybutu hasGrantedAllScopes() lub hasGrantedAnyScope(). Przykład:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

Wszelkie odpowiedzi przyznane wcześniej w poprzednich sesjach i prośbach będą także uwzględnione w odpowiedzi. Rejestr zgody użytkownika jest przechowywany dla każdego użytkownika i identyfikatora klienta i powtarza się w wielu wywołaniach metody initTokenClient() lub requestAccessToken(). Domyślnie zgoda użytkownika jest potrzebna tylko wtedy, gdy użytkownik po raz pierwszy odwiedza Twoją witrynę i prosi o nowy zakres, ale może być żądana podczas każdego wczytywania strony za pomocą prompt=consent w obiektach konfiguracyjnych klienta tokena.

Praca z tokenami

W modelu tokena token dostępu nie jest przechowywany przez system operacyjny ani przeglądarkę. Zamiast tego nowy token jest pobierany podczas wczytywania strony albo przez wywołanie metody requestAccessToken() za pomocą gestu użytkownika, np. kliknięcia przycisku.

Używanie interfejsów API REST i CORS w interfejsach API Google

Tokena dostępu można używać do wysyłania uwierzytelnionych żądań do interfejsów API Google przy użyciu REST i CORS. Dzięki temu użytkownicy mogą się logować, udzielać zgody i wysyłać token dostępu oraz Twoją witrynę, aby mógł on korzystać z danych użytkownika.

W tym przykładzie zobacz zalogowanych użytkowników nadchodzących wydarzeń w kalendarzu za pomocą tokena dostępu zwróconego przez tokenRequest():

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

Więcej informacji znajdziesz w artykule Jak używać CORS do uzyskiwania dostępu do interfejsów API Google.

Kolejna sekcja zawiera informacje o tym, jak łatwo zintegrować ją ze bardziej złożonymi interfejsami API.

Korzystanie z biblioteki JavaScript interfejsów API Google

Klient tokena współpracuje z biblioteką klienta interfejsu API Google dla języka JavaScript Fragment kodu poniżej.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

Wygaśnięcie tokena

Tokeny dostępu są zaprojektowane w krótkim czasie. Jeśli token dostępu wygaśnie przed zakończeniem sesji użytkownika, zdobądź nowy token, wywołując requestAccessToken() z zdarzenia wywoływanego przez użytkownika, np. naciskając przycisk.

Używanie tokena dostępu do cofnięcia zgody

Wywołaj metodę google.accounts.oauth2.revoke, by usunąć zgodę użytkownika i dostęp do zasobów we wszystkich zakresach przyznanych aplikacji. Aby to uprawnienie zostało anulowane, wymagany jest prawidłowy dostęp:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
    console.log(done);
    console.log(done.successful);
    console.log(done.error);
    console.log(done.error_description);
  });