firebase::auth::PhoneAuthProvider

#include <credential.h>

Use phone number text messages to authenticate.

Summary

Allows developers to use the phone number and SMS verification codes to authenticate a user on a mobile device.

This class is not supported on tvOS and Desktop platforms.

The verification flow results in a Credential that can be used to,

  • Sign in to an existing phone number account/sign up with a new phone number
  • Link a phone number to a current user. This provider will be added to the user.
  • Update a phone number on an existing user.
  • Re-authenticate an existing user. This may be needed when a sensitive operation requires the user to be recently logged in.

Possible verification flows: (1) User manually enters verification code.

(2) SMS is automatically retrieved (Android only).

(3) Phone number is instantly verified (Android only).

All three flows can be handled with the example code below. The flow is complete when PhoneVerifier::credential() returns non-NULL.

class PhoneVerifier : public PhoneAuthProvider::Listener {
 public:
  PhoneVerifier(const char* phone_number,
                PhoneAuthProvider* phone_auth_provider)
    : display_message_("Sending SMS with verification code"),
      display_verification_code_input_box_(false),
      display_resend_sms_button_(false),
      phone_auth_provider_(phone_auth_provider),
      phone_number_(phone_number) {
    SendSms();
  }

  ~PhoneVerifier() override {}

  void OnVerificationCompleted(Credential credential) override {
    // Grab `mutex_` for the scope of `lock`. Callbacks can be called on
    // other threads, so this mutex ensures data access is atomic.
    MutexLock lock(mutex_);
    credential_ = credential;
  }

  void OnVerificationFailed(const std::string& error) override {
    MutexLock lock(mutex_);
    display_message_ = "Verification failed with error: " + error;
  }

  void OnCodeSent(const std::string& verification_id,
                  const PhoneAuthProvider::ForceResendingToken&
                      force_resending_token) override {
    MutexLock lock(mutex_);
    verification_id_ = verification_id;
    force_resending_token_ = force_resending_token;

    display_verification_code_input_box_ = true;
    display_message_ = "Waiting for SMS";
  }

  void OnCodeAutoRetrievalTimeOut(
      const std::string& verification_id) override {
    MutexLock lock(mutex_);
    display_resend_sms_button_ = true;
  }

  // Draw the verification GUI on screen and process input events.
  void Draw() {
    MutexLock lock(mutex_);

    // Draw an informative message describing what's currently happening.
    ShowTextBox(display_message_.c_str());

    // Once the time out expires, display a button to resend the SMS.
    // If the button is pressed, call VerifyPhoneNumber again using the
    // force_resending_token_.
    if (display_resend_sms_button_ && !verification_id_.empty()) {
      const bool resend_sms = ShowTextButton("Resend SMS");
      if (resend_sms) {
        SendSms();
      }
    }

    // Once the SMS has been sent, allow the user to enter the SMS
    // verification code into a text box. When the user has completed
    // entering it, call GetCredential() to complete the flow.
    if (display_verification_code_input_box_) {
      const std::string verification_code =
        ShowInputBox("Verification code");
      if (!verification_code.empty()) {
        credential_ = phone_auth_provider_->GetCredential(
            verification_id_.c_str(), verification_code.c_str());
      }
    }
  }

  // The phone number verification flow is complete when this returns
  // non-NULL.
  Credential* credential() {
    MutexLock lock(mutex_);
    return credential_.is_valid() ? &credential_ : nullptr;
  }

 private:
  void SendSms() {
    static const uint32_t kAutoVerifyTimeOut = 2000;
    MutexLock lock(mutex_);
    phone_auth_provider_->VerifyPhoneNumber(
        phone_number_.c_str(), kAutoVerifyTimeOut, &force_resending_token_,
        this);
    display_resend_sms_button_ = false;
  }

  // GUI-related variables.
  std::string display_message_;
  bool display_verification_code_input_box_;
  bool display_resend_sms_button_;

  // Phone flow related variables.
  PhoneAuthProvider* phone_auth_provider_;
  std::string phone_number_;
  std::string verification_id_;
  PhoneAuthProvider::ForceResendingToken force_resending_token_;
  Credential credential_;

  // Callbacks can be called on other threads, so guard them with a mutex.
  Mutex mutex_;
};

Public static attributes

kProviderId
const char *const
The string used to identify this provider.

Public functions

GetCredential(const char *verification_id, const char *verification_code)
Generate a credential for the given phone number.
GetCredential_DEPRECATED(const char *verification_id, const char *verification_code) Deprecated. This is a deprecated method. Please use GetCredential instead.
VerifyPhoneNumber(const char *phone_number, uint32_t auto_verify_time_out_ms, const ForceResendingToken *force_resending_token, Listener *listener)
void
Deprecated. This is a deprecated method. Please use VerifyPhoneNumber(const PhoneAuthOptions&, Listener*) instead.
VerifyPhoneNumber(const PhoneAuthOptions & options, PhoneAuthProvider::Listener *listener)
void
Start the phone number authentication operation.

Public static functions

GetInstance(Auth *auth)
Return the PhoneAuthProvider for the specified auth.

Classes

firebase::auth::PhoneAuthProvider::ForceResendingToken

Token to maintain current phone number verification session.

firebase::auth::PhoneAuthProvider::Listener

Receive callbacks from VerifyPhoneNumber events.

Public static attributes

kProviderId

const char *const kProviderId

The string used to identify this provider.

Public functions

GetCredential

PhoneAuthCredential GetCredential(
  const char *verification_id,
  const char *verification_code
)

Generate a credential for the given phone number.

Details
Parameters
verification_id
The id returned when sending the verification code. Sent to the caller via Listener::OnCodeSent.
verification_code
The verification code supplied by the user, most likely by a GUI where the user manually enters the code received in the SMS sent by VerifyPhoneNumber.
Returns

GetCredential_DEPRECATED

Credential GetCredential_DEPRECATED(
  const char *verification_id,
  const char *verification_code
)

Deprecated. This is a deprecated method. Please use GetCredential instead.

Generate a credential for the given phone number.

Details
Parameters
verification_id
The id returned when sending the verification code. Sent to the caller via Listener::OnCodeSent.
verification_code
The verification code supplied by the user, most likely by a GUI where the user manually enters the code received in the SMS sent by VerifyPhoneNumber.
Returns

VerifyPhoneNumber

void VerifyPhoneNumber(
  const char *phone_number,
  uint32_t auto_verify_time_out_ms,
  const ForceResendingToken *force_resending_token,
  Listener *listener
)

Deprecated. This is a deprecated method. Please use VerifyPhoneNumber(const PhoneAuthOptions&, Listener*) instead.

Start the phone number authentication operation.

Details
Parameters
phone_number
The phone number identifier supplied by the user. Its format is normalized on the server, so it can be in any format here.
auto_verify_time_out_ms
The time out for SMS auto retrieval, in miliseconds. Currently SMS auto retrieval is only supported on Android. If 0, do not do SMS auto retrieval. If positive, try to auto-retrieve the SMS verification code. When the time out is exceeded, listener->OnCodeAutoRetrievalTimeOut() is called.
force_resending_token
If NULL, assume this is a new phone number to verify. If not-NULL, bypass the verification session deduping and force resending a new SMS. This token is received in Listener::OnCodeSent. This should only be used when the user presses a Resend SMS button.
listener
Class that receives notification whenever an SMS verification event occurs. See sample code at top of class.

VerifyPhoneNumber

void VerifyPhoneNumber(
  const PhoneAuthOptions & options,
  PhoneAuthProvider::Listener *listener
)

Start the phone number authentication operation.

Details
Parameters
options
The PhoneAuthOptions struct with a verification configuration.
listener
Class that receives notification whenever an SMS verification event occurs.

Public static functions

GetInstance

PhoneAuthProvider & GetInstance(
  Auth *auth
)

Return the PhoneAuthProvider for the specified auth.

Details
Parameters
auth
The Auth session for which we want to get a PhoneAuthProvider.