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

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

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

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

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

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

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

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

הגדר ואמת תביעות משתמש מותאמות אישית באמצעות ה-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.

פִּיתוֹן

# 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 בתים.

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

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

פִּיתוֹן

# 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']);
  });

Java

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

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

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

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

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

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

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

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 ID המתאים למשתמש המחובר.

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

יישום אחורי (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' }));
  }
});

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

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

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

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

Java

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

ניתן לשנות תביעות מותאמות אישית גם בהדרגה באמצעות ה-Admin 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);
  });

Java

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