Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

שלוט בגישה באמצעות תביעות מותאמות אישית וכללי אבטחה

ה- SDK של מנהל ה- Firebase תומך בהגדרת מאפיינים מותאמים אישית בחשבונות משתמש. זה מספק את היכולת ליישם אסטרטגיות שונות לבקרת גישה, כולל בקרת גישה מבוססת תפקידים, באפליקציות Firebase. מאפיינים מותאמים אישית אלה יכולים להעניק למשתמשים רמות גישה שונות (תפקידים), הנאכפות בכללי האבטחה של היישום.

ניתן להגדיר תפקידי משתמשים במקרים הנפוצים הבאים:

  • הענקת הרשאות ניהול למשתמש לגישה לנתונים ומשאבים.
  • הגדרת קבוצות שונות שמשתמש משתייך אליהן.
  • מתן גישה מרובת רמות:
    • הבחנה בין מנויים בתשלום / ללא תשלום.
    • הבחנה בין מנחים למשתמשים רגילים.
    • בקשה למורה / סטודנט וכו '.
  • הוסף מזהה נוסף למשתמש. לדוגמא, משתמש Firebase יכול למפות ל- UID אחר במערכת אחרת.

הבה נבחן מקרה בו ברצונך להגביל את הגישה לצומת מסד הנתונים "adminContent." אתה יכול לעשות זאת באמצעות בדיקת מסד נתונים ברשימה של משתמשי מנהל. עם זאת, תוכל להשיג את אותה מטרה ביעילות רבה יותר באמצעות תביעת משתמש מותאמת אישית בשם admin עם הכלל הבא של מסד נתונים בזמן אמת:

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

ניתן לגשת לתביעות של משתמשים מותאמים אישית באמצעות אסימוני האימות של המשתמש. בדוגמה שלעיל, רק משתמשים עם admin שהוגדר כ- true בתביעת האסימון שלהם היו בעלי גישה לקריאה / כתיבה לצומת adminContent . מכיוון שאסימון הזיהוי כבר מכיל קביעות אלו, אין צורך בעיבוד או בדיקה נוספת בכדי לבדוק הרשאות מנהל. בנוסף, אסימון הזיהוי הוא מנגנון מהימן למסירת תביעות מותאמות אישית אלה. כל הגישה המאומתת חייבת לאמת את אסימון הזיהוי לפני עיבוד הבקשה המשויכת.

דוגמאות הקוד והפתרונות המתוארים בעמוד זה נובעים הן מממשקי ה- API האוטומטיים של Firebase Auth בצד הלקוח והן מממשקי ה- API האוטומטיים בצד השרת המסופקים על ידי ה- SDK של מנהל המערכת .

הגדר ואמת תביעות של משתמשים מותאמים אישית באמצעות ערכת SDK

תביעות מותאמות אישית יכולות להכיל נתונים רגישים, ולכן יש להגדיר אותן רק מסביבת שרתים מועדפת על ידי SDK מנהל המערכת של Firebase.

Node.js

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

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

ג'אווה

// 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.

פִּיתוֹן

# 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.

ללכת

// 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.

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.

אובייקט התביעות המותאם אישית לא אמור להכיל שמות מפתח שמורים ל- OIDC או שמות שמורים ל- Firebase. עומס המטען של תביעות מותאמות אישית לא יעלה על 1000 בתים.

אסימון מזהה שנשלח לשרת backend יכול לאשר את זהות המשתמש ורמת הגישה באמצעות ה- SDK למנהלים באופן הבא:

Node.js

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

ג'אווה

// 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.
}

פִּיתוֹן

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

ללכת

// 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.
	}
}

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.
admin
  .auth()
  .getUser(uid)
  .then((userRecord) => {
    // The claims can be accessed on the user record.
    console.log(userRecord.customClaims['admin']);
  });

ג'אווה

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

פִּיתוֹן

# 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'))

ללכת

// 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)
	}
}

C #

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

באפשרותך למחוק את התביעות המותאמות אישית של המשתמש על ידי העברת null עבור customClaims .

להפיץ תביעות מותאמות אישית ללקוח

לאחר שינוי תביעות חדשות על משתמש באמצעות SDK Admin, הם מועברים למשתמש מאומת בצד הלקוח באמצעות אסימון הזיהוי בדרכים הבאות:

  • משתמש נכנס או מאמת מחדש לאחר שינוי התביעות המותאמות אישית. אסימון הזהות שהונפק כתוצאה מכך יכלול את התביעות האחרונות.
  • מושב משתמשים קיים מקבל את רענון אסימון הזיהוי שלו לאחר שתוקף אסימון ישן יותר.
  • אסימון מזהה מתרענן בכוח על ידי קריאה ל- currentUser.getIdToken(true) .

גישה לתביעות מותאמות אישית על הלקוח

ניתן לאחזר תביעות מותאמות אישית רק באמצעות אסימון הזיהוי של המשתמש. ייתכן שיהיה צורך בגישה לתביעות אלה כדי לשנות את ממשק המשתמש של הלקוח על סמך תפקיד המשתמש או רמת הגישה. עם זאת, תמיד יש לאכוף את הגישה למערך באמצעות אסימון הזיהוי לאחר אימותו וניתוח טענותיו. אין לשלוח תביעות מותאמות אישית ישירות אל ה- backend, מכיוון שלא ניתן לסמוך עליהן מחוץ לאסימון.

לאחר שהתביעות האחרונות הופצו לאסימון הזיהוי של המשתמש, תוכל להשיג אותן על ידי אחזור אסימון הזיהוי:

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);
  });

דְמוּי אָדָם

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

מָהִיר

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()
  }
})

מטרה-ג

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];
    }
  }
}];

שיטות עבודה מומלצות לתביעות מותאמות אישית

תביעות מותאמות אישית משמשות רק למתן בקרת גישה. הם לא נועדו לאחסן נתונים נוספים (כגון פרופיל ונתונים מותאמים אישית אחרים). אמנם זה עשוי להיראות כמו מנגנון נוח לעשות זאת, אך הוא לא מתייאש מאוד מכיוון שטענות אלה מאוחסנות באסימון הזיהוי ועלולות לגרום לבעיות ביצועים מכיוון שכל הבקשות המאומתות מכילות תמיד אסימון מזהה Firebase המתאים למשתמש המחובר.

  • השתמש בתביעות מותאמות אישית כדי לאחסן נתונים לצורך בקרת גישת משתמשים בלבד. יש לאחסן את כל הנתונים האחרים בנפרד באמצעות מסד הנתונים בזמן אמת או אחסון אחר בצד השרת.
  • תביעות מותאמות אישית מוגבלות בגודלן. העברת מטען תביעות מותאם אישית העולה על 1000 בתים תגרום לשגיאה.

דוגמאות ומקרי שימוש

הדוגמאות הבאות מדגימות תביעות מותאמות אישית בהקשר למקרי שימוש ספציפיים של Firebase.

הגדרת תפקידים באמצעות פונקציות Firebase ביצירת משתמשים

בדוגמה זו, תביעות מותאמות אישית מוגדרות על משתמש בעת יצירתו באמצעות פונקציות ענן.

ניתן להוסיף טענות מותאמות אישית באמצעות ענן פונקציות, ולהפיץ אותן באופן מיידי באמצעות מסד נתונים בזמן אמת. הפונקציה נקראת רק בהרשמה באמצעות טריגר 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);
  }
});

לוגיקה של פונקציות ענן

נוסף צומת מסד נתונים (מטא נתונים / ($ uid)} עם קריאה / כתיבה מוגבלת למשתמש המאומת.

const functions = require('firebase-functions');

const admin = require('firebase-admin');
admin.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 admin.auth().setCustomUserClaims(user.uid, customClaims);

      // Update real-time database to notify client to force refresh.
      const metadataRef = admin.database().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);
});

יישום Backend (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 admin.auth().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 admin.auth().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' }));
  }
});

ניתן להשתמש באותה זרימה בעת שדרוג רמת הגישה של משתמש קיים. קחו לדוגמא משתמש בחינם המשדרג למנוי בתשלום. אסימון מזהה המשתמש נשלח עם פרטי התשלום לשרת ה- backend באמצעות בקשת HTTP. כאשר התשלום מעובד בהצלחה, מוגדר המשתמש כמנוי בתשלום באמצעות מנהל ה- SDK. תשובת HTTP מוצלחת מוחזרת ללקוח כדי לאלץ רענון אסימון.

הגדרת תפקידים באמצעות תסריט backend

ניתן להגדיר סקריפט חוזר (שלא יזם מהלקוח) שיופעל כדי לעדכן תביעות מותאמות אישית של המשתמש:

Node.js

admin
  .auth()
  .getUserByEmail('user@admin.example.com')
  .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 admin.auth().setCustomUserClaims(user.uid, {
        admin: true,
      });
    }
  })
  .catch((error) => {
    console.log(error);
  });

ג'אווה

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

פִּיתוֹן

user = auth.get_user_by_email('user@admin.example.com')
# 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
    })

ללכת

user, err := client.GetUserByEmail(ctx, "user@admin.example.com")
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)
	}

}

C #

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

ניתן לשנות תביעות מותאמות אישית גם באופן הדרגתי באמצעות ערכת SDK:

Node.js

admin
  .auth()
  .getUserByEmail('user@admin.example.com')
  .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 admin.auth().setCustomUserClaims(user.uid, currentCustomClaims);
    }
  })
  .catch((error) => {
    console.log(error);
  });

ג'אווה

UserRecord user = FirebaseAuth.getInstance()
    .getUserByEmail("user@admin.example.com");
// 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);
}

פִּיתוֹן

user = auth.get_user_by_email('user@admin.example.com')
# 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)

ללכת

user, err := client.GetUserByEmail(ctx, "user@admin.example.com")
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)
	}

}

C #

UserRecord user = await FirebaseAuth.DefaultInstance
    .GetUserByEmailAsync("user@admin.example.com");
// Add incremental custom claims without overwriting the existing claims.
object isAdmin;
if (user.CustomClaims.TryGetValue("admin", out isAdmin) && (bool)isAdmin)
{
    var claims = new Dictionary<string, object>(user.CustomClaims);
    // Add level.
    claims["level"] = 10;
    // Add custom claims for additional privileges.
    await FirebaseAuth.DefaultInstance.SetCustomUserClaimsAsync(user.Uid, claims);
}