Biblioteka JavaScript google.accounts.oauth2 pomaga wyświetlać prośby o zgodę użytkownika i uzyskiwać token dostępu do danych użytkownika. Opiera się na procesie niejawnego przyznawania uprawnień OAuth 2.0 i umożliwia bezpośrednie wywoływanie interfejsów API Google za pomocą REST i CORS lub korzystanie z naszej biblioteki klienta interfejsów API Google w JavaScript (znanej też jako gapi.client), aby uzyskać prosty i elastyczny dostęp do bardziej złożonych interfejsów API.
Zanim użytkownicy Twojej witryny uzyskają dostęp do chronionych danych użytkowników z poziomu przeglądarki, wywołują w niej proces wyboru konta, logowania i wyrażania zgody w Google. Na koniec serwery OAuth Google wydają token dostępu i zwracają go do Twojej aplikacji internetowej.
W modelu autoryzacji opartej na tokenach nie musisz przechowywać na serwerze backendu tokenów odświeżania poszczególnych użytkowników.
Zalecamy stosowanie podejścia opisanego tutaj zamiast technik omówionych w starszym przewodniku OAuth 2.0 w przypadku aplikacji internetowych działających po stronie klienta.
Wymagania wstępne
Aby skonfigurować ekran zgody OAuth, uzyskać identyfikator klienta i wczytać bibliotekę klienta, wykonaj czynności opisane w sekcji Konfiguracja.
Inicjowanie klienta tokena
Wywołaj funkcję initTokenClient(), aby zainicjować nowego klienta tokena za pomocą identyfikatora klienta aplikacji internetowej. Musisz podać listę co najmniej 1 zakresu, do którego użytkownik potrzebuje dostępu:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (response) => {
...
},
});
Wywołaj przepływ tokena OAuth 2.0
Użyj metody requestAccessToken(), aby uruchomić proces UX tokena i uzyskać token dostępu. Google wyświetla użytkownikowi prośbę o:
- wybrać konto dziecka,
- zalogować się na konto Google, jeśli nie jest jeszcze zalogowany(-a);
- wyrazić zgodę na dostęp aplikacji internetowej do każdego żądanego zakresu.
Gest użytkownika wywołuje proces tokena: <button onclick="client.requestAccessToken();">Authorize me</button>
Następnie Google zwraca do funkcji zwrotnej TokenResponse zawierający token dostępu i listę zakresów, do których użytkownik przyznał dostęp, lub błąd.
Użytkownicy mogą zamknąć okno wyboru konta lub okno logowania. W takim przypadku funkcja wywołania zwrotnego nie zostanie wywołana.
Jak postępować w przypadku zgody użytkowników
Projekt i wygoda użytkowania aplikacji powinny zostać wdrożone dopiero po dokładnym zapoznaniu się z zasadami Google dotyczącymi OAuth 2.0. Te zasady obejmują m.in. pracę z wieloma zakresami oraz to, kiedy i jak uzyskiwać zgodę użytkownika.
Autoryzacja przyrostowa to zasady i metodologia projektowania aplikacji, które służą do żądania dostępu do zasobów za pomocą zakresów tylko w razie potrzeby, a nie z góry i jednocześnie. Użytkownicy mogą zezwolić na udostępnianie poszczególnych zasobów, o które prosi aplikacja, lub odmówić tego. Jest to tzw. szczegółowe określanie uprawnień.
Podczas tego procesu Google prosi użytkownika o zgodę, wyświetlając poszczególne zakresy, o które prosi aplikacja. Użytkownik wybiera zasoby, które mają być udostępniane aplikacji. Na koniec Google wywołuje funkcję wywołania zwrotnego, aby zwrócić token dostępu i zakresy zatwierdzone przez użytkownika. Aplikacja bezpiecznie obsługuje różne wyniki możliwe dzięki szczegółowym uprawnieniom.
Są jednak wyjątki. Aplikacje Google Workspace Enterprise z delegowaniem uprawnień w całej domenie lub aplikacje oznaczone jako Zaufane pomijają ekran zgody na szczegółowe uprawnienia. W przypadku tych aplikacji użytkownicy nie zobaczą ekranu zgody na szczegółowe uprawnienia. Zamiast tego aplikacja otrzyma wszystkie zakresy, o które poprosiła, lub żadne z nich.
Więcej informacji znajdziesz w artykule Jak zarządzać szczegółowymi uprawnieniami.
Autoryzacja przyrostowa
W przypadku aplikacji internetowych te 2 scenariusze wysokiego poziomu pokazują przyrostową autoryzację za pomocą:
- Aplikacja Ajax na jednej stronie, często korzystająca z
XMLHttpRequestz dynamicznym dostępem do zasobów. - Wiele stron internetowych, zasoby są rozdzielone i zarządzane na poziomie poszczególnych stron.
Te 2 scenariusze przedstawiono w celu zilustrowania kwestii związanych z projektowaniem i metodologii, ale nie stanowią one wyczerpujących zaleceń dotyczących sposobu uzyskiwania zgody w aplikacji. Aplikacje w rzeczywistym świecie mogą wykorzystywać odmiany lub kombinacje tych technik.
Ajax
Dodaj do aplikacji obsługę autoryzacji przyrostowej, wykonując wiele wywołań funkcji requestAccessToken() i używając parametru scope obiektu OverridableTokenClientConfig, aby w razie potrzeby i tylko wtedy, gdy jest to konieczne, żądać poszczególnych zakresów. W tym przykładzie zasoby będą wysyłane i widoczne dopiero po tym, jak użytkownik rozwinie zwiniętą sekcję treści.
| Aplikacja Ajax |
|---|
Zainicjuj klienta tokena podczas wczytywania strony:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Dokumenty do przeczytaniaPokaż ostatnie dokumenty
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Nadchodzące wydarzeniaWyświetlanie informacji o kalendarzu
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Karuzela zdjęćWyświetlanie zdjęć
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
Każde wywołanie funkcji requestAccessToken powoduje wyświetlenie prośby o zgodę użytkownika. Aplikacja będzie mieć dostęp tylko do tych zasobów, które są wymagane przez sekcję wybraną przez użytkownika. W ten sposób ograniczone zostanie udostępnianie zasobów na podstawie wyboru użytkownika.
Wiele stron internetowych
W przypadku autoryzacji przyrostowej do wysyłania żądań używa się wielu stron. Żądania dotyczą tylko zakresów wymaganych do wczytania strony, co zmniejsza złożoność i potrzebę wykonywania wielu wywołań w celu uzyskania zgody użytkownika i pobrania tokena dostępu.
| Aplikacja wielostronicowa | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Każda strona żąda niezbędnego zakresu i uzyskuje token dostępu, wywołując funkcje initTokenClient() i requestAccessToken() w momencie wczytywania. W tym scenariuszu poszczególne strony internetowe służą do wyraźnego oddzielenia funkcji i zasobów użytkownika według zakresu. W rzeczywistości poszczególne strony mogą wymagać wielu powiązanych zakresów.
Szczegółowe uprawnienia
Szczegółowe uprawnienia są obsługiwane w ten sam sposób we wszystkich scenariuszach. Po wywołaniu przez funkcję zwrotną i zwróceniu tokena dostępu sprawdź, czy użytkownik zatwierdził żądane zakresy, używając funkcji hasGrantedAllScopes() lub hasGrantedAnyScope().requestAccessToken() Na 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
...
}
}
},
});
W odpowiedzi zostaną też uwzględnione wszystkie wcześniej zaakceptowane przyznania z poprzednich sesji lub żądań. Zapis zgody użytkownika jest przechowywany dla każdego użytkownika i identyfikatora klienta i jest zachowywany w przypadku wielu wywołań funkcji initTokenClient() lub requestAccessToken(). Domyślnie zgoda użytkownika jest wymagana tylko wtedy, gdy po raz pierwszy odwiedza on Twoją witrynę i żąda nowego zakresu, ale może być wymagana przy każdym wczytaniu strony za pomocą parametru prompt=consent w obiektach konfiguracji klienta tokena.
Praca z tokenami
W modelu tokena system operacyjny ani przeglądarka nie przechowują tokena dostępu. Zamiast tego nowy token jest najpierw uzyskiwany w momencie wczytania strony lub później przez wywołanie funkcji requestAccessToken() za pomocą gestu użytkownika, np. naciśnięcia przycisku.
Korzystanie z REST i CORS w interfejsach API Google
Token dostępu może służyć do wysyłania uwierzytelnionych żądań do interfejsów API Google przy użyciu REST i CORS. Umożliwia to użytkownikom logowanie się i wyrażanie zgody, a Google – wydawanie tokena dostępu, dzięki czemu Twoja witryna może korzystać z danych użytkownika.
W tym przykładzie możesz wyświetlić nadchodzące wydarzenia w kalendarzu zalogowanych użytkowników 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.
W następnej sekcji dowiesz się, jak łatwo zintegrować się z bardziej złożonymi interfejsami API.
Praca z biblioteką JavaScript interfejsów API Google
Klient tokena współpracuje z biblioteką klienta interfejsu API Google dla JavaScript. Poniżej znajdziesz fragment kodu.
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 mają z założenia krótki okres ważności. Jeśli token dostępu wygaśnie przed zakończeniem sesji użytkownika, uzyskaj nowy token, wywołując requestAccessToken() w ramach działania użytkownika, np. naciśnięcia przycisku.
Unieważnianie zgody za pomocą tokena dostępu
Wywołaj metodę google.accounts.oauth2.revoke, aby usunąć zgodę użytkownika i dostęp do zasobów we wszystkich zakresach przyznanych Twojej aplikacji. Do wycofania tego uprawnienia wymagany jest prawidłowy token dostępu:
google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
console.log(done);
console.log(done.successful);
console.log(done.error);
console.log(done.error_description);
});