Identity Platform-Mandanten programmatisch verwalten

In diesem Dokument wird erläutert, wie Sie die Identity Platform Admin SDK verwenden können, um Mandanten und ihre Nutzer programmatisch zu verwalten. Als Administrator können Sie unter anderem folgende Aktivitäten ausführen:

  • Nutzerverwaltung: Nutzer für einen bestimmten Mandanten erstellen, aktualisieren, löschen und auflisten.

  • Identitätsprüfung: Nutzer einer Anwendung identifizieren, um den Zugriff auf Ressourcen auf Ihrem eigenen Server einzuschränken.

  • Nutzer importieren: Nutzer aus einem externen Authentifizierungssystem oder einem anderen Identity Platform-Projekt bzw. -Mandanten migrieren.

  • Zugriffssteuerung mit benutzerdefinierten Anforderungen: Benutzerdefinierte Attribute für Nutzerkonten für einen bestimmten Mandanten definieren und verschiedene Zugriffssteuerungsstrategien wie die rollenbasierte Zugriffssteuerung implementieren.

  • Verwaltung der Nutzersitzung: Aktualisierungstokens eines Nutzers für einen bestimmten Mandanten widerrufen.

  • E-Mail-Aktionslinks: Benutzerdefinierte E-Mail-Links zum Zurücksetzen des Passworts, E-Mail-Links für die Anmeldung und E-Mail-Bestätigung für Nutzer eines bestimmten Mandanten generieren.

  • Mandantenverwaltung: Mandanten für ein bestimmtes Identity Platform-Projekt erstellen, auflisten, abrufen, aktualisieren und löschen.

  • OIDC- und SAML-Anbieter für Mandanten verwalten: OIDC- und SAML-Konfigurationen für einen bestimmten Mandanten programmatisch verwalten.

Hinweis

Unterstützte Features

In der folgenden Tabelle sind die von jedem SDK unterstützten Features in einer mandantenfähigen Umgebung aufgeführt:

Feature Node.js Java Python Go C#
Erstellen von benutzerdefinierten Tokens
ID-Tokens prüfen
Nutzer verwalten
Zugriff mit benutzerdefinierten Anforderungen steuern
Aktualisierungstokens widerrufen
Nutzer importieren
E-Mail-Aktionslinks generieren
Multi-Faktor-Authentifizierung
SAML-/OIDC-Anbieterkonfigurationen verwalten
Verwaltung von Sitzungscookies

In der folgenden Tabelle sehen Sie, welche Anmeldemethoden Sie mit dem Admin SDK und der Cloud Console in einer mandantenfähigen Umgebung konfigurieren können:

Feature Cloud Console Admin SDK
E-Mail
OIDC
SAML
Soziale Netzwerke
Telefon
Multi-Faktor-Authentifizierung
Anonym

Mandantenverwaltung

Mit dem Admin SDK können Sie Mandanten programmatisch über eine sichere Serverumgebung verwalten, anstatt die Cloud Console zu verwenden. Dazu gehört die Möglichkeit, Mandanten zu erstellen, aufzulisten, abzurufen, zu ändern oder zu löschen.

Jeder Mandant enthält seine eigenen Identitätsanbieter, Einstellungen und Gruppen von Nutzern. Vorgänge zur Verwaltung der Mandantenkonfiguration (CRUD) sind über die übergeordnete Projektinstanz unter Verwendung von admin.auth().tenantManager() verfügbar.

Eine Mandantenkonfiguration stellt Informationen über einen Mandanten bereit, wie den Anzeigenamen, die Mandanten-ID und die Konfiguration der E-Mail-Authentifizierung.

Alle anderen Einstellungen eines Mandanten, z. B. Domains auf der weißen Liste und authentifizierte Weiterleitungs-URIs, werden vom übergeordneten Projekt übernommen. Sie müssen mit der Cloud Console verwaltet werden.

Für Vorgänge wie die mandantenspezifische Nutzerverwaltung, das Konfigurieren von OIDC/SAML-Anbietern und das Generieren von E-Mail-Links benötigen Sie eine TenantAwareAuth-Instanz für den Zielmandanten (identifiziert durch ihre eindeutige tenantId).

const tenantManager = admin.auth().tenantManager();
const tenantAuth = tenantManager.authForTenant(tenantId);

Alle Aufrufe an die User Management APIs, OIDC/SAML Provider Management APIs und Email Link Generation APIs sind im Bereich dieses Mandanten (anhand der TenantAwareAuth-Instanz).

Vorhandenen Mandanten abrufen

Das Admin SDK stellt die Methode getTenant() bereit, die Informationen zu einem Mandanten anhand seiner tenantId (eine eindeutige ID für den Mandanten) abruft.

admin.auth().tenantManager().getTenant(tenantId)
  .then((tenant) => {
    console.log(tenant.toJSON());
  })
  .catch((error) => {
    // Handle error.
  });

Diese Methode gibt ein Tenant-Objekt zurück, das tenantId entspricht. Wenn die angegebene tenantId nicht zu einem vorhandenen Mandanten gehört, wird die zurückgegebene Prüfung mit dem Fehler auth/tenant-not-found abgelehnt.

Achten Sie darauf, eine Tenant-Instanz nicht mit einem TenantAwareAuth-Objekt zu verwechseln. authInstance.tenantManager().authForTenant() gibt eine TenantAwareAuth-Instanz zurück, die BaseAuth erweitert. Die Klasse Auth erweitert auch BaseAuth. BaseAuth bietet APIs zum Verwalten von Nutzern und zum Konfigurieren von OIDC-/SAML-Anbietern in verschiedenen Kontexten. Bei Auth befindet sich der Kontext auf der übergeordneten Projektebene. Bei TenantAwareAuth befindet sich der Kontext auf der Mandantenebene (der Mandant wird durch die Mandanten-ID bestimmt). Die SeitegetTenant() Methode mit grundlegenden Mandanteninformationen wie Mandanten-ID, Anzeigenamen und E-Mail-Anbietereinstellungen aufgelöst. Wenn Sie jedoch APIs für diesen Mandanten aufrufen möchten, müssen SieauthForTenant(tenantFromGetTenant.tenantId) verwenden.

Mandanten erstellen

Verwenden Sie die Methode createTenant(), um eine neue Mandantenkonfiguration zu erstellen:

admin.auth().tenantManager().createTenant({
  displayName: 'myTenant1',
  emailSignInConfig: {
    enabled: true,
    passwordRequired: false, // Email link sign-in enabled.
  },
  // TODO: Remove if you don't want to enable multi-factor authentication.
  multiFactorConfig: {
    state: 'ENABLED',
    factorIds: ['phone']
  },
  // TODO: Remove if you don't want to register test phone numbers for use
  // with multi-factor authentication.
  testPhoneNumbers: {
    '+16505551234': '145678',
    '+16505550000': '123456'
  },
})
.then((createdTenant) => {
  console.log(createdTenant.toJSON());
})
.catch((error) => {
  // Handle error.
});

Sie können eine beliebige Kombination dieser Attribute verwenden:

Attribut Typ Beschreibung
displayName

string
    
Der Anzeigename des Mandanten. Es müssen 4 bis 20 Zeichen sein, bestehend aus Buchstaben, Ziffern und Bindestrichen und mit einem Buchstaben beginnen.
emailSignInConfig

{
  enable: boolean,
  passwordRequired: boolean
}
    
Konfiguration des E-Mail-Anbieters für die Anmeldung. Dazu gehört, ob der E-Mail-Anbieter aktiviert ist und ob ein Passwort für die E-Mail-Anmeldung erforderlich ist. Wenn nicht erforderlich, kann sich eine E-Mail-Anmeldung mit einem Passwort oder einer E-Mail-Anmeldung anmelden.
multiFactorConfig

{
  state: 'DISABLED' | 'ENABLED',
  factorIds: string[]
}
    
Gibt an, ob für den Mandanten eine Multi-Faktor-Authentifizierung aktiviert ist und welche Faktortypen zulässig sind. Derzeit ist die einzige unterstützte Faktor-ID phone.
testPhoneNumbers

{
  string: string
}
  
Eine Zuordnung von Telefonnummern und zugehörigen Multi-Faktor-Authentifizierungscodes zu Testzwecken. Es sind maximal zehn Einträge zulässig. Wenn Sie alle Testnummern entfernen möchten, setzen Sie dieses Feld auf null.

Die Methode gibt ein Tenant-Objekt für den neu erstellten Mandanten zurück.

Mandanten aktualisieren

Vorhandene Daten eines Mandanten können Sie mit der Methode updateTenant() ändern. Sie müssen den tenantId und die Attribute angeben, die für diesen Mandanten aktualisiert werden sollen.

admin.auth().tenantManager().updateTenant(tenantId, {
  displayName: 'updatedName',
  emailSignInConfig: {
    enabled: false, // Disable email provider.
  },
  // Enable multi-factor authentication.
  multiFactorConfig: {
    state: 'ENABLED',
    factorIds: ['phone']
  },
  // Register phone numbers for testing.
  testPhoneNumbers: {
    '+16505551234': '145678',
    '+16505550000': '123456'
  },
})
.then((updatedTenant) => {
  console.log(updatedTenant.toJSON());
})
.catch((error) => {
  // Handle error.
});

updateTenant() akzeptiert dieselben Attribute wie createTenant(). Alle Attribute sind optional. Wenn ein Attribut nicht angegeben wird, wird der vorhandene Wert nicht geändert.

Die Methode gibt nach Abschluss ein aktualisiertes Tenant-Objekt zurück. Wenn die angegebene tenantId nicht zu einem vorhandenen Mandanten gehört, wird das zurückgegebene Versprechen mit dem Fehler auth/tenant-not-found abgelehnt.

Mandanten löschen

Sie können einen Mandanten anhand seiner tenantId löschen:

admin.auth().tenantManager().deleteTenant(tenantId)
  .then(() => {
    // Tenant deleted.
  })
  .catch((error) => {
    // Handle error.
  });

Die Methode gibt ein leeres Ergebnis zurück, wenn der Löschvorgang erfolgreich abgeschlossen ist. Wenn die angegebene tenantId nicht zu einem vorhandenen Mandanten gehört, wird die zurückgegebene Prüfung mit dem Fehler auth/tenant-not-found abgelehnt.

Mandanten auflisten

Verwenden Sie die Methode listTenants(), um vorhandene Mandanten aufzulisten:

function listAllTenants(nextPageToken) {
  return admin.auth().tenantManager().listTenants(100, nextPageToken)
    .then((result) => {
      result.tenants.forEach((tenant) => {
        console.log(tenant.toJSON());
      });
      if (result.pageToken) {
        return listAllTenants(result.pageToken);
      }
    });
}

listAllTenants();

Jeder Satz von Ergebnissen enthält eine Liste der Mandanten sowie ein Token für die nächste Seite, um den nächsten Mandanten-Satz aufzulisten. Wenn alle Mandanten bereits aufgelistet sind, wird kein pageToken zurückgegeben.

Wenn kein Feld maxResults angegeben ist, liegt der Standardwert bei 1.000 Mandanten pro Batch. Dies ist auch die maximale Anzahl der Mandanten, die gleichzeitig aufgelistet werden können. Jeder Wert, der größer als der Höchstwert ist, löst einen Argumentfehler aus. Wenn kein pageToken angegeben ist, listet die Methode Mandanten von Beginn an auf.

SAML- und OIDC-Anbieter programmatisch verwalten

Das Admin SDK bietet APIs für die programmatische Verwaltung der Konfiguration von SAML 2.0- (Security Assertion Markup Language) und OIDC-Anbietern (OpenID Connect) in einer sicheren Serverumgebung.

Mit dem Admin SDK können Sie diese Anbieter für einen bestimmten Mandanten verwalten. Dies ist mit dem Verwalten von OIDC- und SAML-Anbietern auf Projektebene vergleichbar.

Um Anbieter für einen Mandanten zu verwalten, erstellen Sie zuerst eine TenantAwareAuth-Instanz:

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Sie können dann übliche Vorgänge wie das Erstellen, Ändern oder Löschen von Anbietern für einen Mandanten ausführen.

Anbieter erstellen

Der folgende Code zeigt, wie ein SAML-Anbieter für einen Mandanten erstellt wird:

const newConfig = {
  displayName: 'SAML provider name',
  enabled: true,
  providerId: 'saml.myProvider',
  idpEntityId: 'IDP_ENTITY_ID',
  ssoURL: 'https://example.com/saml/sso/1234/',
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT1...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----'
  ],
  rpEntityId: 'RP_ENTITY_ID',
  // Using the default callback URL.
  callbackURL: 'https://project-id.firebaseapp.com/__/auth/handler'
};

tenantAuth.createProviderConfig(newConfig).then(() => {
  // Successful creation.
}).catch((error) => {
  // Handle error.
});

Anbieter ändern

Der folgende Code zeigt, wie ein Anbieter geändert wird:

const updatedConfig = {
  x509Certificates: [
    '-----BEGIN CERTIFICATE-----\nCERT2...\n-----END CERTIFICATE-----',
    '-----BEGIN CERTIFICATE-----\nCERT3...\n-----END CERTIFICATE-----',
  ],
};
tenantAuth.updateProviderConfig('saml.myProvider', updatedConfig).then(() => {
  // Successful update.
}).catch((error) => {
  // Handle error.
});

Anbieter abrufen

Der folgende Code zeigt, wie die Anbieterkonfiguration für einen bestimmten Mandanten anhand dessen Anbieter-ID abgerufen wird:

tenantAuth.getProviderConfig('saml.myProvider').then((config) => {
  // Get display name and whether it is enabled.
   console.log(config.displayName, config.enabled);
}).catch((error) => {
  // Handle error. Common error is that config is not found.
});

Anbieter auflisten

Der folgende Code zeigt, wie Anbieterkonfigurationen für einen bestimmten Mandanten aufgelistet werden:

// Returns 10 SAML provider configs starting from the specified nextPageToken offset.
tenantAuth.listProviderConfigs({type: 'saml', maxResults: 10, pageToken: 'nextPageToken'}).then((results) => {
  results.providerConfigs.forEach((config) => {
     console.log(config.providerId);
  });
  // To list the next 10:
  // return tenantAuth.listProviderConfigs(
  //     {type: 'saml', maxResults: 10, pageToken: results.pageToken});
}).catch((error) => {
   // Handle error.
});

Anbieter löschen

Der folgende Code zeigt, wie ein Anbieter gelöscht wird:

tenantAuth.deleteProviderConfig('saml.myProvider').then(() => {
  // Successful deletion.
}).catch((error) => {
  // Handle error.
});

OIDC-Anbieter werden ähnlich wie OIDC-Anbieter auf Projektebene verwaltet, außer sie können von der entsprechenden TenantAwareAuth-Instanz statt einer Auth auf Projektebene verwaltet werden.

Weitere Informationen finden Sie unter SAML- und OIDC-Anbieter programmatisch verwalten.

Mandantenspezifische Nutzer verwalten

Mit dem Admin SDK können Sie alle Nutzer für einen bestimmten Mandanten erstellen, abrufen, aktualisieren, löschen und auflisten.

Als Erstes benötigen Sie eine TenantAwareAuth-Instanz für den entsprechenden Mandanten:

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Nutzer abrufen

Sie können einen mandantenspezifischen Nutzer mit einer uid-ID abrufen:

tenantAuth.getUser(uid)
  .then((userRecord) => {
    // See the UserRecord reference documentation to learn more.
    console.log('Successfully fetched user data:', userRecord.toJSON());
    // Tenant ID will be reflected in userRecord.tenantId.
  })
  .catch((error) => {
    console.log('Error fetching user data:', error);
  });

Sie können einen Nutzer auch anhand seiner E-Mail-Adresse identifizieren:

tenantAuth.getUserByEmail(email)
  .then((userRecord) => {
    // See the UserRecord reference documentation to learn more.
    console.log('Successfully fetched user data:', userRecord.toJSON());
    // Tenant ID will be reflected in userRecord.tenantId.
  })
  .catch((error) => {
    console.log('Error fetching user data:', error);
  });

Nutzer erstellen

Mit der Methode createUser() können Sie neue Nutzer für einen bestimmten Mandanten erstellen. Beim Erstellen eines neuen Nutzers ist die Angabe einer uid optional. Wenn nicht angegeben, stellt Identity Platform eine eindeutige ID bereit.

tenantAuth.createUser({
  email: 'user@example.com',
  emailVerified: false,
  phoneNumber: '+11234567890',
  password: 'secretPassword',
  displayName: 'John Doe',
  photoURL: 'http://www.example.com/12345678/photo.png',
  disabled: false
})
.then((userRecord) => {
  // See the UserRecord reference documentation to learn more.
  console.log('Successfully created new user:', userRecord.uid);
  // Tenant ID will be reflected in userRecord.tenantId.
})
.catch((error) => {
  console.log('Error creating new user:', error);
});

Nutzer ändern

Sie können vorhandene Nutzer ändern, indem Sie ihre uid für die Methode updateUser() angeben:

tenantAuth.updateUser(uid, {
  email: 'modifiedUser@example.com',
  phoneNumber: '+11234567890',
  emailVerified: true,
  password: 'newPassword',
  displayName: 'Jane Doe',
  photoURL: 'http://www.example.com/12345678/photo.png',
  disabled: true
})
.then((userRecord) => {
  // See the UserRecord reference documentation to learn more.
  console.log('Successfully updated user', userRecord.toJSON());
})
.catch((error) => {
  console.log('Error updating user:', error);
});

Nutzer löschen

Das folgende Beispiel zeigt, wie Sie einen Nutzer anhand seiner uid löschen:

tenantAuth.deleteUser(uid)
  .then(() => {
    console.log('Successfully deleted user');
  })
  .catch((error) => {
    console.log('Error deleting user:', error);
  });

Nutzer auflisten

Zum Abrufen einer gesamten Liste von Nutzern für einen bestimmten Mandanten in Stapeln verwenden Sie die Methode listUsers(). Jeder Stapel enthält eine Liste von Nutzerdatensätzen sowie ein Token für die nächste Seite, falls weitere Nutzer verbleiben.

function listAllUsers(nextPageToken) {
  // List batch of users, 1000 at a time.
  tenantAuth.listUsers(1000, nextPageToken)
    .then((listUsersResult) => {
      listUsersResult.users.forEach((userRecord) => {
        console.log('user', userRecord.toJSON());
        // Tenant ID will be reflected in userRecord.tenantId.
      });
      if (listUsersResult.pageToken) {
        // List next batch of users.
        listAllUsers(listUsersResult.pageToken);
      }
    })
    .catch((error) => {
      console.log('Error listing users:', error);
    });
}
// Start listing users from the beginning, 1000 at a time.
listAllUsers();

Weitere Informationen finden Sie in der Admin SDK-Dokumentation unter Nutzer verwalten.

Nutzer importieren

Sie können das Admin SDK verwenden, um Nutzer gesammelt in einen bestimmten Mandanten mit erhöhten Berechtigungen zu importieren. Dies bietet zahlreiche Vorteile, z. B. die Migration von Nutzern aus einem anderen Identity Platform-Produkt, aus einem anderen Mandanten oder aus einem externen Authentifizierungssystem mit einem anderen Hash-Algorithmus. Sie können auch Nutzer mit föderierten Anbietern (wie SAML und OIDC) und benutzerdefinierten Anforderungen direkt gesammelt importieren.

Rufen Sie zuerst eine TenantAwareAuth-Instanz für den entsprechenden Mandanten ab:

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Mit einem bestimmten Hash-Algorithmus können Sie bis zu 1.000 Nutzer gleichzeitig importieren.

tenantAuth.importUsers([{
  uid: 'uid1',
  email: 'user1@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash-1'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('salt1')
},
{
  uid: 'uid2',
  email: 'user2@example.com',
  // Must be provided in a byte buffer.
  passwordHash: Buffer.from('password-hash-2'),
  // Must be provided in a byte buffer.
  passwordSalt: Buffer.from('salt2')

}], {
  hash: {
    algorithm: 'HMAC_SHA256',
    // Must be provided in a byte buffer.
    key: Buffer.from('secret')
  }
})
.then((results) => {
  results.errors.forEach(function(indexedError) {
   console.log('Error importing user ' + indexedError.index);
  });
})
.catch((error) => {
  console.log('Error importing users:', error);
});

Für alle importierten Nutzer wird tenantId auf tenantAuth.tenantId festgelegt.

Nutzer ohne Passwörter können auch in einen bestimmten Mandanten importiert werden. Diese Nutzer können mit föderierten Anbietern und benutzerdefinierten Anforderungen importiert werden.

tenantAuth.importUsers([{
  uid: 'some-uid',
  displayName: 'John Doe',
  email: 'johndoe@acme.com',
  photoURL: 'http://www.example.com/12345678/photo.png',
  emailVerified: true,
  phoneNumber: '+11234567890',
  // Set this user as admin.
  customClaims: {admin: true},
  // User with SAML provider.
  providerData: [{
    uid: 'saml-uid',
    email: 'johndoe@acme.com',
    displayName: 'John Doe',
    photoURL: 'http://www.example.com/12345678/photo.png',
    providerId: 'saml.acme'
  }]
}])
.then(function(results) {
  results.errors.forEach(function(indexedError) {
   console.log('Error importing user ' + indexedError.index);
  });
})
.catch(function(error) {
  console.log('Error importing users:', error);
});

Weitere Informationen finden Sie in der Admin SDK-Dokumentation unter Nutzer importieren.

Identitätsprüfung

Wenn eine Identity Platform-Clientanwendung mit einem benutzerdefinierten Back-End-Server kommuniziert, muss der aktuell angemeldete Nutzer auf diesem Server identifiziert werden. Dies kann sicher erfolgen, indem Sie das ID-Token des Nutzers senden, nachdem Sie sich über eine sichere Verbindung zu Ihrem Server angemeldet haben. Der Server kann dann die Integrität und Authentizität des ID-Tokens überprüfen.

Das Admin SDK hat eine integrierte Methode zum Prüfen und Decodieren von ID-Tokens für einen bestimmten Mandanten.

Nachdem der Nutzer erfolgreich über den Client bei einem bestimmten Mandanten angemeldet wurde, rufen Sie das ID-Token des Nutzers mithilfe des Client SDK ab:

auth.tenantId = 'TENANT-ID';
auth.signInWithEmailAndPassword('user@example.com', 'password')
  .then((userCredential) => {
    return userCredential.user.getIdToken();
  })
  .then((idToken) => {
    // Send the ID token to server for verification. ID token should be scoped to TENANT-ID.
  });

Erstellen Sie eine TenantAwareAuth-Instanz auf dem Server:

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Sie können dann das ID-Token für diesen bestimmten Mandanten prüfen:

// idToken comes from the client app
tenantAuth.verifyIdToken(idToken)
  .then((decodedToken) => {
    let uid = decodedToken.uid;
    // This should be set to TENANT-ID. Otherwise auth/mismatching-tenant-id error thrown.
    console.log(decodedToken.firebase.tenant);
    // ...
  }).catch((error) => {
    // Handle error
  });

Eine serverseitige Ressource kann von mehreren Mandanten mit unterschiedlichen Zugriffsebenen zugänglich sein. Da die Mandanten-ID in diesem Fall möglicherweise nicht vorab bekannt ist, kann das ID-Token zuerst auf Projektebene verifiziert werden.

admin.auth().verifyIdToken(idToken)
  .then((decodedToken) => {
    if (decodedToken.firebase.tenant === 'TENANT-ID1') {
      // Allow appropriate level of access for TENANT-ID1.
    } else if (decodedToken.firebase.tenant === 'TENANT-ID2') {
      // Allow appropriate level of access for TENANT-ID2.
    } else {
      // Block access for all other tenants.
      throw new Error('Access not allowed.');
    }
  }).catch((error) => {
    // Handle error
  });

Weitere Informationen finden Sie in der Dokumentation zum Thema ID-Tokens prüfen.

Nutzersitzungen verwalten

Identity Platform-Sitzungen sind langlebig. Bei jeder Anmeldung eines Nutzers werden die Anmeldedaten des Nutzers auf dem Identity Platform-Server überprüft und dann gegen ein kurzlebiges ID-Token und ein langlebiges Aktualisierungstoken ausgetauscht. ID-Tokens dauern eine Stunde. Aktualisierungstokens laufen nie ab, es sei denn, ein Nutzer ist deaktiviert, gelöscht oder wird von einer großen Kontoänderung wie eine E-Mail-Adresse oder ein Passwort-Update geändert.

In einigen Fällen muss das Aktualisierungstoken eines Nutzers aus Sicherheitsgründen widerrufen werden, z. B. wenn der Nutzer ein verlorenes oder gestohlenes Gerät meldet, eine allgemeine Sicherheitslücke in einer App oder ein erhebliches Datenleck in einem aktiven Token entdeckt. Das Admin SDK bietet eine API, mit der alle ausgegebenen Aktualisierungstokens für einen bestimmten Nutzer eines bestimmten Mandanten widerrufen werden.

Als Erstes benötigen Sie eine TenantAwareAuth-Instanz:

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Die Aktualisierungstokens können dann durch Angabe der uid dieses Nutzers widerrufen werden:

// Revoke all refresh tokens for a specified user in a specified tenant for whatever reason.
// Retrieve the timestamp of the revocation, in seconds since the epoch.
tenantAuth.revokeRefreshTokens(uid)
  .then(() => {
    return tenantAuth.getUser(uid);
  })
  .then((userRecord) => {
    return new Date(userRecord.tokensValidAfterTime).getTime() / 1000;
  })
  .then((timestamp) => {
    console.log('Tokens revoked at: ', timestamp);
  });

Nach dem Widerrufen der Aktualisierungstoken können für diesen Nutzer keine neuen ID-Token ausgestellt werden, bis eine neue Authentifizierung erfolgt. Vorhandene ID-Tokens bleiben jedoch bis zur natürlichen Ablaufzeit (eine Stunde) aktiv.

Sie können prüfen, ob ein nicht abgelaufenes ID-Token nicht widerrufen wurde, indem Sie den optionalen Parameter checkRevoked angeben. Damit wird geprüft, ob ein Token widerrufen wird, nachdem seine Integrität und Authentizität geprüft wurden.

// Verify the ID token for a specific tenant while checking if the token is revoked by passing
// checkRevoked true.
let checkRevoked = true;
tenantAuth.verifyIdToken(idToken, checkRevoked)
  .then(payload => {
    // Token is valid.
  })
  .catch(error => {
    if (error.code == 'auth/id-token-revoked') {
      // Token has been revoked. Inform the user to re-authenticate or
      // signOut() the user.
    } else {
      // Token is invalid.
    }
  });

Weitere Informationen finden Sie in der Admin SDK-Dokumentation unter Sitzungen verwalten.

Zugriff mit benutzerdefinierten Anforderungen steuern

Das Admin SDK unterstützt die Definition benutzerdefinierter Attribute in Nutzerkonten für einen bestimmten Mandanten. Mit diesen Attributen können Sie verschiedene Zugriffssteuerungsstrategien implementieren, z. B. rollenbasierte Zugriffssteuerung. Mithilfe der Attribute können Sie Nutzern unterschiedliche Zugriffsebenen zuweisen, die von den Sicherheitsregeln der Anwendung erzwungen werden.

Rufen Sie zuerst eine TenantAwareAuth-Instanz für den entsprechenden Mandanten ab:

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Benutzerdefinierte Anforderungen können sensible Daten enthalten, daher sollten sie nur mithilfe des Admin SDK über eine privilegierte Serverumgebung festgelegt werden.

// Set admin privilege on the user corresponding to uid for a specific tenant.
tenantAuth.setCustomUserClaims(uid, {admin: true}).then(() => {
  // The new custom claims will propagate to the user's ID token the
  // next time a new one is issued.
});

Neu festgelegte benutzerdefinierte Attribute werden für die Attribute der obersten Ebene der Tokennutzlast angezeigt, wenn sich der Nutzer das nächste Mal anmeldet oder seine ID-Tokens in einer bestehenden Sitzung aktualisiert. Im vorherigen Beispiel enthält das ID-Token eine zusätzliche Anforderung: {admin: true}.

Nach der Prüfung des ID-Tokens und der Decodierung der Nutzlast können diese zusätzlichen benutzerdefinierten Anforderungen geprüft werden, um die Zugriffssteuerung zu erzwingen.

// Verify the ID token first.
tenantAuth.verifyIdToken(idToken).then((claims) => {
  if (claims.admin === true) {
    // Allow access to requested admin resource.
  }
});

Benutzerdefinierte Anforderungen für einen vorhandenen Nutzer für einen bestimmten Mandanten sind auch als Attribut für den Nutzerdatensatz verfügbar.

// Lookup the user associated with the specified uid.
tenantAuth.getUser(uid).then((userRecord) => {
  // The claims can be accessed on the user record.
  console.log(userRecord.customClaims.admin);
});

Weitere Informationen finden Sie in der Admin SDK-Dokumentation unter Benutzerdefinierte Anforderungen.

Mit den Identity Platform-Client-SDKs können Sie Nutzern eines bestimmten Mandanten E-Mails mit Links zum Zurücksetzen von Passwörtern, zur Bestätigung der E-Mail-Adresse und zur Anmeldung per E-Mail senden. Diese E-Mails werden von Google gesendet und können nur beschränkt angepasst werden.

Mit dem Admin SDK können Sie diese Links programmatisch im Bereich eines bestimmten Mandanten generieren.

Rufen Sie zuerst eine TenantAwareAuth-Instanz für den entsprechenden Mandanten ab:

const tenantAuth = admin.auth().tenantManager().authForTenant('TENANT-ID');

Das folgende Beispiel zeigt, wie Sie einen Link generieren, um die E-Mail-Adresse eines Nutzers für einen angegebenen Mandanten zu bestätigen:

const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for
  // this URL must be whitelisted in the Cloud Console.
  url: 'https://www.example.com/checkout?cartId=1234',
  // This must be true for email link sign-in.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12'
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link'
};

// Admin SDK API to generate the email verification link.
const userEmail = 'user@example.com';
tenantAuth.generateEmailVerificationLink(userEmail, actionCodeSettings)
  .then((link) => {
    // Construct email verification template, embed the link and send
    // using custom SMTP server.
    return sendCustomVerificationEmail(userEmail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Es gibt ähnliche Mechanismen, mit denen sich Links für das Zurücksetzen von Passwörtern und E-Mail-basierte Anmeldelinks generieren lassen. Beim Generieren eines E-Mail-Aktions-Links in einem Mandantenkontext muss die Mandanten-ID aus dem Link geparst und in der Client-Instanz Auth festgelegt werden, bevor der Code angewendet werden kann.

const actionCodeUrl = firebase.auth.ActionCodeURL.parseLink(window.location.href);
// A one-time code, used to identify and verify a request.
const code = actionCodeUrl.code;
// The tenant ID being used to trigger the email action.
const tenantId = actionCodeUrl.tenantId;
auth.tenantId = tenantId;

// Apply the action code.
auth.applyActionCode(actionCode)
  .then(() => {
    // User's email is now verified.
  })
  .catch((error) => {
    // Handle error.
  });

Weitere Informationen finden Sie in der Admin SDK-Dokumentation unter E-Mail-Aktion-links.

Fehlermeldungen

In der folgenden Tabelle sind häufig auftretende Fehlermeldungen aufgeführt.

Fehlercode Beschreibung und Lösungsschritte
auth/billing-not-enabled Für dieses Feature muss die Abrechnung aktiviert sein.
auth/invalid-display-name Das Feld "displayName" muss ein gültiger String sein.
auth/invalid-name Der angegebene Ressourcenname ist ungültig.
auth/invalid-page-token Das Seitentoken muss eine gültige, nicht leere Zeichenfolge sein.
auth/invalid-project-id Ungültiges übergeordnetes Projekt. Entweder ermöglicht oder ermöglichte das übergeordnete Projekt die Mehrmandantenfähigkeit nicht.
auth/invalid-tenant-id Die Mandanten-ID muss ein gültiger, nicht leerer String sein.
auth/mismatching-tenant-id Die Mandanten-ID des Nutzers stimmt nicht mit der aktuellen Mandanten-ID TenantAwareAuth überein.
auth/missing-display-name Bei der Ressource, die gerade erstellt oder bearbeitet wird, fehlt ein gültiger Anzeigename.
auth/insufficient-permission Der Nutzer hat keine ausreichende Berechtigung, um auf die angefragte Ressource zuzugreifen oder den spezifischen Mandantenvorgang auszuführen.
auth/quota-exceeded Das Projektkontingent für den angegebenen Vorgang wurde überschritten.
auth/tenant-not-found Es ist kein Mandanten vorhanden, der mit der angegebenen ID übereinstimmt.
auth/unsupported-tenant-operation Dieser Vorgang wird in einem mandantenfähigen Kontext nicht unterstützt.
auth/invalid-testing-phone-number Es wurde eine ungültige Testtelefonnummer oder ein ungültiger Testcode angegeben.
auth/test-phone-number-limit-exceeded Die maximale Anzahl zulässiger Testtelefonnummern und Testcodepaaren wurde überschritten.