browser.identity

Beschreibung

Verwenden Sie die chrome.identity API, um OAuth2-Zugriffstokens abzurufen.

Berechtigungen

identity

Typen

AccountInfo

Attribute

  • id

    String

    Eine eindeutige Kennung für das Konto. Diese ID ändert sich während der Lebensdauer des Kontos nicht.

AccountStatus

Chrome 84 und höher browser.* seit Chrome 148

Enum

"SYNC"
Gibt an, dass die Synchronisierung für das primäre Konto aktiviert ist.

ANY
Gibt an, ob ein primäres Konto vorhanden ist.

GetAuthTokenResult

Chrome 105 und höher browser.* seit Chrome 148

Attribute

  • grantedScopes

    string[] optional

    Eine Liste der OAuth2-Bereiche, die der Erweiterung gewährt wurden.

  • Token

    String optional

    Das spezifische Token, das der Anfrage zugeordnet ist.

InvalidTokenDetails

Attribute

  • Token

    String

    Das spezifische Token, das aus dem Cache entfernt werden soll.

ProfileDetails

Chrome 84 und höher browser.* seit Chrome 148

Attribute

  • accountStatus

    AccountStatus optional

    Ein Status des primären Kontos, das in einem Profil angemeldet ist, dessen ProfileUserInfo zurückgegeben werden soll. Der Standardwert ist der Kontostatus SYNC.

ProfileUserInfo

Attribute

  • E-Mail

    String

    Eine E‑Mail-Adresse für das Nutzerkonto, das im aktuellen Profil angemeldet ist. Leer, wenn der Nutzer nicht angemeldet ist oder die Manifestberechtigung identity.email nicht angegeben ist.

  • id

    String

    Eine eindeutige Kennung für das Konto. Diese ID ändert sich während der Lebensdauer des Kontos nicht. Leer, wenn der Nutzer nicht angemeldet ist oder (in M41+) die Manifestberechtigung identity.email nicht angegeben ist.

TokenDetails

Attribute

  • Konto

    AccountInfo optional

    Die Konto-ID, deren Token zurückgegeben werden soll. Wenn nichts angegeben ist, wird ein Konto aus dem Chrome-Profil verwendet: das Synchronisierungskonto, falls vorhanden, oder das erste Google-Webkonto.

  • enableGranularPermissions

    Boolesch optional

    Chrome 87 und höher browser.* seit Chrome 148

    Mit dem Flag enableGranularPermissions können Erweiterungen vorzeitig den Zustimmungsbildschirm für detaillierte Berechtigungen aktivieren, auf dem angeforderte Berechtigungen einzeln gewährt oder abgelehnt werden.

  • interaktiv

    Boolesch optional

    Zum Abrufen eines Tokens muss sich der Nutzer möglicherweise in Chrome anmelden oder die angeforderten Bereiche der Anwendung genehmigen. Wenn das interaktive Flag true ist, fordert getAuthToken den Nutzer bei Bedarf auf. Wenn das Flag false ist oder weggelassen wird, gibt getAuthToken immer dann einen Fehler zurück, wenn eine Eingabeaufforderung erforderlich wäre.

  • Umfang

    string[] optional

    Eine Liste der anzufordernden OAuth2-Bereiche.

    Wenn das Feld scopes vorhanden ist, überschreibt es die Liste der in „manifest.json“ angegebenen Bereiche.

WebAuthFlowDetails

Attribute

  • abortOnLoadForNonInteractive

    Boolesch optional

    Chrome 113 und höher browser.* seit Chrome 148

    Gibt an, ob launchWebAuthFlow für nicht interaktive Anfragen nach dem Seitenaufbau beendet werden soll. Dieser Parameter hat keine Auswirkungen auf interaktive Abläufe.

    Wenn der Wert auf true (Standard) festgelegt ist, wird der Ablauf sofort nach dem Seitenaufbau beendet. Wenn false festgelegt ist, wird der Ablauf erst beendet, wenn die timeoutMsForNonInteractive abgelaufen ist. Das ist nützlich für Identitätsanbieter, die JavaScript verwenden, um Weiterleitungen nach dem Seitenaufbau durchzuführen.

  • interaktiv

    Boolesch optional

    Gibt an, ob der Authentifizierungsablauf im interaktiven Modus gestartet werden soll.

    Da einige Authentifizierungsabläufe möglicherweise sofort zu einer Ergebnis-URL weiterleiten, blendet launchWebAuthFlow die Webansicht aus, bis die erste Navigation entweder zur endgültigen URL weiterleitet oder das Laden einer Seite abgeschlossen ist, die angezeigt werden soll.

    Wenn das Flag interactive auf true gesetzt ist, wird das Fenster angezeigt, sobald der Seitenaufbau abgeschlossen ist. Wenn das Flag false ist oder weggelassen wird, gibt launchWebAuthFlow einen Fehler zurück, wenn die erste Navigation den Ablauf nicht abschließt.

    Bei Abläufen, die JavaScript für die Weiterleitung verwenden, kann abortOnLoadForNonInteractive auf false gesetzt werden. In Kombination mit der Einstellung timeoutMsForNonInteractive hat die Seite dann die Möglichkeit, Weiterleitungen auszuführen.

  • timeoutMsForNonInteractive

    number optional

    Chrome 113 und höher browser.* seit Chrome 148

    Die maximale Zeit in Millisekunden, die launchWebAuthFlow insgesamt im nicht interaktiven Modus ausgeführt werden darf. Hat nur dann eine Auswirkung, wenn interactive den Wert false hat.

  • URL

    String

    Die URL, die den Authentifizierungsablauf initiiert.

Methoden

clearAllCachedAuthTokens()

Chrome 87 und höher browser.* seit Chrome 148 
browser.identity.clearAllCachedAuthTokens(): Promise<void>

Setzt den Status der Identity API zurück:

  • Entfernt alle OAuth2-Zugriffstokens aus dem Token-Cache
  • Entfernt die Kontoeinstellungen des Nutzers
  • Entzieht dem Nutzer die Autorisierung für alle Autorisierungsabläufe.

Ausgabe

  • Promise<void>

    Chrome 106 und höher browser.* seit Chrome 148

    Gibt ein Promise zurück, das aufgelöst wird, wenn der Status gelöscht wurde.

getAccounts()

Entwicklerversion 
browser.identity.getAccounts(): Promise<AccountInfo[]>

Ruft eine Liste von AccountInfo-Objekten ab, die die im Profil vorhandenen Konten beschreiben.

getAccounts wird nur in der Entwicklerversion unterstützt.

Ausgabe

getAuthToken()

browser.identity.getAuthToken(
  details?: TokenDetails,
): Promise<GetAuthTokenResult>

Ruft ein OAuth2-Zugriffstoken mithilfe der Client-ID und der Bereiche ab, die im Abschnitt oauth2 von manifest.json angegeben sind.

Die Identity API speichert Zugriffstokens im Arbeitsspeicher. Daher ist es in Ordnung, getAuthToken nicht interaktiv aufzurufen, wenn ein Token erforderlich ist. Der Token-Cache verarbeitet den Ablauf automatisch.

Für eine gute Nutzererfahrung ist es wichtig, dass interaktive Tokenanfragen über die Benutzeroberfläche Ihrer App initiiert werden und erklärt wird, wofür die Autorisierung erforderlich ist. Andernfalls erhalten Ihre Nutzer Autorisierungsanfragen oder Chrome-Anmeldebildschirme, wenn sie nicht angemeldet sind, ohne dass sie den Kontext kennen. Verwenden Sie getAuthToken insbesondere nicht interaktiv, wenn Ihre App zum ersten Mal gestartet wird.

Hinweis: Wenn diese Funktion mit einem Callback aufgerufen wird, gibt sie kein Objekt zurück, sondern die beiden Properties als separate Argumente, die an den Callback übergeben werden.

Parameter

Ausgabe

  • Chrome 105 und höher browser.* seit Chrome 148

    Gibt ein Promise zurück, das mit einem OAuth2-Zugriffstoken aufgelöst wird, wie im Manifest angegeben, oder abgelehnt wird, wenn ein Fehler aufgetreten ist. Der Parameter grantedScopes wird seit Chrome 87 erfasst. Wenn verfügbar, enthält dieser Parameter die Liste der gewährten Bereiche, die dem zurückgegebenen Token entsprechen.

getProfileUserInfo()

browser.identity.getProfileUserInfo(
  details?: ProfileDetails,
): Promise<ProfileUserInfo>

Ruft die E‑Mail-Adresse und die verschleierte Gaia-ID des Nutzers ab, der in einem Profil angemeldet ist.

Erfordert die Manifestberechtigung identity.email. Andernfalls wird ein leeres Ergebnis zurückgegeben.

Diese API unterscheidet sich in zweierlei Hinsicht von „identity.getAccounts“. Die zurückgegebenen Informationen sind offline verfügbar und gelten nur für das primäre Konto des Profils.

Parameter

  • Details

    ProfileDetails optional

    Chrome 84 und höher browser.* seit Chrome 148

    Profiloptionen.

Ausgabe

  • Promise<ProfileUserInfo>

    Chrome 106 und höher browser.* seit Chrome 148

    Gibt ein Promise zurück, das mit der ProfileUserInfo des primären Chrome-Kontos aufgelöst wird, oder eine leere ProfileUserInfo, wenn das Konto mit der angegebenen details nicht vorhanden ist.

getRedirectURL()

browser.identity.getRedirectURL(
  path?: string,
): string

Generiert eine Weiterleitungs-URL, die in launchWebAuthFlow verwendet werden soll.

Die generierten URLs entsprechen dem Muster https://<app-id>.chromiumapp.org/*.

Parameter

  • Pfad

    String optional

    Der Pfad, der an das Ende der generierten URL angehängt wird.

Ausgabe

  • String

launchWebAuthFlow()

browser.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
): Promise<string | undefined>

Startet einen Autorisierungsablauf unter der angegebenen URL.

Diese Methode ermöglicht Authentifizierungsabläufe mit Identitätsanbietern, die nicht von Google stammen. Dazu wird eine Webansicht gestartet und zur ersten URL im Authentifizierungsablauf des Anbieters navigiert. Wenn der Anbieter zu einer URL weiterleitet, die dem Muster https://<app-id>.chromiumapp.org/* entspricht, wird das Fenster geschlossen und die endgültige Weiterleitungs-URL wird an die Funktion callback übergeben.

Für eine gute Nutzererfahrung ist es wichtig, dass interaktive Autorisierungsabläufe über die Benutzeroberfläche Ihrer App initiiert werden und erklärt wird, wofür die Autorisierung erforderlich ist. Andernfalls erhalten Ihre Nutzer Autorisierungsanfragen ohne Kontext. Starten Sie insbesondere keinen interaktiven Authentifizierungsablauf, wenn Ihre App zum ersten Mal gestartet wird.

Parameter

Ausgabe

  • Promise<string | undefined>

    Chrome 106 und höher browser.* seit Chrome 148

    Gibt ein Promise zurück, das mit der URL aufgelöst wird, die zurück zu Ihrer Anwendung weitergeleitet wird.

removeCachedAuthToken()

browser.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
): Promise<void>

Entfernt ein OAuth2-Zugriffstoken aus dem Token-Cache der Identity API.

Wenn ein Zugriffstoken ungültig ist, sollte es an „removeCachedAuthToken“ übergeben werden, um es aus dem Cache zu entfernen. Die App kann dann mit getAuthToken ein neues Token abrufen.

Parameter

Ausgabe

  • Promise<void>

    Chrome 106 und höher browser.* seit Chrome 148

    Gibt ein Promise zurück, das aufgelöst wird, wenn das Token aus dem Cache entfernt wurde.

Ereignisse

onSignInChanged

browser.identity.onSignInChanged.addListener(
  callback: function,
)

Wird ausgelöst, wenn sich der Anmeldestatus für ein Konto im Profil des Nutzers ändert.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (account: AccountInfo, signedIn: boolean) => void