Managing Identity Platform tenants programmatically

This document explains how to use the Identity Platform Admin SDK to manage tenants and their users programmatically. Some activities you can perform as an administrator include:

• User management: Create, update, delete, and list users for a specific tenant.

• Identity verification: Identify users of an app to restrict access to resources on your own server.

• Import users: Migrate users from an external authentication system or another Identity Platform project or tenant.

• Access control with custom claims: Define custom attributes on user accounts for a specific tenant and implement various access control strategies, such as role-based access control.

• User session management: Revoke a user's refresh tokens for a specific tenant.

• Email action links: Generate customized email links for password reset, email link sign-in, and email verification for users of a specific tenant.

• Tenant management: Create, list, get, update, delete tenants for a specific Identity Platform project.

• Manage OIDC and SAML providers on tenants: Programmatically manage OIDC and SAML configurations on a specified tenant.

Before you begin

• Install the Admin SDK for Node.js, Java, Python, Go, or C#.

• Enable multi-tenancy for your Google Cloud project.

Supported features

The following table lists the features supported by each SDK in a multi-tenant environment:

The following table shows what sign-in methods you can configure using the Admin SDK and the Google Cloud console in a tenant-specific context:

Tenant management

Using the Admin SDK, you can manage tenants programmatically from a secure server environment instead of using the Google Cloud console. This includes the ability to create, list, get, modify, or delete tenants.

Each tenant contains its own identity providers, settings, and sets of users. Tenant configuration management operations (CRUD) are available from the parent project instance using admin.auth().tenantManager().

A tenant configuration provides information about a tenant, such as its display name, tenant identifier, and email authentication configuration.

All other settings (such as whitelisted domains and authenticated redirect URIs) of a tenant are inherited from the parent project. These must be managed using the Google Cloud console.

For operations such as tenant-specific user management, configuring OIDC/SAML providers, and email link generation, you'll need a TenantAwareAuth instance for the target tenant (identified by its unique tenantId).

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

from firebase_admin import tenant_mgt

tenant_client = tenant_mgt.auth_for_tenant(tenant_id)
index.py

FirebaseAuth auth = FirebaseAuth.getInstance();
TenantManager tenantManager = auth.getTenantManager();
TenantAwareFirebaseAuth tenantAuth = tenantManager.getAuthForTenant(tenantId);
FirebaseAuthSnippets.java

All calls to the user management APIs, OIDC/SAML provider management APIs, and email link generation APIs will be inside the scope of this tenant (using its TenantAwareAuth instance).

Getting an existing tenant

The Admin SDK provides the getTenant() method, which fetches information about a tenant based on its tenantId (a unique identifier for the tenant).

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

tenant = tenant_mgt.get_tenant(tenant_id)

print('Retrieved tenant:', tenant.tenant_id)
index.py

Tenant tenant = FirebaseAuth.getInstance().getTenantManager().getTenant(tenantId);
System.out.println("Retrieved tenant: " + tenant.getTenantId());
FirebaseAuthSnippets.java

This method returns a Tenant object corresponding to the tenantId. If the provided tenantId does not belong to an existing tenant, the returned promise rejects with an auth/tenant-not-found error.

Be careful not to confuse a Tenant instance with a TenantAwareAuth object. authInstance.tenantManager().authForTenant() returns a TenantAwareAuth instance that extends BaseAuth. The Auth class also extends BaseAuth. BaseAuth provides APIs to manage users, configure OIDC/SAML providers in different contexts. For Auth, the context is at the parent project level. For TenantAwareAuth, the context is at the tenant level (the tenant is determined by the tenant ID). The getTenant() method will resolve with basic tenant information (like tenant ID, display name, and email provider settings), but to call APIs on that tenant, you need to use authForTenant(tenantFromGetTenant.tenantId).

Creating a tenant

Use the createTenant() method to to create a new tenant configuration:

admin.auth().tenantManager().createTenant({
  displayName: 'myTenant1',
  emailSignInConfig: {