Biblioteka JavaScript autoryzacji firm zewnętrznych w witrynach – informacje o interfejsie API

W tym artykule znajdziesz opis interfejsu API bibliotek JavaScript autoryzacji Google 3P, którego możesz używać do wczytywania kodów autoryzacji i uzyskiwania dostępu do tokenów od Google.

Metoda: google.accounts.oauth2.initCodeClient

Metoda initCodeClient inicjuje i zwraca klienta kodu z konfiguracjami w parametrze.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

Typ danych: CodeClientConfig

W tabeli poniżej znajdziesz listę właściwości typu danych CodeClientConfig.

Właściwości
client_id Wymagane. Identyfikator klienta Twojej aplikacji. Tę wartość możesz znaleźć w konsoli interfejsu API.
scope Wymagane. Lista rozdzielonych spacjami zakresów identyfikujących zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi.
include_granted_scopes Opcjonalnie: wartość domyślna to true. Zezwala aplikacjom na używanie przyrostowej autoryzacji do żądania dostępu do dodatkowych zakresów kontekstowych. Jeśli ustawisz wartość tego parametru na false i żądanie autoryzacji zostanie przyznane, nowy token dostępu będzie obejmować tylko zakresy, do których scope żąda danych w CodeClientConfig.
redirect_uri Wymagane do UX przekierowania. Określa, gdzie serwer interfejsu API przekierowuje użytkownika po zakończeniu procesu autoryzacji. Wartość musi być zgodna z jednym z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0, które zostały skonfigurowane w konsoli API i muszą być zgodne z naszymi regułami weryfikacji przekierowania URI. Usługa zostanie zignorowana przez wyskakujące okienko.
callback Wymagane na potrzeby UX wyskakującego okienka. Funkcja JavaScript, która obsługuje zwracaną odpowiedź z kodem. Usługa będzie ignorowana przez przekierowanie użytkownika.
state Opcjonalnie. Zalecany do UX przekierowania. Określa wartość ciągu, której aplikacja używa do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.
enable_serial_consent Opcjonalnie: wartość domyślna to true. Jeśli ma wartość false, bardziej szczegółowe uprawnienia konta Google zostaną wyłączone w przypadku identyfikatorów klienta OAuth utworzonych przed 2019 rokiem. Nie ma wpływu na nowsze identyfikatory klientów OAuth, ponieważ zawsze mają one bardziej szczegółowe uprawnienia.
login_hint Opcjonalnie. Jeśli aplikacja wie, który użytkownik powinien autoryzować żądanie, może za pomocą tej właściwości podać Google dane logowania. Pomyślne pominięcie konta zostanie pominięte. Wartość pola sub adresu e-mail lub tokena tożsamości użytkownika docelowego. Więcej informacji znajdziesz w polu login_hint w dokumentacji OpenID Connect.
hd Opcjonalnie. Jeśli Twoja aplikacja zna domenę Workspace, do której należy użytkownik, podaj tę wskazówkę dla Google. Pomyślne utworzenie kont użytkowników jest ograniczone lub wstępnie wybrane do podanej domeny. Więcej informacji znajdziesz w polu hd w dokumentacji OpenID Connect.
ux_mode Opcjonalnie. Tryb UX używany podczas procesu autoryzacji. Domyślnie będzie on otwierany w wyskakującym okienku. Prawidłowe wartości to popup i redirect.
select_account Opcjonalnie: wartość domyślna to 'false'. Wartość logiczna zachęcająca użytkownika do wybrania konta.
error_callback Opcjonalnie. Funkcja JavaScript, która obsługuje niektóre błędy inne niż OAuth, na przykład nie udało się otworzyć wyskakującego okienka lub została zamknięta przed zwróceniem odpowiedzi OAuth.

Pole „type” parametru wejściowego zawiera szczegółową przyczynę.
  • popup_failed_to_open Nie udało się otworzyć wyskakującego okienka.
  • popup_closed Wyskakujące okienko jest zamykane przed zwróceniem odpowiedzi OAuth.
  • Nieznana zmienna, która zawiera inne błędy.

Typ danych: CodeClient

Klasa ma tylko 1 publiczną metodę requestCode, która uruchamia proces UX kodu OAuth 2.0.

interface CodeClient {
  requestCode(): void;
}

Typ danych: CodeResponse

Obiekt JavaScript CodeResponse zostanie przekazany do metody callback w wyskakującym okienku UX. W interfejsie użytkownika przekierowania CodeResponse jest przekazywany jako parametry adresu URL.

W tabeli poniżej znajdziesz listę właściwości typu danych CodeResponse.

Właściwości
code Kod autoryzacji odpowiedzi na token.
scope Lista rozdzielonych spacjami zakresów, które zostały zatwierdzone przez użytkownika.
state Wartość ciągu znaków, której aplikacja używa do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią.
error Pojedynczy kod błędu ASCII.
error_description Czytelny dla człowieka tekst ASCII, zawierający dodatkowe informacje, który pomaga deweloperowi zrozumieć problem, który wystąpił.
error_uri Identyfikator URI informujący użytkownika o błędzie czytelny dla człowieka, który zawiera dodatkowe informacje o błędzie.

Metoda: google.accounts.oauth2.initTokenClient

Metoda initTokenClient inicjuje i zwraca klienta klienta z konfiguracjami w parametrze.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

Typ danych: TokenClientConfig

W tabeli poniżej znajdziesz listę właściwości typu danych TokenClientConfig.

Właściwości
client_id Wymagane. Identyfikator klienta Twojej aplikacji. Tę wartość możesz znaleźć w konsoli interfejsu API.
callback Wymagane. Funkcja JavaScript, która obsługuje zwracaną odpowiedź tokena.
scope Wymagane. Lista rozdzielonych spacjami zakresów identyfikujących zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi.
include_granted_scopes Opcjonalnie: wartość domyślna to true. Zezwala aplikacjom na używanie przyrostowej autoryzacji do żądania dostępu do dodatkowych zakresów kontekstowych. Jeśli ustawisz wartość tego parametru na false i żądanie autoryzacji zostanie przyznane, nowy token dostępu będzie obejmować tylko zakresy, do których scope żąda danych w TokenClientConfig.
prompt Opcjonalnie: wartość domyślna to 'select_account'. Rozdzielona spacjami wielkość liter z prośbą o przedstawienie użytkownika. Możliwe wartości:
  • pusty ciąg. Użytkownik zostanie poproszony tylko za pierwszym razem, gdy poprosi o dostęp do aplikacji. Nie można go określić, używając innych wartości.
  • 'none' Nie wyświetlaj żadnych ekranów uwierzytelniania ani zgody. Nie można go podawać razem z innymi wartościami.
  • 'consent' Pytaj użytkownika o zgodę.
  • 'select_account' Poproś użytkownika o wybranie konta.
enable_serial_consent Opcjonalnie: wartość domyślna to true. Jeśli ma wartość false, bardziej szczegółowe uprawnienia konta Google zostaną wyłączone w przypadku identyfikatorów klienta OAuth utworzonych przed 2019 rokiem. Nie ma wpływu na nowsze identyfikatory klientów OAuth, ponieważ zawsze mają one bardziej szczegółowe uprawnienia.
login_hint Opcjonalnie. Jeśli aplikacja wie, który użytkownik powinien autoryzować żądanie, może za pomocą tej właściwości podać Google dane logowania. Pomyślne pominięcie konta zostanie pominięte. Wartość pola sub adresu e-mail lub tokena tożsamości użytkownika docelowego. Więcej informacji znajdziesz w polu login_hint w dokumentacji OpenID Connect.
hd Opcjonalnie. Jeśli Twoja aplikacja zna domenę Workspace, do której należy użytkownik, podaj tę wskazówkę dla Google. Pomyślne utworzenie kont użytkowników jest ograniczone lub wstępnie wybrane do podanej domeny. Więcej informacji znajdziesz w polu hd w dokumentacji OpenID Connect.
state Opcjonalnie. Niezalecane. Określa wartość ciągu, której aplikacja używa do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.
error_callback Opcjonalnie. Funkcja JavaScript, która obsługuje niektóre błędy inne niż OAuth, na przykład nie udało się otworzyć wyskakującego okienka lub została zamknięta przed zwróceniem odpowiedzi OAuth.

Pole „type” parametru wejściowego zawiera szczegółową przyczynę.
  • popup_failed_to_open Nie udało się otworzyć wyskakującego okienka.
  • popup_closed Wyskakujące okienko jest zamykane przed zwróceniem odpowiedzi OAuth.
  • Nieznana zmienna, która zawiera inne błędy.

Typ danych: TokenClient

Klasa ma tylko jedną metodę publiczną requestAccessToken, która uruchamia proces UX tokena OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argumenty
overrideConfig OverridableTokenClientConfig Opcjonalnie. Konfiguracje, które mają zostać zastąpione w tej metodzie.

Typ danych: OverridableTokenClientConfig

W tabeli poniżej znajdziesz listę właściwości typu danych OverridableTokenClientConfig.

Właściwości
scope Opcjonalnie. Lista rozdzielonych spacjami zakresów identyfikujących zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi.
include_granted_scopes Opcjonalnie: wartość domyślna to true. Zezwala aplikacjom na używanie przyrostowej autoryzacji do żądania dostępu do dodatkowych zakresów kontekstowych. Jeśli ustawisz wartość tego parametru na false i żądanie autoryzacji zostanie przyznane, nowy token dostępu będzie obejmować tylko zakresy, do których scope żąda danych w OverridableTokenClientConfig.
prompt Opcjonalnie. Rozdzielona spacjami wielkość liter z prośbą o przedstawienie użytkownika.
enable_serial_consent Opcjonalnie: wartość domyślna to true. Jeśli ma wartość false, bardziej szczegółowe uprawnienia konta Google zostaną wyłączone w przypadku identyfikatorów klienta OAuth utworzonych przed 2019 rokiem. Nie ma wpływu na nowsze identyfikatory klientów OAuth, ponieważ zawsze mają one bardziej szczegółowe uprawnienia.
login_hint Opcjonalnie. Jeśli aplikacja wie, który użytkownik powinien autoryzować żądanie, może za pomocą tej właściwości podać Google dane logowania. Pomyślne pominięcie konta zostanie pominięte. Wartość pola sub adresu e-mail lub tokena tożsamości użytkownika docelowego. Więcej informacji znajdziesz w polu login_hint w dokumentacji OpenID Connect.
state Opcjonalnie. Niezalecane. Określa wartość ciągu, której aplikacja używa do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.

Typ danych: TokenResponse

Obiekt JavaScript TokenResponse zostanie przekazany do Twojej metody wywołania zwrotnego w interfejsie wyskakującego okienka.

W tabeli poniżej znajdziesz listę właściwości typu danych TokenResponse.

Właściwości
access_token Token dostępu do udanej odpowiedzi tokena.
expires_in Czas życia tokena dostępu w sekundach.
hd Domena hostowana, do której należy zalogowany użytkownik.
prompt Wartość komunikatu, która została użyta z możliwej listy wartości określonej przez TokenClientConfig lub OverridableTokenClientConfig.
token_type Typ wydanego tokena.
scope Lista rozdzielonych spacjami zakresów, które zostały zatwierdzone przez użytkownika.
state Wartość ciągu znaków, której aplikacja używa do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią.
error Pojedynczy kod błędu ASCII.
error_description Czytelny dla człowieka tekst ASCII, zawierający dodatkowe informacje, który pomaga deweloperowi zrozumieć problem, który wystąpił.
error_uri Identyfikator URI informujący użytkownika o błędzie czytelny dla człowieka, który zawiera dodatkowe informacje o błędzie.

Metoda: google.accounts.oauth2.hasGrantedAllScopes

Sprawdza, czy użytkownik przyznał wszystkie określone zakresy lub zakresy.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
Argumenty
tokenResponse TokenResponse Wymagane. Obiekt TokenResponse.
firstScope tekst Wymagane. Zakres do sprawdzenia.
restScopes ciąg znaków[] Opcjonalnie. Inne zakresy do sprawdzenia.
Zwroty
wartość logiczna Wartość „prawda”, jeśli zostały przyznane wszystkie zakresy.

Metoda: google.accounts.oauth2.hasGranted AnyScope

Sprawdza, czy użytkownik przyznał którykolwiek z podanych zakresów.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Argumenty
tokenResponse TokenResponse Wymagane. Obiekt TokenResponse.
firstScope tekst Wymagane. Zakres do sprawdzenia.
restScopes ciąg znaków[] Opcjonalnie. Inne zakresy do sprawdzenia.
Zwroty
wartość logiczna Wartość „prawda”, jeśli został przyznany dowolny zakres.

Metoda: google.accounts.oauth2.revoke

Metoda revoke unieważnia wszystkie zakresy przyznane użytkownikowi przez aplikację. Do unieważnienia uprawnień wymagany jest prawidłowy token dostępu.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Argumenty
accessToken tekst Wymagane. Prawidłowy token dostępu.
callback funkcja Opcjonalnie. Moduł obsługi RevocationResponse.

Typ danych: RevocationResponse

Obiekt JavaScript RevocationResponse zostanie przekazany do Twojej metody wywołania zwrotnego.

W tabeli poniżej znajdziesz listę właściwości typu danych RevocationResponse.

Właściwości
successful Wartość logiczna. true w przypadku powodzenia, false w przypadku niepowodzenia.
error Ciąg tekstowy. Nie określono przyczyny sukcesu. Pojedynczy kod błędu ASCII. Obejmuje to m.in. standardowe kody błędów OAuth 2.0. Typowe błędy występujące w przypadku metody revoke:
  • invalid_token – token stracił już ważność lub został unieważniony przed wywołaniem metody revoke. W większości przypadków możesz rozważyć przyznanie grantu powiązanego z: accessToken.
  • invalid_request – tokena nie można unieważnić. Upewnij się, że accessToken to prawidłowe dane logowania Google OAuth 2.0.
error_description Ciąg tekstowy. Nie określono przyczyny sukcesu. Czytelny dla człowieka tekst ASCII zawiera dodatkowe informacje o właściwości error. W ten sposób deweloperzy mogą lepiej zrozumieć, jaki błąd wystąpił. Ciąg znaków error_description jest tylko w języku angielskim. W przypadku typowych błędów wymienionych w error odpowiada error_description:
  • invalid_token – token wygasł lub został unieważniony.
  • invalid_request – tokena nie można unieważnić.