6.8 KiB
Getting started
Installation
Nhost
The easiest way to deploy HBP is with the official Nhost managed service. Get your perfect configured backend with PostgreSQL, Hasura and Hasura Backend Plus and save yourself hours of maintenance per month.
All Nhost projects are built on open source software so you can make realtime web and mobile apps fast 🚀.
Docker-Compose
Create the following docker-compose.yaml file, and modify the Hasura Admin Secret in both graphql-engine and hasura-backend-plus services.
<<< @/examples/simple-hasura-minio/docker-compose.yaml
Then start the services:
export HASURA_GRAPHQL_ADMIN_SECRET=<your Hasura Admin secret>
export S3_SECRET_ACCESS_KEY=<your Minio access key>
docker-compose up -d
Everything should be up and running. HBP is listening to http://localhost:3000, Hasura Graphql Engine is listening to http://localhost:8080.
You can then run the Hasura Console in following the official instructions.
Standalone
You can also install HBP without any other service, and connect it to an existing Hasura server, and/or an S3 instance if you plan to use the storage features. The easiest way is to pull and run a Docker container, but you can also run the service from the source code.
You will also need to make sure the HBP migrations and metadata are loaded in your Hasura instance, either in using the AUTO_MIGRATE=true environment variable, or in loading the migrations manually. Please see the related configuration chapter for further details.
Using Docker
docker run -d -p 3000:3000 \
-e "HASURA_ENDPOINT=<your Hasura graphql endpoint>" \
-e "HASURA_GRAPHQL_ADMIN_SECRET=<your Hasura admin secret>" \
-e "JWT_KEY=<your JWT RSA256 key>" \
nhost/hasura-backend-plus:latest
From the source code
git clone https://github.com/nhost/hasura-backend-plus.git
cd hasura-backend-plus
yarn
cp .env.example .env
yarn start
Registration
By default, anyone can register with an email address and a password:
curl -d '{"email":"real@emailadress.com", "password":"StrongPasswordNot1234"}' -H "Content-Type: application/json" -X POST http://localhost:3000/auth/register`
You can add some safeguards and limitations to the registration process like email verification, constraints on emails and passwords, or setting additional registration fields from your custom database schema. More information is available in the registration configuration chapter.
Login
Once an user is registered, they can connect to HBP with the /auth/login endpoint:
curl -d '{"email":"real@emailadress.com", "password":"StrongPasswordNot1234"}' -H "Content-Type: application/json" -X POST http://localhost:3000/auth/login`
It will return the following payload:
{
"jwt_token": "<the user Hasura-compatible JWT>",
"jwt_expires_in": "<the number of milliseconds of validity of the JWT>"
}
You'll find more details about how HBP handles the session and JWT in the JWT section.
Multi-Factor Authentication
By default, any authenticted user can decide to add TOTP multi-factor authentication (MFA). It will require the user to get a generator such as Authy or Google Authenticator.
Generate
The first step to activate MFA is to generate a secret through the /auth/mfa/generate POST endpoint:
curl -H "Content-Type: application/json" -X POST http://localhost:3000/auth/mfa/generate`
It will return the following payload:
{
"otp_secret": "<the otp secret>",
"image_url": "<the base64-encoded QR Code png image>"
}
The client now goes to its favorite MFA app (e.g. Google Authenticator) and enters its secret either manually or in using the QR-code generated by the server.
Enable
Once the user fetched their OTP secret, they must generate a verification code and send it to HBP to complete the activation or MFA. The code is send to the /auth/mfa/enable POST endpoint:
curl -d '{"code":"<verification-code>"}' -H "Content-Type: application/json" -X POST http://localhost:3000/auth/mfa/enable`
The server should return a 204 HTTP code. The user login will now have an additional step as explained in the following section.
Login
When an user enabled MFA, they still send their user/email credentials to /auth/login, but the payload will now become:
{
"mfa": true,
"ticket": "<an automatically one-time only generated ticket>"
}
The next step to finish the authentication is to send back the ticket with the verification code from your favorite MFA app to /auth/mfa/totp:
curl -d '{"ticket":"<generated-ticket>", code":"<verification-code>"}' -H "Content-Type: application/json" -X POST http://localhost:3000/auth/mfa/totp`
The HBP session is then opened with the client, and the JWT is sent back as the payload:
{
"jwt_token": "<the user Hasura-compatible JWT>",
"jwt_expires_in": "<the number of milliseconds of validity of the JWT>"
}
Disable
JWT
When the user logs in, HBP sets an HTTP-Only cookie to store session information and a refresh token.
::: warning Never store a JWT in the local storage of the browser as it is prone to XSS attacks! Keep a short expiration period instead, and get a refreshed JWT through HBP. :::
The jwt_expires_in indicates the maximum frequency in which the browser will need to refresh the JWT.
You can get a refreshed JWT throught the /auth/token/refresh GET endpoint:
curl -H "Content-Type: application/json" http://localhost:3000/auth/token/refresh`
It will return the same kind of payload as in /auth/login, with a new JWT:
{
"jwt_token": "<the user Hasura-compatible JWT>",
"jwt_expires_in": "<the number of milliseconds of validity of the JWT>"
}