使用自定义声明和安全规则控制访问权限

Firebase Admin SDK 支持为用户账号指定自定义特性。您可以借此功能在 Firebase 应用中实施各种访问控制策略，包括基于角色的访问权限控制。这些自定义特性可以授予用户不同的访问权限级别（角色），并通过应用的安全规则强制施行。

您可以针对以下常见情况定义用户角色：

• 向用户授予管理权限，以允许其访问数据和资源。
• 指定用户所属的不同群组。
• 提供多级别访问权限：
  • 区分付费/免费订阅者。
  • 区分管理员与常规用户。
  • 教师/学生应用等。
• 为用户添加额外的标识符。例如，Firebase 用户可以映射到另一个系统中的不同 UID。

假设您要限制对数据库节点“adminContent”的访问。您可以对管理员用户列表进行数据库查询来实现此目的。但是，有一种方法可以更高效地达成此目标，那就是将名为 admin 的自定义用户声明与以下 Realtime Database 规则搭配使用：

{
  "rules": {
    "adminContent": {
      ".read": "auth.token.admin === true",
      ".write": "auth.token.admin === true",
    }
  }
}

通过用户的身份验证令牌可以访问自定义用户声明。在上面的示例中，只有令牌声明中的 admin 设为 true 的用户才具有 adminContent 节点的读/写访问权限。由于 ID 令牌已包含这些断言，因此不需要进行额外的处理或查询来检查管理员权限。另外，ID 令牌是用于传递这些自定义声明的可信机制，所有经过身份验证的访问都必须先验证 ID 令牌，然后才能处理关联的请求。

注意：虽然自定义用户声明与自定义身份验证有关联，但不要将二者混淆。自定义身份验证一般是在将不同的身份验证系统与 Firebase 服务搭配时使用，或者用于通过非开箱支持的提供方服务为 Firebase Authentication 提供补充。自定义声明适用于已经使用受支持的提供方服务（电子邮件/密码、Google、Facebook、电话等）登录的用户。例如，您可以使用自定义声明，针对那些使用 Firebase Authentication 的电子邮件/密码提供方服务登录的用户来定义访问控制措施。

此页介绍的代码示例和解决方案提取自 Admin SDK 提供的客户端 Firebase Auth API 和服务器端 Auth API。

通过 Admin SDK 设置和验证自定义用户声明

由于自定义声明可能包含敏感数据，因此只能通过 Firebase Admin SDK 在特权服务器环境中进行设置。

Node.js

// Set admin privilege on the user corresponding to uid.

getAuth()
  .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.
  });

Java

// Set admin privilege on the user corresponding to uid.
Map<String, Object> claims = new HashMap<>();
claims.put("admin", true);
FirebaseAuth.getInstance().setCustomUserClaims(uid, claims);
// The new custom claims will propagate to the user's ID token the
// next time a new one is issued.

Python

# Set admin privilege on the user corresponding to uid.
auth.set_custom_user_claims(uid, {'admin': True})
# The new custom claims will propagate to the user's ID token the
# next time a new one is issued.

Go

// Get an auth client from the firebase.App
client, err := app.Auth(ctx)
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

// Set admin privilege on the user corresponding to uid.
claims := map[string]interface{}{"admin": true}
err = client.SetCustomUserClaims(ctx, uid, claims)
if err != nil {
	log.Fatalf("error setting custom claims %v\n", err)
}
// The new custom claims will propagate to the user's ID token the
// next time a new one is issued.
auth.go

C#

// Set admin privileges on the user corresponding to uid.
var claims = new Dictionary<string, object>()
{
    { "admin", true },
};
await FirebaseAuth.DefaultInstance.SetCustomUserClaimsAsync(uid, claims);
// The new custom claims will propagate to the user's ID token the
// next time a new one is issued.

注意：此操作会一律覆盖用户现有的自定义声明。但是，如果对通过自定义身份验证登录的用户指定了相同的自定义用户声明，则自定义令牌中指定的重叠声明具有更高的优先级，并且会一律覆盖通过此 API 对用户指定的自定义用户声明。
例如，如果调用 setCustomUserClaims(uid, {foo: 'bar', key1: 'value1'}) 并使用自定义令牌 createCustomToken(uid, {foo: 'overwrite', key2: 'value2'}) 让用户登录，则会对该用户指定以下声明：{foo: 'overwrite', key2: 'value2', key1: 'value1'})。

自定义声明对象不应包含任何 OIDC 预留的键名称或 Firebase 预留的名称。自定义声明载荷不得超过 1000 字节。

您可以使用 Admin SDK，根据发送到后端服务器的 ID 令牌来确认用户的身份以及访问权限级别，如下所示：

Node.js

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

Java

// Verify the ID token first.
FirebaseToken decoded = FirebaseAuth.getInstance().verifyIdToken(idToken);
if (Boolean.TRUE.equals(decoded.getClaims().get("admin"))) {
  // Allow access to requested admin resource.
}

Python

# Verify the ID token first.
claims = auth.verify_id_token(id_token)
if claims['admin'] is True:
    # Allow access to requested admin resource.
    pass

Go

// Verify the ID token first.
token, err := client.VerifyIDToken(ctx, idToken)
if err != nil {
	log.Fatal(err)
}

claims := token.Claims
if admin, ok := claims["admin"]; ok {
	if admin.(bool) {
		//Allow access to requested admin resource.
	}
}
auth.go

C#

// Verify the ID token first.
FirebaseToken decoded = await FirebaseAuth.DefaultInstance.VerifyIdTokenAsync(idToken);
object isAdmin;
if (decoded.Claims.TryGetValue("admin", out isAdmin))
{
    if ((bool)isAdmin)
    {
        // Allow access to requested admin resource.
    }
}

您还可以检查用户现有的自定义声明，这些声明作为用户对象的属性显示：

Node.js

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

Java

// Lookup the user associated with the specified uid.
UserRecord user = FirebaseAuth.getInstance().getUser(uid);
System.out.println(user.getCustomClaims().get("admin"));

Python

# Lookup the user associated with the specified uid.
user = auth.get_user(uid)
# The claims can be accessed on the user record.
print(user.custom_claims.get('admin'))

Go

// Lookup the user associated with the specified uid.
user, err := client.GetUser(ctx, uid)
if err != nil {
	log.Fatal(err)
}
// The claims can be accessed on the user record.
if admin, ok := user.CustomClaims["admin"]; ok {
	if admin.(bool) {
		log.Println(admin)
	}
}
auth.go

C#

// Lookup the user associated with the specified uid.
UserRecord user = await FirebaseAuth.DefaultInstance.GetUserAsync(uid);
Console.WriteLine(user.CustomClaims["admin"]);

您可以删除用户的自定义声明，只需为 customClaims 传递 null 即可。

将自定义声明传播至客户端

在通过 Admin SDK 修改用户的新声明后，修改后的声明将通过 ID 令牌传播给在客户端上经过身份验证的用户，方式如下：

• 用户在自定义声明修改后登录或重新进行身份验证，如此签发的 ID 令牌将包含最新的声明。
• 现有的用户会话在旧令牌到期之后其 ID 令牌将会刷新。
• 调用 currentUser.getIdToken(true) 可强制刷新 ID 令牌。

访问客户端上的自定义声明

您只能通过用户的 ID 令牌检索自定义声明。如需根据用户的角色或访问权限级别修改客户端界面，可能需要访问这些声明。但是，必须确保在验证 ID 令牌和解析其声明后，才能通过 ID 令牌执行后端访问。自定义声明不应直接发送到后端，因为它们在令牌之外不受信任。

在最新的声明传播到用户的 ID 令牌后，您可以通过检索 ID 令牌来获取这些声明：

JavaScript

firebase.auth().currentUser.getIdTokenResult()
  .then((idTokenResult) => {
     // Confirm the user is an Admin.
     if (!!idTokenResult.claims.admin) {
       // Show admin UI.
       showAdminUI();
     } else {
       // Show regular user UI.
       showRegularUI();
     }
  })
  .catch((error) => {
    console.log(error);
  });

Android

user.getIdToken(false).addOnSuccessListener(new OnSuccessListener<GetTokenResult>() {
  @Override
  public void onSuccess(GetTokenResult result) {
    boolean isAdmin = result.getClaims().get("admin");
    if (isAdmin) {
      // Show admin UI.
      showAdminUI();
    } else {
      // Show regular user UI.
      showRegularUI();
    }
  }
});

Swift

user.getIDTokenResult(completion: { (result, error) in
  guard let admin = result?.claims?["admin"] as? NSNumber else {
    // Show regular user UI.
    showRegularUI()
    return
  }
  if admin.boolValue {
    // Show admin UI.
    showAdminUI()
  } else {
    // Show regular user UI.
    showRegularUI()
  }
})

Objective-C

user.getIDTokenResultWithCompletion:^(FIRAuthTokenResult *result,
                                      NSError *error) {
  if (error != nil) {
    BOOL *admin = [result.claims[@"admin"] boolValue];
    if (admin) {
      // Show admin UI.
      [self showAdminUI];
    } else {
      // Show regular user UI.
      [self showRegularUI];
    }
  }
}];

自定义声明最佳做法

自定义声明仅用于提供访问控制，并非为了存储额外的数据（如配置文件和其他自定义数据）。虽然用其存储额外数据可能看起来很方便，但我们强烈建议不要这样做。由于这些声明存储在 ID 令牌中，而所有经过身份验证的请求会包含与登录用户对应的 Firebase ID 令牌，因而有可能会导致性能问题。

• 仅使用自定义声明来存储用于控制用户访问权限的数据。所有其他数据均应通过实时数据库或其他服务器端存储系统单独存储。
• 自定义声明的大小是有限的。自定义声明载荷不得超过 1000 字节，否则在传递时系统会抛出错误。

示例和使用情形

下面的示例结合特定的 Firebase 使用场景来说明自定义声明。

在创建用户时通过 Firebase Functions 定义角色

在此示例中，我们在创建用户时使用 Cloud Functions 为其设置自定义声明。

您可以使用 Cloud Functions 添加自定义声明，然后借助 Realtime Database 即时传播。系统只会在注册用户时使用 onCreate 触发器调用相关函数。自定义声明设置后，即会传播到现有和将来的所有会话。用户下次使用用户凭据登录时，令牌中就会包含自定义声明。

客户端实现 (JavaScript)

const provider = new firebase.auth.GoogleAuthProvider();
firebase.auth().signInWithPopup(provider)
.catch(error => {
  console.log(error);
});

let callback = null;
let metadataRef = null;
firebase.auth().onAuthStateChanged(user => {
  // Remove previous listener.
  if (callback) {
    metadataRef.off('value', callback);
  }
  // On user login add new listener.
  if (user) {
    // Check if refresh is required.
    metadataRef = firebase.database().ref('metadata/' + user.uid + '/refreshTime');
    callback = (snapshot) => {
      // Force refresh to pick up the latest custom claims changes.
      // Note this is always triggered on first call. Further optimization could be
      // added to avoid the initial trigger when the token is issued and already contains
      // the latest claims.
      user.getIdToken(true);
    };
    // Subscribe new listener to changes on that node.
    metadataRef.on('value', callback);
  }
});

Cloud Functions 逻辑

下例中添加了一个新的数据库节点 (metadata/($uid))，该节点只允许已通过身份验证的用户进行读/写操作。

const functions = require('firebase-functions');
const { initializeApp } = require('firebase-admin/app');
const { getAuth } = require('firebase-admin/auth');
const { getDatabase } = require('firebase-admin/database');

initializeApp();

// On sign up.
exports.processSignUp = functions.auth.user().onCreate(async (user) => {
  // Check if user meets role criteria.
  if (
    user.email &&
    user.email.endsWith('@admin.example.com') &&
    user.emailVerified
  ) {
    const customClaims = {
      admin: true,
      accessLevel: 9
    };

    try {
      // Set custom user claims on this newly created user.
      await getAuth().setCustomUserClaims(user.uid, customClaims);

      // Update real-time database to notify client to force refresh.
      const metadataRef = getDatabase().ref('metadata/' + user.uid);

      // Set the refresh time to the current UTC timestamp.
      // This will be captured on the client to force a token refresh.
      await  metadataRef.set({refreshTime: new Date().getTime()});
    } catch (error) {
      console.log(error);
    }
  }
});

数据库规则

{
  "rules": {
    "metadata": {
      "$user_id": {
        // Read access only granted to the authenticated user.
        ".read": "$user_id === auth.uid",
        // Write access only via Admin SDK.
        ".write": false
      }
    }
  }
}

通过 HTTP 请求定义角色

下面的示例显示了如何通过 HTTP 请求为新登录的用户设置自定义用户声明。

客户端实现 (JavaScript)

const provider = new firebase.auth.GoogleAuthProvider();
firebase.auth().signInWithPopup(provider)
.then((result) => {
  // User is signed in. Get the ID token.
  return result.user.getIdToken();
})
.then((idToken) => {
  // Pass the ID token to the server.
  $.post(
    '/setCustomClaims',
    {
      idToken: idToken
    },
    (data, status) => {
      // This is not required. You could just wait until the token is expired
      // and it proactively refreshes.
      if (status == 'success' && data) {
        const json = JSON.parse(data);
        if (json && json.status == 'success') {
          // Force token refresh. The token claims will contain the additional claims.
          firebase.auth().currentUser.getIdToken(true);
        }
      }
    });
}).catch((error) => {
  console.log(error);
});

后端实现 (Admin SDK)

app.post('/setCustomClaims', async (req, res) => {
  // Get the ID token passed.
  const idToken = req.body.idToken;

  // Verify the ID token and decode its payload.
  const claims = await getAuth().verifyIdToken(idToken);

  // Verify user is eligible for additional privileges.
  if (
    typeof claims.email !== 'undefined' &&
    typeof claims.email_verified !== 'undefined' &&
    claims.email_verified &&
    claims.email.endsWith('@admin.example.com')
  ) {
    // Add custom claims for additional privileges.
    await getAuth().setCustomUserClaims(claims.sub, {
      admin: true
    });

    // Tell client to refresh token on user.
    res.end(JSON.stringify({
      status: 'success'
    }));
  } else {
    // Return nothing.
    res.end(JSON.stringify({ status: 'ineligible' }));
  }
});

同样的流程也可用于升级现有用户的访问权限级别。 举例来说，一位免费用户正在升级到付费订阅。用户的 ID 令牌将与付款信息一起通过 HTTP 请求发送到后端服务器。成功处理付款后，系统会通过 Admin SDK 将用户设为付费订阅者。系统会将成功的 HTTP 响应返回给客户端以强制刷新令牌。

通过后端脚本指定角色

可以通过运行周期性脚本（而非从客户端启动）来更新用户自定义声明：

Node.js

getAuth()
  .getUserByEmail('[e-mail]')
  .then((user) => {
    // Confirm user is verified.
    if (user.emailVerified) {
      // Add custom claims for additional privileges.
      // This will be picked up by the user on token refresh or next sign in on new device.
      return getAuth().setCustomUserClaims(user.uid, {
        admin: true,
      });
    }
  })
  .catch((error) => {
    console.log(error);
  });

Java

UserRecord user = FirebaseAuth.getInstance()
    .getUserByEmail("[e-mail]");
// Confirm user is verified.
if (user.isEmailVerified()) {
  Map<String, Object> claims = new HashMap<>();
  claims.put("admin", true);
  FirebaseAuth.getInstance().setCustomUserClaims(user.getUid(), claims);
}

Python

user = auth.get_user_by_email('[e-mail]')
# Confirm user is verified
if user.email_verified:
    # Add custom claims for additional privileges.
    # This will be picked up by the user on token refresh or next sign in on new device.
    auth.set_custom_user_claims(user.uid, {
        'admin': True
    })

Go

user, err := client.GetUserByEmail(ctx, "[e-mail]")
if err != nil {
	log.Fatal(err)
}
// Confirm user is verified
if user.EmailVerified {
	// Add custom claims for additional privileges.
	// This will be picked up by the user on token refresh or next sign in on new device.
	err := client.SetCustomUserClaims(ctx, user.UID, map[string]interface{}{"admin": true})
	if err != nil {
		log.Fatalf("error setting custom claims %v\n", err)
	}

}
auth.go

C#

UserRecord user = await FirebaseAuth.DefaultInstance
    .GetUserByEmailAsync("[e-mail]");
// Confirm user is verified.
if (user.EmailVerified)
{
    var claims = new Dictionary<string, object>()
    {
        { "admin", true },
    };
    await FirebaseAuth.DefaultInstance.SetCustomUserClaimsAsync(user.Uid, claims);
}

也可以通过 Admin SDK 逐步修改自定义声明：

Node.js

getAuth()
  .getUserByEmail('[e-mail]')
  .then((user) => {
    // Add incremental custom claim without overwriting existing claims.
    const currentCustomClaims = user.customClaims;
    if (currentCustomClaims['admin']) {
      // Add level.
      currentCustomClaims['accessLevel'] = 10;
      // Add custom claims for additional privileges.
      return getAuth().setCustomUserClaims(user.uid, currentCustomClaims);
    }
  })
  .catch((error) => {
    console.log(error);
  });

Java

UserRecord user = FirebaseAuth.getInstance()
    .getUserByEmail("[e-mail]");
// Add incremental custom claim without overwriting the existing claims.
Map<String, Object> currentClaims = user.getCustomClaims();
if (Boolean.TRUE.equals(currentClaims.get("admin"))) {
  // Add level.
  currentClaims.put("level", 10);
  // Add custom claims for additional privileges.
  FirebaseAuth.getInstance().setCustomUserClaims(user.getUid(), currentClaims);
}

Python

user = auth.get_user_by_email('[e-mail]')
# Add incremental custom claim without overwriting existing claims.
current_custom_claims = user.custom_claims
if current_custom_claims.get('admin'):
    # Add level.
    current_custom_claims['accessLevel'] = 10
    # Add custom claims for additional privileges.
    auth.set_custom_user_claims(user.uid, current_custom_claims)

Go

user, err := client.GetUserByEmail(ctx, "[e-mail]")
if err != nil {
	log.Fatal(err)
}
// Add incremental custom claim without overwriting existing claims.
currentCustomClaims := user.CustomClaims
if currentCustomClaims == nil {
	currentCustomClaims = map[string]interface{}{}
}

if _, found := currentCustomClaims["admin"]; found {
	// Add level.
	currentCustomClaims["accessLevel"] = 10
	// Add custom claims for additional privileges.
	err := client.SetCustomUserClaims(ctx, user.UID, currentCustomClaims)
	if err != nil {
		log.Fatalf("error setting custom claims %v\n", err)
	}

}
auth.go

C#

UserRecord user = await FirebaseAuth.DefaultInstance
    .GetUserByEmailAsync("[e-mail]");
// Add incremental custom claims without overwriting the existing claims.
object isAdmin;
if (user.CustomClaims.TryGetValue("admin", out isAdmin) && (bool)isAdmin)
{
    var claims = user.CustomClaims.ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
    // Add level.
    var level = 10;
    claims["level"] = level;
    // Add custom claims for additional privileges.
    await FirebaseAuth.DefaultInstance.SetCustomUserClaimsAsync(user.Uid, claims);
}