Cloud Firestore: Enforcing Unique User Names
Solution 1
@asciimike
on twitter is a firebase security rules developer.
He says there is currently no way to enforce uniqueness on a key on a document. https://twitter.com/asciimike/status/937032291511025664
Since firestore
is based on Google Cloud datastore
it inherits this issue. It's been a long standing request since 2008.
https://issuetracker.google.com/issues/35875869#c14
However, you can achieve your goal by using firebase functions
and some strict security rules
.
You can view my entire proposed solution on medium. https://medium.com/@jqualls/firebase-firestore-unique-constraints-d0673b7a4952
Solution 2
Created another, pretty simple solution for me.
I have usernames
collection to storing unique values. username
is available if the document doesn't exist, so it is easy to check on front-end.
Also, I added the pattern ^([a-z0-9_.]){5,30}$
to valide a key value.
Checking everything with Firestore rules:
function isValidUserName(username){
return username.matches('^([a-z0-9_.]){5,30}$');
}
function isUserNameAvailable(username){
return isValidUserName(username) && !exists(/databases/$(database)/documents/usernames/$(username));
}
match /users/{userID} {
allow update: if request.auth.uid == userID
&& (request.resource.data.username == resource.data.username
|| isUserNameAvailable(request.resource.data.username)
);
}
match /usernames/{username} {
allow get: if isValidUserName(username);
}
Firestore rules will not allow updating user's document in case if the username already exists or have an invalid value.
So, Cloud Functions will be handling only in case if the username has a valid value and doesn't exist yet. So, your server will have much less work.
Everything you need with cloud functions is to update usernames
collection:
const functions = require("firebase-functions");
const admin = require("firebase-admin");
admin.initializeApp(functions.config().firebase);
exports.onUserUpdate = functions.firestore
.document("users/{userID}")
.onUpdate((change, context) => {
const { before, after } = change;
const { userID } = context.params;
const db = admin.firestore();
if (before.get("username") !== after.get('username')) {
const batch = db.batch()
// delete the old username document from the `usernames` collection
if (before.get('username')) {
// new users may not have a username value
batch.delete(db.collection('usernames')
.doc(before.get('username')));
}
// add a new username document
batch.set(db.collection('usernames')
.doc(after.get('username')), { userID });
return batch.commit();
}
return true;
});
Solution 3
Create a series of cloud functions that are triggered whenever a document is added, updated, or deleted in the users
table. The cloud functions will maintain a separate lookup table named usernames
, with document ids set to the usernames. Your front-end app can then query the usernames collection to see if a username is available.
Here is TypeScript code for the cloud functions:
/* Whenever a user document is added, if it contains a username, add that
to the usernames collection. */
export const userCreated = functions.firestore
.document('users/{userId}')
.onCreate((event) => {
const data = event.data();
const username = data.username.toLowerCase().trim();
if (username !== '') {
const db = admin.firestore();
/* just create an empty doc. We don't need any data - just the presence
or absence of the document is all we need */
return db.doc(`/usernames/${username}`).set({});
} else {
return true;
}
});
/* Whenever a user document is deleted, if it contained a username, delete
that from the usernames collection. */
export const userDeleted = functions.firestore
.document('users/{userId}')
.onDelete((event) => {
const data = event.data();
const username = data.username.toLowerCase().trim();
if (username !== '') {
const db = admin.firestore();
return db.doc(`/usernames/${username}`).delete();
}
return true;
});
/* Whenever a user document is modified, if the username changed, set and
delete documents to change it in the usernames collection. */
export const userUpdated = functions.firestore
.document('users/{userId}')
.onUpdate((event, context) => {
const oldData = event.before.data();
const newData = event.after.data();
if ( oldData.username === newData.username ) {
// if the username didn't change, we don't need to do anything
return true;
}
const oldUsername = oldData.username.toLowerCase().trim();
const newUsername = newData.username.toLowerCase().trim();
const db = admin.firestore();
const batch = db.batch();
if ( oldUsername !== '' ) {
const oldRef = db.collection("usernames").doc(oldUsername);
batch.delete(oldRef);
}
if ( newUsername !== '' ) {
const newRef = db.collection("usernames").doc(newUsername);
batch.set(newRef,{});
}
return batch.commit();
});
Solution 4
This works for me efficiently whereby username must be unique. I am able to add and edit usernames without duplicates.
NOTE: username must be in lowercase always, this eliminates duplicates caused by case sensitivity.
Create users collection:
/users (collection)
/{uid} (document)
- name "the username"
Create usernames collection:
/usernames (collection)
/{name} (document)
- uid "the auth {uid} field"
Then in firestore use the following rules:
match /databases/{database}/documents {
match /usernames/{name} {
allow read,create: if request.auth != null;
allow update: if
request.auth.uid == resource.data.uid;
}
match /users/{userId}{
allow read: if true;
allow create, update: if
request.auth.uid == userId &&
request.resource.data.name is string &&
request.resource.data.name.size() >=3 &&
get(/databases/$(database)/documents/usernames/$(request.resource.data.name)).data.uid == userId;
}
}
Solution 5
I store the usernames
in the same collection where each username occupies a unique document
ID. That way the username which already exists will not be created in the database.
Related videos on Youtube
crazypeter
Updated on June 14, 2022Comments
-
crazypeter about 2 years
The Problem
I have seen this question several times (also in the context of the Firebase Real-Time Database), but I haven't seen a convincing answer to it. The problem statement is fairly simple:
How can (authenticated) users choose a username that hasn't been taken yet?
First of all, the why: After a user authenticates, they have a unique user ID. Many web-apps, however, let the user choose a "display name" (how the user wants to appear on the website), in order to protect the users personal data (like real name).
The Users Collection
Given a data structure like the following it is possible to store a username along with other data for each user:
/users (collection) /{uid} (document) - name: "<the username>" - foo: "<other data>"
However, nothing prevents another user (with a different
{uid}
) to store the samename
in their record. As far as I know, there is no "security rule" that allows us to check if thename
has already been by another user.Note: A client side check is possible, but unsafe as a malicious client could omit the check.
The Reverse Mapping
Popular solutions are creating a collection with a reverse mapping:
/usernames (collection) /{name} (document) - uid: "<the auth {uid} field>"
Given this reverse mapping, it is possible to write a security rule to enforce that a username is not already taken:
match /users/{userId} { allow read: if true; allow create, update: if request.auth.uid == userId && request.resource.data.name is string && request.resource.data.name.size() >= 3 && get(/PATH/usernames/$(request.resource.data.name)).data.uid == userId; }
and to force a user to create a usernames document first:
match /usernames/{name} { allow read: if true; allow create: if request.resource.data.size() == 1 && request.resource.data.uid is string && request.resource.data.uid == request.auth.uid; }
I believe the solution is half-way there. However, there are still a few unsolved issues.
Remaining Issues / Questions
This implementation is quite involved already but it doesn't even solve the problem of users that want to change their user name (requires record deletion or update rules, etc.)
Another issue is, nothing prevents a user from adding multiple records in the
usernames
collection, effectively snatching all good usernames to sabotage the system.So to the questions:
- Is there a simpler solution to enforce unique usernames?
- How can spamming the
usernames
collection be prevented? - How can the username checks be made case-insensitive?
I tried also enforcing existence of the
users
, with anotherexists()
rule for the /usernames collection and then committing a batch write operation, however, this doesn't seem to work ("Missing or insufficient permissions" error).Another note: I have seen solutions with client-side checks. BUT THESE ARE UNSAFE. Any malicious client can modify the code, and omit checks.
-
crazypeter over 6 yearsSomebody working on Firestore twittert and I believe he suggested that it is not necessary to create the reverse lookup: twitter.com/abeisgreat/status/920730970751254528
-
gbhall over 6 yearsDid you come up with a solid solution to this?
-
crazypeter over 6 yearsI am basically using the solution above, I implemented the rules to support updating user names, but malicious spamming and case-insensitive matching is still an open issue.
-
Linxy over 6 yearshow about moving the client side check to functions? let the user send a 'change username request' to functions, and do the check there. If succesfull set the user's username from functions which should be read-only.
-
crazypeter over 6 yearsI have not worked with functions before, but it sounds ideal. Is such a thing feasible with functions?
-
Linxy over 6 yearsI'm pretty sure that is one of the main usecases for functions. Offload intensive data processing from the device (like thumbnail generation), execute sensitive operations (e.g enforcing unique usernames) in a secure environment and sending push notifications/emails (ofc. there are plenty more).
-
Brian Neisler over 4 yearsI believe this is possible using a combination of two collections, Firestore rules and batched writes. See my answer here for how this can be done stackoverflow.com/questions/47543251/…
-
Miguel Stevens over 2 yearswith the functions being async, how should we listen for the answer as to if a username is available or not from the client?
-
Mr.Drew over 5 yearsThis is an awesome workaround for webapps, but how can one enforce this on native apps with the new firestore?
-
Mr.Drew over 5 yearsAfter spending hours figuring out how to get this working (I kept getting invalid auth because I wasn't paying attention to your regex rules, also the line
{ userID }
should be a key value pair) I finally got it, although I had to add the linesadmin.initializeApp(functions.config().firebase);
as noted here in the docs for node.js -
Bohdan Didukh over 5 years@Mr.Drew The SDK can also be initialized with no parameters. In this case, the SDK uses Google Application Default Credentials and reads options from the FIREBASE_CONFIG environment variable. You can read more information here
-
Mr.Drew over 5 yearsAh I see that now, thanks. But I wonder why I didn't have to do that for a realtime datatbase functions file, but I did for this firestore one? In case anyone starting off stumbles upon this check here for more info about GOOGLE_APPLICATION_CREDENTIALS in server to server communications. Since it's still in beta I'm trying to get familiar with it and not implementing it in a larger scope project. Thus the default instructions in the first doc link worked for me.
-
Mr.Drew over 5 yearsWouldn't this forfeit the right of username transfer? At the very least you would need a more complex checking method to go through all the unique document IDs and check their fields.
-
Andre Cytryn about 5 yearsAny updates on this? No Firestore built in solution yet?
-
Ahsan over 4 years@Mr.Drew did you find a solution for this?
-
Mr.Drew over 4 years@Ahsan, not really, but there are a few strategies for different workarounds. One that comes to mind is creating a separate collection of current usernames to check every time you want to add or change a username. This requires more client side code or firebase functions that check the username collection though.
-
EmreAkkoc about 4 yearswhat if the user doesn't have an username yet and I want to change some other field in users/{ userID }
-
EmreAkkoc about 4 yearsalso !exists(/databases/{database}/documents/usernames/$(username)) is always returning false
-
EmreAkkoc about 4 yearscorrect me if I am wrong but on your cloud function line 51: if (unameDoc.exists && unameDoc.data.uid !== req.user.uid) I believe you meant ===
-
Bohdan Didukh about 4 years@EmreAkkoc, - security rules allowing to update other fields if the username is the same as it was or valid. - !exists(/databases/{database}/documents/usernames/$(username)) returns false only when the username exists.
-
Miguel Stevens over 2 yearsThis method doesn't allow the user to change other fields? Since the username property is hardcoded in the rules?
-
Miguel Stevens over 2 yearsWhat security rules do you use to prevent tampering from the client?
-
Derrick Miller over 2 yearsI'd post the entire firestore.rules file but it's too long. Here are the lines related to the usernames collection: // USERNAMES match /usernames/{username} { allow get: if true; // Can only query individual usernames to see if they're available allow list: if false; // Can't get a list of usernames allow create: if false; // Can't modify - that is handled by cloud functions allow update: if false; // Can't modify - that is handled by cloud functions allow delete: if false; // Can't modify - that is handled by cloud functions }
-
Miguel Stevens over 2 yearsThanks @Derrick, what rules do you have in place for the /users/{userId} itself?
-
Bohdan Didukh over 2 years@MiguelStevens, these rules will not give us permissions to update other fields only in the case of username value is changed and it is not available to use(chosen by someone else)
-
Miguel Stevens over 2 yearsTo create a user, his record must first be present in the /usernames table, is that correct?
-
Derrick Miller over 2 years@MiguelStevens // USERS match /users/{userId} { allow get: if true; // needed to allow viewing of user profiles allow list: if true; // Can this one be tightened up? allow create: if request.auth.uid != null && request.resource.data.username == '' && request.resource.data.isAdmin == 0; // don't allow users to escalate their own privs allow update: if request.auth.uid == userId && request.resource.data.isAdmin == 0; allow delete: if false; }