Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

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

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

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

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

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

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

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

הדוגמאות קוד ופתרונות המתוארות בדף זה לצייר משני APIs בצד הלקוח Firebase המחבר ואת בצד השרת המחבר APIs שמספקת SDK של ניהול .

הגדר ואמת תביעות משתמש מותאמות אישית באמצעות ה- SDK לניהול

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

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

ג'אווה

// 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.
getAuth()
  .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.
getAuth()
  .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 של מנהל המערכת, הן מופצות למשתמש מאומת בצד הלקוח באמצעות אסימון המזהה בדרכים הבאות:

  • משתמש נכנס או מאמת מחדש לאחר שינוי התביעות המותאמות אישית. אסימון הזיהוי שהונפק כתוצאה מכך יכיל את הטענות האחרונות.
  • הפעלת משתמש קיימת מרעננת את אסימון המזהה שלה לאחר פקיעת תוקפו של האסימון הישן יותר.
  • מזהה של אסימון הוא כוח הרענון על ידי התקשרות 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()
  }
})

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

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

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

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

צומת מסד נתונים חדש (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);
});

יישום backend (מנהל מערכת 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' }));
  }
});

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

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

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

Node.js

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

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