In diesem Artikel erfahren Sie, wie Sie eine eigene Authentifizierungsseite mit externen Identitäten und IAP erstellen. Wenn Sie diese Seite selbst erstellen, haben Sie die volle Kontrolle über den Authentifizierungsablauf und die Nutzerfreundlichkeit.
Wenn Sie Ihre Benutzeroberfläche nicht vollständig anpassen müssen, können Sie IAP eine Anmeldeseite für Sie hosten lassen oder FirebaseUI verwenden, um die Nutzung zu vereinfachen.
Übersicht
So erstellen Sie eine eigene Authentifizierungsseite:
- Aktivieren Sie externe Identitäten. Wählen Sie bei der Einrichtung die Option Eigene Benutzeroberfläche bereitstellen aus.
- Installieren Sie die
gcip-iap
-Bibliothek. - Konfigurieren Sie die Benutzeroberfläche, indem Sie die
AuthenticationHandler
-Benutzeroberfläche implementieren. Ihre Authentifizierungsseite muss die folgenden Szenarien verarbeiten:- Mandantenauswahl
- Nutzerautorisierung
- Nutzeranmeldung
- Fehlerbehandlung
- Optional: Passen Sie die Authentifizierungsseite mit zusätzlichen Funktionen an, z. B. Fortschrittsbalken, Abmeldeseiten und Nutzerverarbeitung.
- Testen Sie die Benutzeroberfläche.
gcip-iap-Bibliothek installieren
Führen Sie den folgenden Befehl aus, um die gcip-iap
-Bibliothek zu installieren:
npm install gcip-iap --save
Das NPM-Modul gcip-iap
abstrahiert die Kommunikation zwischen Ihrer Anwendung, IAP und Identity Platform. So können Sie den gesamten Authentifizierungsablauf anpassen, ohne die zugrunde liegenden Austauschvorgänge zwischen UI und IAP verwalten zu müssen.
Verwenden Sie die richtigen Importe für Ihre SDK-Version:
// Import Firebase/GCIP dependencies. These are installed on npm install.
import * as firebase from 'firebase/app';
import 'firebase/auth';
// Import GCIP/IAP module.
import * as ciap from 'gcip-iap';
Ab Version 1.0.0 ist für gcip-iap
die Peer-Abhängigkeit firebase
v9 oder höher erforderlich.
Wenn Sie zu gcip-iap
v1.0.0 oder höher migrieren, führen Sie die folgenden Schritte aus:
- Aktualisieren Sie die
firebase
-Version in Ihrerpackage.json
-Datei auf Version 9.6.0 oder höher. - Aktualisieren Sie die Importanweisungen für
firebase
so:
// Import Firebase modules.
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
// Import the gcip-iap module.
import * as ciap from 'gcip-iap';
Es sind keine weiteren Codeänderungen erforderlich.
Ab Version 2.0.0 muss Ihre benutzerdefinierte UI-Anwendung für gcip-iap
im modularen SDK-Format neu geschrieben werden. Wenn Sie zu gcip-iap
v2.0.0 oder höher migrieren, führen Sie die folgenden Schritte aus:
- Aktualisieren Sie die
firebase
-Version in der Dateipackage.json
auf Version 9.8.3 oder höher. - Aktualisieren Sie die Importanweisungen für
firebase
so:
// Import Firebase modules.
import { initializeApp } from 'firebase/app';
import { getAuth, GoogleAuthProvider } 'firebase/auth';
// Import the gcip-iap module.
import * as ciap from 'gcip-iap';
Benutzeroberfläche konfigurieren
Erstellen Sie zum Konfigurieren der Benutzeroberfläche eine benutzerdefinierte Klasse, die die AuthenticationHandler
-Schnittstelle implementiert:
interface AuthenticationHandler {
languageCode?: string | null;
getAuth(apiKey: string, tenantId: string | null): FirebaseAuth;
startSignIn(auth: FirebaseAuth, match?: SelectedTenantInfo): Promise<UserCredential>;
selectTenant?(projectConfig: ProjectConfig, tenantIds: string[]): Promise<SelectedTenantInfo>;
completeSignOut(): Promise<void>;
processUser?(user: User): Promise<User>;
showProgressBar?(): void;
hideProgressBar?(): void;
handleError?(error: Error | CIAPError): void;
}
Während der Authentifizierung ruft die Bibliothek automatisch die Methoden von AuthenticationHandler
auf.
Mandanten auswählen
Implementieren Sie selectTenant()
, um einen Mandanten auszuwählen. Durch Implementieren dieser Methode kann ein Mandant wahlweise programmatisch ausgewählt oder eine Benutzeroberfläche angezeigt werden, mit der der Nutzer selbst einen Mandanten auswählen kann.
In beiden Fällen verwendet die Bibliothek das zurückgegebene SelectedTenantInfo
-Objekt, um den Authentifizierungsvorgang abzuschließen. Es enthält die ID des ausgewählten Mandanten, alle Anbieter-IDs und die E-Mail-Adresse, die der Nutzer eingegeben hat.
Wenn Ihr Projekt mehrere Mandanten hat, müssen Sie einen auswählen, bevor Sie einen Nutzer authentifizieren können. Wenn Sie nur einen einzelnen Mandanten oder die Authentifizierung auf Projektebene verwenden, müssen Sie selectTenant()
nicht implementieren.
IAP unterstützt die gleichen Anbieter wie Identity Platform:
- E-Mail-Adresse und Passwort
- OAuth (Google, Facebook, Twitter, GitHub, Microsoft usw.)
- SAML
- OIDC
- Telefonnummer
- Benutzerdefiniert
- Anonym
Die Authentifizierung durch Telefonnummer sowie die benutzerdefinierte und die anonyme Authentifizierung werden für die Mehrinstanzenfähigkeit nicht unterstützt.
Mandanten programmatisch auswählen
Wenn Sie einen Mandanten programmatisch auswählen möchten, nutzen Sie den aktuellen Kontext. Die Klasse Authentication
enthält getOriginalURL()
, die die URL zurückgibt, auf die der Nutzer vor der Authentifizierung zugegriffen hat.
So können Sie eine Übereinstimmung über eine Liste der zugehörigen Mandanten ermitteln:
// Select provider programmatically.
selectTenant(projectConfig, tenantIds) {
return new Promise((resolve, reject) => {
// Show UI to select the tenant.
auth.getOriginalURL()
.then((originalUrl) => {
resolve({
tenantId: getMatchingTenantBasedOnVisitedUrl(originalUrl),
// If associated provider IDs can also be determined,
// populate this list.
providerIds: [],
});
})
.catch(reject);
});
}
Nutzern erlauben, Mieter auszuwählen
Wenn Sie dem Nutzer die Auswahl eines Mandanten ermöglichen möchten, können Sie eine Liste der Mandanten anzeigen lassen, aus der er einen auswählen muss, oder Sie fordern ihn auf, seine E-Mail-Adresse einzugeben, um dann eine Übereinstimmung anhand der Domain zu ermitteln:
// Select provider by showing UI.
selectTenant(projectConfig, tenantIds) {
return new Promise((resolve, reject) => {
// Show UI to select the tenant.
renderSelectTenant(
tenantIds,
// On tenant selection.
(selectedTenantId) => {
resolve({
tenantId: selectedTenantId,
// If associated provider IDs can also be determined,
// populate this list.
providerIds: [],
// If email is available, populate this field too.
email: undefined,
});
});
});
}
Nutzer authentifizieren
Nachdem Sie einen Anbieter haben, implementieren Sie getAuth()
, um eine Auth-Instanz zurückzugeben, die dem bereitgestellten API-Schlüssel und der Mandanten-ID entspricht. Wenn keine Mandanten-ID verfügbar ist, müssen Sie stattdessen Identitätsanbieter auf Projektebene verwenden.
Mit getAuth()
lässt sich feststellen, wo der Nutzer, der der angegebenen Konfiguration entspricht, gespeichert ist. Außerdem ist es damit möglich, das Identity Platform-ID-Token eines zuvor authentifizierten Nutzers im Hintergrund zu aktualisieren, ohne dass der Nutzer seine Anmeldedaten noch einmal eingeben muss.
Wenn Sie mehrere IAP-Ressourcen mit unterschiedlichen Mandanten nutzen, empfehlen wir die Verwendung einer eindeutigen Authentifizierungs-Instanz für jede Ressource. Dadurch können Sie mehrere Ressourcen mit unterschiedlichen Konfigurationen die gleiche Authentifizierungsseite nutzen. Außerdem bietet es mehreren Nutzern die Möglichkeit, sich gleichzeitig anzumelden, ohne dass der vorherige Nutzer abgemeldet werden muss.
Im Folgenden finden Sie ein Beispiel für die Implementierung von getAuth()
:
getAuth(apiKey, tenantId) {
let auth = null;
// Make sure the expected API key is being used.
if (apiKey !== expectedApiKey) {
throw new Error('Invalid project!');
}
try {
auth = firebase.app(tenantId || undefined).auth();
// Tenant ID should be already set on initialization below.
} catch (e) {
// Use different App names for every tenant so that
// multiple users can be signed in at the same time (one per tenant).
const app = firebase.initializeApp(this.config, tenantId || '[DEFAULT]');
auth = app.auth();
// Set the tenant ID on the Auth instance.
auth.tenantId = tenantId || null;
}
return auth;
}
import {initializeApp, getApp} from 'firebase/app';
import {getAuth} from 'firebase/auth';
getAuth(apiKey, tenantId) {
let auth = null;
// Make sure the expected API key is being used.
if (apiKey !== expectedApiKey) {
throw new Error('Invalid project!');
}
try {
auth = getAuth(getApp(tenantId || undefined));
// Tenant ID should be already set on initialization below.
} catch (e) {
// Use different App names for every tenant so that
// multiple users can be signed in at the same time (one per tenant).
const app = initializeApp(this.config, tenantId || '[DEFAULT]');
auth = getAuth(app);
// Set the tenant ID on the Auth instance.
auth.tenantId = tenantId || null;
}
return auth;
}
Nutzer anmelden
Implementiere startSignIn()
, um die Anmeldung zu verarbeiten, zeige eine Benutzeroberfläche für die Authentifizierung an und gib nach Abschluss der Authentifizierung einen UserCredential
-Wert für den angemeldeten Nutzer zurück.
In einer Umgebung mit mehreren Mandanten können Sie die verfügbaren Authentifizierungsmethoden aus SelectedTenantInfo
ermitteln, sofern diese Variable angegeben wurde. Sie enthält die Informationen, die von selectTenant()
zurückgegeben werden.
Das folgende Beispiel zeigt eine startSignIn()
-Implementierung für einen vorhandenen Nutzer mit einer E-Mail-Adresse und einem Passwort:
startSignIn(auth, selectedTenantInfo) {
return new Promise((resolve, reject) => {
// Show the UI to sign-in or sign-up a user.
$('#sign-in-form').on('submit', (e) => {
const email = $('#email').val();
const password = $('#password').val();
// Example: Ask the user for an email and password.
// Note: The method of sign in may have already been determined from the
// selectedTenantInfo object.
auth.signInWithEmailAndPassword(email, password)
.then((userCredential) => {
resolve(userCredential);
})
.catch((error) => {
// Show the error message.
});
});
});
}
import {signInWithEmailAndPassword} from 'firebase/auth';
startSignIn(auth, selectedTenantInfo) {
return new Promise((resolve, reject) => {
// Show the UI to sign-in or sign-up a user.
$('#sign-in-form').on('submit', (e) => {
const email = $('#email').val();
const password = $('#password').val();
// Example: Ask the user for an email and password.
// Note: The method of sign in may have already been determined from the
// selectedTenantInfo object.
signInWithEmailAndPassword(auth, email, password)
.then((userCredential) => {
resolve(userCredential);
})
.catch((error) => {
// Show the error message.
});
});
});
}
Sie haben auch die Möglichkeit, Nutzer mit einem Föderationsanbieter wie SAML oder OIDC über ein Pop-up-Fenster oder eine Weiterleitung anzumelden:
startSignIn(auth, selectedTenantInfo) {
// Show the UI to sign-in or sign-up a user.
return new Promise((resolve, reject) => {
// Provide the user multiple buttons to sign-in.
// For example sign-in with popup using a SAML provider.
// Note: The method of sign in may have already been determined from the
// selectedTenantInfo object.
const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
auth.signInWithPopup(provider)
.then((userCredential) => {
resolve(userCredential);
})
.catch((error) => {
// Show the error message.
});
// Using redirect flow. When the page redirects back and sign-in completes,
// ciap will detect the result and complete sign-in without any additional
// action.
auth.signInWithRedirect(provider);
});
}
import {signInWithPopup, SAMLAuthProvider} from 'firebase/auth';
startSignIn(auth, selectedTenantInfo) {
// Show the UI to sign-in or sign-up a user.
return new Promise((resolve, reject) => {
// Provide the user multiple buttons to sign-in.
// For example sign-in with popup using a SAML provider.
// Note: The method of sign in might have already been determined from the
// selectedTenantInfo object.
const provider = new SAMLAuthProvider('saml.myProvider');
signInWithPopup(auth, provider)
.then((userCredential) => {
resolve(userCredential);
})
.catch((error) => {
// Show the error message.
});
// Using redirect flow. When the page redirects back and sign-in completes,
// ciap will detect the result and complete sign-in without any additional
// action.
signInWithRedirect(auth, provider);
});
}
Einige OAuth-Anbieter unterstützen die Übergabe eines Hinweises für die Anmeldung:
startSignIn(auth, selectedTenantInfo) {
// Show the UI to sign-in or sign-up a user.
return new Promise((resolve, reject) => {
// Use selectedTenantInfo to determine the provider and pass the login hint
// if that provider supports it and the user specified an email address.
if (selectedTenantInfo &&
selectedTenantInfo.providerIds &&
selectedTenantInfo.providerIds.indexOf('microsoft.com') !== -1) {
const provider = new firebase.auth.OAuthProvider('microsoft.com');
provider.setCustomParameters({
login_hint: selectedTenantInfo.email || undefined,
});
} else {
// Figure out the provider used...
}
auth.signInWithPopup(provider)
.then((userCredential) => {
resolve(userCredential);
})
.catch((error) => {
// Show the error message.
});
});
}
import {signInWithPopup, OAuthProvider} from 'firebase/auth';
startSignIn(auth, selectedTenantInfo) {
// Show the UI to sign in or sign up a user.
return new Promise((resolve, reject) => {
// Use selectedTenantInfo to determine the provider and pass the login hint
// if that provider supports it and the user specified an email address.
if (selectedTenantInfo &&
selectedTenantInfo.providerIds &&
selectedTenantInfo.providerIds.indexOf('microsoft.com') !== -1) {
const provider = new OAuthProvider('microsoft.com');
provider.setCustomParameters({
login_hint: selectedTenantInfo.email || undefined,
});
} else {
// Figure out the provider used...
}
signInWithPopup(auth, provider)
.then((userCredential) => {
resolve(userCredential);
})
.catch((error) => {
// Show the error message.
});
});
}
Weitere Informationen finden Sie unter Authentifizierung mit Mehrfachunterstützung.
Fehlerbehebung
Wenn Sie Nutzern Fehlermeldungen anzeigen oder versuchen möchten, Fehler wie Netzwerkzeitüberschreitungen automatisch zu beheben, implementieren Sie handleError()
.
Im folgenden Beispiel wird handleError()
implementiert:
handleError(error) {
showAlert({
code: error.code,
message: error.message,
// Whether to show the retry button. This is only available if the error is
// recoverable via retrial.
retry: !!error.retry,
});
// When user clicks retry, call error.retry();
$('.alert-link').on('click', (e) => {
error.retry();
e.preventDefault();
return false;
});
}
In der folgenden Tabelle sind die spezifischen IAP-Fehlercodes aufgeführt, die zurückgegeben werden können. Auch über Identity Platform können Fehler ausgegeben werden. Informationen dazu finden Sie in der Dokumentation zu firebase.auth.Auth
.
Fehlercode | Beschreibung |
---|---|
invalid-argument |
Der Client hat ein ungültiges Argument angegeben. |
failed-precondition |
Die Anfrage kann im aktuellen Systemzustand nicht ausgeführt werden. |
out-of-range |
Der Client hat einen ungültigen Bereich angegeben. |
unauthenticated |
Die Anfrage wurde aufgrund eines fehlenden, ungültigen oder abgelaufenen OAuth-Tokens nicht authentifiziert. |
permission-denied |
Der Client hat keine ausreichende Berechtigungen oder die UI wird in einer nicht autorisierten Domain gehostet. |
not-found |
Die angegebene Ressource wurde nicht gefunden. |
aborted |
Es ist ein Konflikt aufgrund von gleichzeitig ausgeführten Aktionen aufgetreten, beispielsweise ein Read-Modify-Write-Konflikt. |
already-exists |
Die Ressource, die ein Client erstellen möchte, ist bereits vorhanden. |
resource-exhausted |
Es wurde entweder das Ressourcenkontingent überschritten oder das Ratenlimit erreicht. |
cancelled |
Die Anfrage wurde vom Client abgebrochen. |
data-loss |
Es ist ein dauerhafter Datenverlust oder Datenkorruption aufgetreten. |
unknown |
Unbekannter Serverfehler. |
internal |
Interner Serverfehler. |
not-implemented |
Die API-Methode wurde vom Server nicht implementiert. |
unavailable |
Dienst ist nicht verfügbar. |
restart-process |
Sie müssen die URL, über die Sie auf diese Seite weitergeleitet wurden, noch einmal aufrufen und den Authentifizierungsprozess neu starten. |
deadline-exceeded |
Die Frist der Anfrage wurde überschritten. |
authentication-uri-fail |
Authentifizierungs-URI konnte nicht generiert werden. |
gcip-token-invalid |
Ein ungültiges GCIP-ID-Token wurde angegeben. |
gcip-redirect-invalid |
Ungültige Weiterleitungs-URL. |
get-project-mapping-fail |
Fehler beim Abrufen der Projekt-ID. |
gcip-id-token-encryption-error |
Fehler bei der GCIP-ID-Token-Verschlüsselung. |
gcip-id-token-decryption-error |
Fehler bei der Entschlüsselung des GCIP-ID-Tokens. |
gcip-id-token-unescape-error |
Fehler beim Aufheben der Escapezeichen für die websichere Base64-Codierung. |
resource-missing-gcip-sign-in-url |
GCIP-Authentifizierungs-URL für die angegebene IAP-Ressource ist nicht vorhanden. |
Benutzeroberfläche anpassen
Sie können die Authentifizierungsseite mit optionalen Funktionen wie Fortschrittsbalken und Abmeldeseiten anpassen.
Fortschrittsanzeige darstellen
Wenn Nutzern ein benutzerdefinierter Fortschrittsverlauf angezeigt werden soll, wenn das gcip-iap
-Modul lang andauernde Netzwerkaufgaben ausführt, implementieren Sie showProgressBar()
und hideProgressBar()
.
Nutzer abmelden
In einigen Fällen kann es sinnvoll sein, Nutzern das Abmelden von allen aktuellen Sitzungen zu erlauben, die die gleiche Authentifizierungs-URL nutzen.
Möglicherweise ist dann aber keine URL vorhanden, zu der der Nutzer nach der Abmeldung zurückgeleitet werden kann.
Dies tritt häufig dann auf, wenn sich ein Nutzer von allen mit einer Anmeldeseite verknüpften Mandanten abmeldet. Implementieren Sie in diesem Fall completeSignOut()
. Eine Nachricht zeigt dann an, dass der Nutzer erfolgreich abgemeldet wurde. Wenn Sie diese Methode nicht implementieren, wird beim Abmelden eines Nutzers eine leere Seite angezeigt.
Nutzer verarbeiten
Wenn Sie einen angemeldeten Nutzer ändern möchten, bevor er zur IAP-Ressource weitergeleitet wird, implementieren Sie processUser()
.
Mit dieser Methode können Sie Folgendes tun:
- Mit weiteren Anbietern verknüpfen
- Nutzerprofil aktualisieren
- Nutzer nach der Registrierung zur Eingabe zusätzlicher Daten auffordern
- OAuth-Zugriffstoken verarbeiten, die von
getRedirectResult()
nach dem Aufruf vonsignInWithRedirect()
zurückgegeben werden
Im Folgenden finden Sie ein Beispiel für die Implementierung von processUser()
:
processUser(user) {
return lastAuthUsed.getRedirectResult().then(function(result) {
// Save additional data, or ask the user for additional profile information
// to store in database, etc.
if (result) {
// Save result.additionalUserInfo.
// Save result.credential.accessToken for OAuth provider, etc.
}
// Return the user.
return user;
});
}
import {getRedirectResult} from 'firebase/auth';
processUser(user) {
return getRedirectResult(lastAuthUsed).then(function(result) {
// Save additional data, or ask the user for additional profile information
// to store in database, etc.
if (result) {
// Save result.additionalUserInfo.
// Save result.credential.accessToken for OAuth provider, etc.
}
// Return the user.
return user;
});
}
Wenn Änderungen an einem Nutzer in den ID-Token-Anforderungen berücksichtigt werden sollen, die von IAP an Ihre Anwendung weitergegeben werden, müssen Sie die Aktualisierung des Tokens erzwingen:
processUser(user) {
return user.updateProfile({
photoURL: 'https://example.com/profile/1234/photo.png',
}).then(function() {
// To reflect updated photoURL in the ID token, force token
// refresh.
return user.getIdToken(true);
}).then(function() {
return user;
});
}
import {updateProfile} from 'firebase/auth';
processUser(user) {
return updateProfile(user, {
photoURL: 'https://example.com/profile/1234/photo.png',
}).then(function() {
// To reflect updated photoURL in the ID token, force token
// refresh.
return user.getIdToken(true);
}).then(function() {
return user;
});
}
Benutzeroberfläche testen
Wenn Sie eine Klasse erstellt haben, die AuthenticationHandler
implementiert, können Sie damit eine neue Authentication
-Instanz erstellen und starten:
// Implement interface AuthenticationHandler.
// const authHandlerImplementation = ....
const ciapInstance = new ciap.Authentication(authHandlerImplementation);
ciapInstance.start();
Stellen Sie Ihre Anwendung bereit und rufen Sie die Authentifizierungsseite auf. Anschließend sollte Ihre benutzerdefinierte Anmeldungs-UI angezeigt werden.
Nächste Schritte
- Programmatisch auf Ressourcen von Drittanbietern zugreifen
- Sitzungen verwalten
- Weitere Informationen zur Funktionsweise von externen Identitäten mit IAP