firebase-users-admin is a backend app featuring CRUD API endpoints for managing Firebase Authentication users using the firebase-admin SDK for NodeJS.
A basic web app client in the /client directory will show basic API usage and demonstration.
- Requirements
- Installation
- Usage
- Available Scripts - server
- Installation and Usage Using Docker
- References
- Windows 10, MacOS, Linux
- NodeJS v14.18.3 or higher
- Firebase Project [link]
- Pricing Plan: Spark plan or higher
- with the Email/Password Provider enabled in the Firebase Console's
Authentication -> Sign-in method -> Sign-in providers options. - Service account credentials JSON file
- firebase-admin v10.0.2
- Firebase Authentication (using Email/Password Provider)
- React 18.1.0 (CRA) on client app
-
Clone this repository.
git clone https://github.com/ciatph/firebase-users-admin.git
-
Install dependencies.
cd server npm install
-
Set up the environment variables. Create a
.env
file inside the /server directory with reference to the.env.example
file. Encode your own Firebase project settings on the following variables:Variable Name Description FIREBASE_SERVICE_ACC The project's private key file contents, condensed into one line and minus all whitespace characters.
The service account JSON file is generated from the Firebase project's Project Settings page, on Project Settings -> Service accounts -> Generate new private keyFIREBASE_PRIVATE_KEY The private_key
entry from the service account JSON file.
NOTE: Take note to make sure that the value starts and ends with a double-quote on WINDOWS OS localhost. Some systems may or may not require the double-quotes (i.e., Ubuntu running on heroku).
ALLOWED_ORIGINS IP/domain origins in comma-separated values that are allowed to access the API. Include http://localhost:3000
by default to allow CORS access to the/client
app.EMAIL_WHITELIST Comma-separated email addresses linked to Firebase Auth UserRecords that are not allowed to be deleted or updated (write-protected)
Default value issuperadmin@gmail.com
ALLOW_CORS Allow Cross-Origin Resource Sharing (CORS) on the API endpoints.
Default value is1
. Setting to0
will make all endpoints accept requests from all domains, including Postman.
-
Install dependencies.
cd client npm install
-
Replace the
/client/utils/firebase/firebase.config.js
file with your own Firebase project's web SDK setup configuration file.- You can find this file in a Firebase project's
Project Settings -> General -> Web apps (Add an app if needed) -> SDK setup and configuration - The
firebase.config.js
settings must match with theFIREBASE_SERVICE_ACC
environment variable defined on server - step # 3.
- You can find this file in a Firebase project's
-
Create a
/client/.env
file from the/client/.env.example
file. Replace theREACT_APP_BASE_URL
variable with an appropriate value.Variable Name Description REACT_APP_BASE_URL Domain on which the CRUD API is running.
Default value ishttp://localhost:3001/api
on localhost. See the server set-up instructions for more information. -
Run the app in development mode.
npm start
-
Launch the client app in:
http://localhost:3000
- Navigate to the
/server
directory. - Create a default Firebase Auth user.
npm run seed
- Generate the API documentation.
npm run gen:docs
- Run the app:
- (development mode)
npm run dev
- (production mode)
npm start
- (development mode)
- Read the API documentation and usage examples guide of available CRUD API endpoints on:
http://localhost:3001/docs
- Try to log-in to the
/client
app using the default superadmin seeded user from step no. 2:username: superadmin@gmail.com password: 123456789
- Use the CRUD API endpoints to create/update/delete or view Firebase Auth users using Postman, curl, or other http clients.
- Try signing in these users to the
/client
app. -
NOTE: Comment out the
cors
options lineapp.use(cors(corsOptions))
on /server/src/index.js when testing on Postman and other http clients other than the/client
app.
- Try signing in these users to the
The npm scripts listed below are available under the /server directory.
Run the express app (API only) in production mode. You'll need to npm run gen:docs
if you haven't done so already, if you'd also like to view the API documentation usage in production mode.
Run the express app (API only) in development mode.
Builds the API documentation. The static website documentation files are put in the /src/public/docs
directory, and made available on http://localhost:3001/docs
.
Creates an initial superadmin Firebase Authentication user with the credentials:
email: superadmin@gmail.com
displayname: Super Admin
password: 123456789
account_level: 1
Copies the built /client
website from /client/build
to the server's root directory.
- It requires to build the client app first, after following its set-up instructions:
cd client npm run build
- The built client app will be viewable on
http://localhost:3001
if the server is running.
We can use Docker to run dockerized client and server apps for local development. The following methods require Docker and Docker compose correctly installed and set up on your development machine.
- Set-up the environment variables and firebase configuration file for the /client app.
- Create (your own)
firebase.config.js
file under/client/utils/firebase/firebase.config.js
as advised on Installation - client # 2. - Create the
.env
file under the /client directory as advised on Installation - client # 3.
- Create (your own)
- Set-up the environment variables for the /server app.
- Create the
.env
file under the /server directory as advised on Installation - server # 3.
- Create the
- Build the client and server docker services for localhost development.
docker-compose -f docker-compose-dev.yml build
-
INFO: Building the images for localhost development takes a while, around ~7min+.
- Create and start the client and server containers.
docker-compose -f docker-compose-dev.yml up
- Run a script in the container to create the default
superadmin@gmail.com
account, if it does not yet exist in the Firestore database.
docker exec -it server-prod npm run seed
- Launch the dockerized (dev) client app on
http://localhost:3000
- Launch the dockerized (dev) server app's API documentation on
http://localhost:3001/docs
- Edit source the codes in
/client/src
or/server/src
as needed. Verify that hot reload is working on both the client and server apps. - Stop and remove containers, networks, images and volumes:
docker-compose -f docker-compose-dev.yml down
The following docker-compose commands build small client and server images targeted for creating optimized dockerized apps running on self-managed production servers. Hot reload is not available when editing source codes from /client/src
or /server/src
.
- Install and set up the required client and server environment variables as with the required variables on Docker for Localhost Development.
- Build the client and server docker services for production deployment.
docker-compose -f docker-compose-prod.yml build
- At this point, we can opt to push the docker images to a docker registry of your choice. (Requires sign-in to the selected docker registry).
docker-compose -f docker-compose-prod.yml push
- Create and start the client and server containers.
docker-compose -f docker-compose-prod.yml up
- Run a script in the container to create the default
superadmin@gmail.com
account, if it does not yet exist in the Firestore database.
docker exec -it server-prod npm run seed
- Launch the dockerized (prod) client app on
http://localhost:3000
- Launch the dockerized (prod) server app's API documentation on
http://localhost:3001/docs
- Stop and remove containers, networks, images and volumes:
docker-compose -f docker-compose-prod.yml down
firebase-users-admin's server
component is available as a stand-alone docker image on Docker Hub with customizable environment variables (.env file).
- Pull the (production) /server docker image from Docker Hub.
docker pull ciatphdev/firebase-users-admin-server:v1.1.1
- Create a
.env
file.- Read Installation - server #3 for more information.
- Replace the variables accordingly in the
.env
file.ALLOWED_ORIGINS=http://localhost,http://localhost:3000,http://mywebsite.com,http://yourwebsite.com FIREBASE_SERVICE_ACC=YOUR-FIREBASE-PROJ-SERVICE-ACCOUNT-JSON-CREDENTIALS-ONE-LINER-NO-SPACES FIREBASE_PRIVATE_KEY=PRIVATE-KEY-FROM-FIREBASE-SERVICE-ACCOUNT-JSON-WITH-DOUBLE-QUOTES EMAIL_WHITELIST=superadmin@gmail.com ALLOW_CORS=1
- Run the image.
docker run -it --rm \ --env-file .env \ -p 3001:3001 \ ciatphdev/firebase-users-admin-server:v1.1.1
- Run a script in the container to create the default
superadmin@gmail.com
account, if it does not yet exist in the Firestore database.
docker exec -it server-prod npm run seed
- Launch the server API documentation on
http://localhost:3001/docs
[1] - docker compose commands
@ciatph
20220406