Google is committed to advancing racial equity for Black communities. See how.
This page was translated by the Cloud Translation API.
Switch to English

Контроль доступа с помощью пользовательских утверждений и правил безопасности

Firebase Admin SDK поддерживает определение пользовательских атрибутов для учетных записей пользователей. Это обеспечивает возможность реализации различных стратегий управления доступом, в том числе контроля доступа на основе ролей, в приложениях Firebase. Эти пользовательские атрибуты могут предоставлять пользователям разные уровни доступа (роли), которые применяются в правилах безопасности приложения.

Роли пользователя могут быть определены для следующих распространенных случаев:

  • Предоставление пользователю административных прав доступа к данным и ресурсам.
  • Определение различных групп, к которым принадлежит пользователь.
  • Предоставление многоуровневого доступа:
    • Различение платных / неоплачиваемых абонентов.
    • Отличие модераторов от обычных пользователей.
    • Заявление учителя / ученика и т. Д.
  • Добавьте дополнительный идентификатор для пользователя. Например, пользователь Firebase может сопоставить другой UID в другой системе.

Давайте рассмотрим случай, когда вы хотите ограничить доступ к базе данных узла «adminContent». Вы можете сделать это с помощью поиска в базе данных в списке пользователей с правами администратора. Однако вы можете достичь той же цели более эффективно, используя пользовательское утверждение с именем admin со следующим правилом базы данных в реальном времени:

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

Пользовательские утверждения пользователя доступны через токены аутентификации пользователя. В приведенном выше примере только пользователи с admin установленным в true в их заявке на токен, будут иметь доступ на чтение / запись к узлу adminContent . Поскольку токен ID уже содержит эти утверждения, для проверки прав администратора не требуется никакой дополнительной обработки или поиска. Кроме того, токен ID является доверенным механизмом для доставки этих пользовательских утверждений. Весь аутентифицированный доступ должен проверять идентификатор токена перед обработкой соответствующего запроса.

Примеры кода и решения, описанные на этой странице, основаны как на клиентских API Firebase Auth, так и на серверных Auth API, предоставляемых Admin SDK .

Установка и проверка пользовательских утверждений пользователя через Admin SDK

Пользовательские утверждения могут содержать конфиденциальные данные, поэтому их следует устанавливать только из привилегированной серверной среды с помощью Firebase Admin SDK.

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.
 

Объект пользовательских требований не должен содержать какой - либо РСИН защищены имена ключей или Firebase зарезервированных имена. Полезная нагрузка пользовательских требований не должна превышать 1000 байт.

Идентификационный токен, отправленный на внутренний сервер, может подтвердить личность пользователя и уровень доступа с помощью Admin 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 .

Распространение пользовательских требований к клиенту

После изменения новых утверждений для пользователя с помощью Admin SDK они передаются аутентифицированному пользователю на стороне клиента с помощью токена идентификатора следующими способами:

  • Пользователь входит в систему или повторно аутентифицируется после изменения пользовательских требований. Идентификационный токен, выданный в результате, будет содержать последние заявки.
  • Существующий пользовательский сеанс получает свой токен ID, обновленный после истечения срока действия старого токена.
  • Идентификационный токен принудительно обновляется с помощью вызова currentUser.getIdToken(true) .

Доступ к настраиваемым претензиям клиента

Пользовательские заявки могут быть получены только через токен 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();
    }
  }
});
 

стриж

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

Логика облачных функций

Добавлен новый узел базы данных (метаданные / ($ uid)} с правами чтения / записи, доступными только аутентифицированному пользователю.

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

const admin = require('firebase-admin');
admin.initializeApp();

// On sign up.
exports.processSignUp = functions.auth.user().onCreate((user) => {
  // Check if user meets role criteria.
  if (user.email &&
      user.email.endsWith('@admin.example.com') &&
      user.emailVerified) {
    const customClaims = {
      admin: true,
      accessLevel: 9
    };
    // Set custom user claims on this newly created user.
    return admin.auth().setCustomUserClaims(user.uid, customClaims)
      .then(() => {
        // 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.
        return 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', (req, res) => {
  // Get the ID token passed.
  const idToken = req.body.idToken;
  // Verify the ID token and decode its payload.
  admin.auth().verifyIdToken(idToken).then((claims) => {
    // 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.
      admin.auth().setCustomUserClaims(claims.sub, {
        admin: true
      }).then(function() {
        // 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

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

 

Пользовательские утверждения также можно изменять постепенно с помощью Admin 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);
}