Prelude API v2 and Firebase Auth integration

Here we show a sample Go application that verifies a user’s phone number with Prelude, then authenticates them in Firebase Auth, creating the account if it does not exist yet. The server exposes 2 endpoints. Clients call /send_code to send a verification code to a phone number, then /verify with the phone number and the code they received. If the code is correct, the response carries a Firebase custom token for the user. See the full example on GitHub.

Prerequisites

A recent Go version. To set this up, follow the Go docs.
A Prelude account. If you don’t have one already, you can sign up here.
A Firebase project with Auth enabled. Follow the Firebase docs.

Outside Google Cloud you also need a service account key file, generated from the Firebase project settings, in the “Service accounts” section.

Setting up the project

Create a new directory and configure the Go module and dependencies:

Create a new Go module: go mod init example.com/prelude-firebase-integration
Install the Prelude Go SDK: go get github.com/prelude-so/go-sdk
Install the Firebase SDK: go get firebase.google.com/go/v4
From the Prelude dashboard, select your application, go to Configure, Keys and click “Generate Key”. Make a note of this key as you can not reveal it again in the dashboard.

Both SDKs read their credentials from the environment, so the code holds no configuration of its own:

export API_TOKEN=sk_XXXXXXXX

# Outside Google Cloud only. There, the credentials come from the metadata
# server.
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

The server

Create a main.go file in that directory. It builds the two clients, holds them on a server value, and routes the two endpoints:

package main

import (
	"context"
	"encoding/json"
	"log"
	"net/http"

	firebase "firebase.google.com/go/v4"
	firebaseauth "firebase.google.com/go/v4/auth"
	prelude "github.com/prelude-so/go-sdk"
)

const addr = ":8080"

func main() {
	ctx := context.Background()

	app, err := firebase.NewApp(ctx, nil)
	if err != nil {
		log.Fatalf("initialize firebase: %v", err)
	}

	authClient, err := app.Auth(ctx)
	if err != nil {
		log.Fatalf("initialize firebase auth: %v", err)
	}

	// NewClient reads the API token from API_TOKEN.
	srv := &server{prelude: prelude.NewClient(), auth: authClient}

	log.Printf("listening on %s", addr)
	log.Fatal(http.ListenAndServe(addr, srv.handler()))
}

// server wires the Prelude and Firebase clients into the HTTP handlers.
type server struct {
	prelude *prelude.Client
	auth    *firebaseauth.Client
}

// handler routes the two endpoints. The mux answers anything else, including a
// known path reached with the wrong method.
func (s *server) handler() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /send_code", s.sendCode)
	mux.HandleFunc("POST /verify", s.verify)
	return mux
}

Neither client is given options: the Firebase SDK finds the service account through GOOGLE_APPLICATION_CREDENTIALS, and the Prelude SDK reads API_TOKEN.

Requesting a verification code

POST http://localhost:8080/send_code
Content-Type: application/json

{
  "phone_number": "+[COUNTRY_CODE][PHONE_NUMBER]"
}

phone_number is an E.164 formatted mobile phone number. For instance, a French mobile number would be formatted as +33XXXXXXXXX.

func (s *server) sendCode(w http.ResponseWriter, r *http.Request) {
	var req struct {
		PhoneNumber string `json:"phone_number"`
	}
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "invalid request body", http.StatusBadRequest)
		return
	}

	_, err := s.prelude.Verification.New(r.Context(), prelude.VerificationNewParams{
		Target: prelude.F(prelude.VerificationNewParamsTarget{
			Type:  prelude.F(prelude.VerificationNewParamsTargetTypePhoneNumber),
			Value: prelude.F(req.PhoneNumber),
		}),
	})
	if err != nil {
		http.Error(w, "could not send code", http.StatusBadGateway)
		return
	}

	w.WriteHeader(http.StatusNoContent)
}

We read the phone number from the body and pass it to Verification.New, which sends the code. On success the handler returns 204.

Checking the verification code

POST http://localhost:8080/verify
Content-Type: application/json

{
  "phone_number": "+[COUNTRY_CODE][PHONE_NUMBER]",
  "code": "[VERIFICATION_CODE]"
}

code is the verification code received on the phone (4 to 8 digits).

func (s *server) verify(w http.ResponseWriter, r *http.Request) {
	var req struct {
		PhoneNumber string `json:"phone_number"`
		Code        string `json:"code"`
	}
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "invalid request body", http.StatusBadRequest)
		return
	}

	check, err := s.prelude.Verification.Check(r.Context(), prelude.VerificationCheckParams{
		Target: prelude.F(prelude.VerificationCheckParamsTarget{
			Type:  prelude.F(prelude.VerificationCheckParamsTargetTypePhoneNumber),
			Value: prelude.F(req.PhoneNumber),
		}),
		Code: prelude.F(req.Code),
	})
	if err != nil {
		http.Error(w, "could not check code", http.StatusBadGateway)
		return
	}

	if check.Status != prelude.VerificationCheckResponseStatusSuccess {
		http.Error(w, "verification failed", http.StatusUnauthorized)
		return
	}

	token, err := s.customToken(r.Context(), req.PhoneNumber)
	if err != nil {
		http.Error(w, "could not issue token", http.StatusInternalServerError)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	_ = json.NewEncoder(w).Encode(map[string]string{"token": token})
}

We pass the phone number and the code to Verification.Check. Only a Success status lets us mint a token; anything else means the code did not check out, and the client gets a 401.

Creating the Firebase user

At this point the phone number is verified, which is all Firebase needs to authenticate the user:

// customToken returns a Firebase custom token for phoneNumber, creating the
// user on first sign-in. A lookup failure that is not "no such user" is
// reported rather than mistaken for a missing user, which would create a
// duplicate.
func (s *server) customToken(ctx context.Context, phoneNumber string) (string, error) {
	user, err := s.auth.GetUserByPhoneNumber(ctx, phoneNumber)
	if firebaseauth.IsUserNotFound(err) {
		user, err = s.auth.CreateUser(ctx, (&firebaseauth.UserToCreate{}).PhoneNumber(phoneNumber))
	}
	if err != nil {
		return "", err
	}

	return s.auth.CustomToken(ctx, user.UID)
}

We look the user up by phone number, create them if there is none, and return a custom token for them. Your client then signs the user in with that token, through signInWithCustomToken or its equivalent in the Firebase SDK it uses.

Running it

go run .

# Send a code to the phone number. Responds 204.
curl -i -X POST localhost:8080/send_code \
  -d '{"phone_number": "+33xxxxxxxxx"}'

# Check the code and get a Firebase custom token back. Responds 200.
curl -i -X POST localhost:8080/verify \
  -d '{"phone_number": "+33xxxxxxxxx", "code": "12345678"}'
# {"token":"eyJhbGci..."}

Errors come back as a status code and a short message: 400 for a malformed body, 401 for a code that did not check out, 502 when the call to the Prelude API failed.

Conclusion

That is the whole integration. If you have questions about implementing Prelude, we’ll be happy to help at support@prelude.so.

Documentation

API Reference

Prelude API v2 and Firebase Auth integration

Prerequisites

Setting up the project

The server

Requesting a verification code

Checking the verification code

Creating the Firebase user

Running it

Conclusion

​Prerequisites

​Setting up the project

​The server

​Requesting a verification code

​Checking the verification code

​Creating the Firebase user

​Running it

​Conclusion

Prerequisites

Setting up the project

The server

Requesting a verification code

Checking the verification code

Creating the Firebase user

Running it

Conclusion