@capacitor-firebase/authentication

@capacitor-firebase/authentication

⚡️ Capacitor plugin for Firebase Authentication.

Installation

npm install @capacitor-firebase/authentication firebase
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

On iOS, verify that this function is included in your app's AppDelegate.swift:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
  return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}

Attention: If you use this plugin on iOS in combination with @capacitor-firebase/messaging, then add the following to your app's AppDelegate.swift:

+ import FirebaseAuth

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+    if Auth.auth().canHandle(url) {
+      return true
+    }
    return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}

The further installation steps depend on the selected authentication method:

• Apple Sign-In
• Facebook Sign-In
• GitHub Sign-In
• Google Sign-In
• Microsoft Sign-In
• Play Games Sign-In
• Twitter Sign-In
• Yahoo Sign-In
• Phone Number Sign-In
• Email Link Sign-In
• Custom Token Sign-In

Attention: Please note that this plugin uses third-party SDKs to offer native sign-in. These SDKs can initialize on their own and collect various data. Here you can find more information.

Configuration

These configuration values are available:

Prop	Type	Description	Default	Since
skipNativeAuth	boolean	Configure whether the plugin should skip the native authentication. Only needed if you want to use the Firebase JavaScript SDK. Note that the plugin may behave differently across the platforms. Only available for Android and iOS.	false	0.1.0
providers	string[]	Configure the providers that should be loaded by the plugin. Possible values: ["apple.com", "facebook.com", "github.com", "google.com", "microsoft.com", "playgames.google.com", "twitter.com", "yahoo.com", "phone"] Only available for Android and iOS.	[]	0.1.0

Examples

In capacitor.config.json:

{
  "plugins": {
    "FirebaseAuthentication": {
      "skipNativeAuth": false,
      "providers": ["apple.com", "facebook.com"]
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor/firebase-authentication" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseAuthentication: {
      skipNativeAuth: false,
      providers: ["apple.com", "facebook.com"],
    },
  },
};

export default config;

Demo

A working example can be found here: robingenz/capacitor-firebase-authentication-demo

Usage

import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const applyActionCode = async () => {
  await FirebaseAuthentication.applyActionCode({ oobCode: '1234' });
};

const createUserWithEmailAndPassword = async () => {
  const result = await FirebaseAuthentication.createUserWithEmailAndPassword({
    email: '[e-mail]',
    password: '1234',
  });
  return result.user;
};

const confirmPasswordReset = async () => {
  await FirebaseAuthentication.confirmPasswordReset({
    oobCode: '1234',
    newPassword: '4321',
  });
};

const getCurrentUser = async () => {
  const result = await FirebaseAuthentication.getCurrentUser();
  return result.user;
};

const getIdToken = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  const result = await FirebaseAuthentication.getIdToken();
  return result.token;
};

const sendEmailVerification = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.sendEmailVerification();
};

const sendPasswordResetEmail = async () => {
  await FirebaseAuthentication.sendPasswordResetEmail({
    email: '[e-mail]',
  });
};

const sendSignInLinkToEmail = async () => {
  const email = '[e-mail]';
  await FirebaseAuthentication.sendSignInLinkToEmail({
    email,
    actionCodeSettings: {
      // URL you want to redirect back to. The domain (www.example.com) for this
      // URL must be in the authorized domains list in the Firebase Console.
      url: 'https://www.example.com/finishSignUp?cartId=1234',
      // This must be true.
      handleCodeInApp: true,
      iOS: {
        bundleId: 'com.example.ios',
      },
      android: {
        packageName: 'com.example.android',
        installApp: true,
        minimumVersion: '12',
      },
      dynamicLinkDomain: 'example.page.link',
    }
  });
  // The link was successfully sent. Inform the user.
  // Save the email locally so you don't need to ask the user for it again
  // if they open the link on the same device.
  window.localStorage.setItem('emailForSignIn', email);
};

const setLanguageCode = async () => {
  await FirebaseAuthentication.setLanguageCode({ languageCode: 'en-US' });
};

const signInWithApple = async () => {
  const result = await FirebaseAuthentication.signInWithApple();
  return result.user;
};

const signInWithCustomToken = async () => {
  const result = await FirebaseAuthentication.signInWithCustomToken({
    token: '1234',
  });
  return result.user;
};

const signInWithEmailAndPassword = async () => {
  const result = await FirebaseAuthentication.signInWithEmailAndPassword({
    email: '[e-mail]',
    password: '1234',
  });
  return result.user;
};

const signInWithEmailLink = async () => {
  // Get the email if available. This should be available if the user completes
  // the flow on the same device where they started it.
  const emailLink = window.location.href;
  // Confirm the link is a sign-in with email link.
  const result = await FirebaseAuthentication.isSignInWithEmailLink({
    emailLink,
  });
  if (
    result.isSignInWithEmailLink
  ) {
    let email = window.localStorage.getItem('emailForSignIn');
    if (!email) {
      // User opened the link on a different device. To prevent session fixation
      // attacks, ask the user to provide the associated email again.
      email = window.prompt(
        'Please provide your email for confirmation.',
      );
    }
    // The client SDK will parse the code from the link for you.
    const result = await FirebaseAuthentication.signInWithEmailLink({
      email,
      emailLink,
    });
    // Clear email from storage.
    window.localStorage.removeItem('emailForSignIn');
    return result.user;
  } else {
    alert('emailLink is invalid.');
  }
};

const signInWithFacebook = async () => {
  const result = await FirebaseAuthentication.signInWithFacebook();
  return result.user;
};

const signInWithGithub = async () => {
  const result = await FirebaseAuthentication.signInWithGithub();
  return result.user;
};

const signInWithGoogle = async () => {
  const result = await FirebaseAuthentication.signInWithGoogle();
  return result.user;
};

const signInWithMicrosoft = async () => {
  const result = await FirebaseAuthentication.signInWithMicrosoft();
  return result.user;
};

const signInWithPlayGames = async () => {
  const result = await FirebaseAuthentication.signInWithPlayGames();
  return result.user;
};

const signInWithPhoneNumber = async () => {
  const { verificationId } = await FirebaseAuthentication.signInWithPhoneNumber(
    {
      phoneNumber: '123456789',
    },
  );
  const verificationCode = window.prompt(
    'Please enter the verification code that was sent to your mobile device.',
  );
  const result = await FirebaseAuthentication.signInWithPhoneNumber({
    verificationId,
    verificationCode,
  });
  return result.user;
};

const signInWithTwitter = async () => {
  const result = await FirebaseAuthentication.signInWithTwitter();
  return result.user;
};

const signInWithYahoo = async () => {
  const result = await FirebaseAuthentication.signInWithYahoo();
  return result.user;
};

const signOut = async () => {
  await FirebaseAuthentication.signOut();
};

const updateEmail = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.updateEmail({
    newEmail: '[e-mail]',
  });
};

const updatePassword = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.updatePassword({
    newPassword: '4321',
  });
};

const useAppLanguage = async () => {
  await FirebaseAuthentication.useAppLanguage();
};

const useEmulator = async () => {
  await FirebaseAuthentication.useEmulator({
    host: '10.0.2.2',
    port: 9099,
  });
};

API

• applyActionCode(...)
• createUserWithEmailAndPassword(...)
• confirmPasswordReset(...)
• getCurrentUser()
• getIdToken(...)
• isSignInWithEmailLink(...)
• sendEmailVerification()
• sendPasswordResetEmail(...)
• sendSignInLinkToEmail(...)
• setLanguageCode(...)
• signInWithApple(...)
• signInWithCustomToken(...)
• signInWithEmailAndPassword(...)
• signInWithEmailLink(...)
• signInWithFacebook(...)
• signInWithGithub(...)
• signInWithGoogle(...)
• signInWithMicrosoft(...)
• signInWithPhoneNumber(...)
• signInWithPlayGames(...)
• signInWithTwitter(...)
• signInWithYahoo(...)
• signOut()
• updateEmail(...)
• updatePassword(...)
• useAppLanguage()
• useEmulator(...)
• addListener('authStateChange', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

applyActionCode(...)

applyActionCode(options: ApplyActionCodeOptions) => Promise<void>

Applies a verification code sent to the user by email.

Param	Type
options	ApplyActionCodeOptions

Since: 0.2.2

---

createUserWithEmailAndPassword(...)

createUserWithEmailAndPassword(options: CreateUserWithEmailAndPasswordOptions) => Promise<SignInResult>

Creates a new user account with email and password. If the new account was created, the user is signed in automatically.

Param	Type
options	CreateUserWithEmailAndPasswordOptions

Returns: Promise<SignInResult>

Since: 0.2.2

---

confirmPasswordReset(...)

confirmPasswordReset(options: ConfirmPasswordResetOptions) => Promise<void>

Completes the password reset process.

Param	Type
options	ConfirmPasswordResetOptions

Since: 0.2.2

---

getCurrentUser()

getCurrentUser() => Promise<GetCurrentUserResult>

Fetches the currently signed-in user.

Returns: Promise<GetCurrentUserResult>

Since: 0.1.0

---

getIdToken(...)

getIdToken(options?: GetIdTokenOptions | undefined) => Promise<GetIdTokenResult>

Fetches the Firebase Auth ID Token for the currently signed-in user.

Param	Type
options	GetIdTokenOptions

Returns: Promise<GetIdTokenResult>

Since: 0.1.0

---

isSignInWithEmailLink(...)

isSignInWithEmailLink(options: IsSignInWithEmailLinkOptions) => Promise<IsSignInWithEmailLinkResult>

Checks if an incoming link is a sign-in with email link suitable for signInWithEmailLink.

Param	Type
options	IsSignInWithEmailLinkOptions

Returns: Promise<IsSignInWithEmailLinkResult>

Since: 1.1.0

---

sendEmailVerification()

sendEmailVerification() => Promise<void>

Sends a verification email to the currently signed in user.

Since: 0.2.2

---

sendPasswordResetEmail(...)

sendPasswordResetEmail(options: SendPasswordResetEmailOptions) => Promise<void>

Sends a password reset email.

Param	Type
options	SendPasswordResetEmailOptions

Since: 0.2.2

---

sendSignInLinkToEmail(...)

sendSignInLinkToEmail(options: SendSignInLinkToEmailOptions) => Promise<void>

Sends a sign-in email link to the user with the specified email.

To complete sign in with the email link, call signInWithEmailLink with the email address and the email link supplied in the email sent to the user.

Param	Type
options	SendSignInLinkToEmailOptions

Since: 1.1.0

---

setLanguageCode(...)

setLanguageCode(options: SetLanguageCodeOptions) => Promise<void>

Sets the user-facing language code for auth operations.

Param	Type
options	SetLanguageCodeOptions

Since: 0.1.0

---

signInWithApple(...)

signInWithApple(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the Apple sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithCustomToken(...)

signInWithCustomToken(options: SignInWithCustomTokenOptions) => Promise<SignInResult>

Starts the Custom Token sign-in flow.

This method cannot be used in combination with skipNativeAuth on Android and iOS. In this case you have to use the signInWithCustomToken interface of the Firebase JS SDK directly.

Param	Type
options	SignInWithCustomTokenOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithEmailAndPassword(...)

signInWithEmailAndPassword(options: SignInWithEmailAndPasswordOptions) => Promise<SignInResult>

Starts the sign-in flow using an email and password.

Param	Type
options	SignInWithEmailAndPasswordOptions

Returns: Promise<SignInResult>

Since: 0.2.2

---

signInWithEmailLink(...)

signInWithEmailLink(options: SignInWithEmailLinkOptions) => Promise<SignInResult>

Signs in using an email and sign-in email link.

Param	Type
options	SignInWithEmailLinkOptions

Returns: Promise<SignInResult>

Since: 1.1.0

---

signInWithFacebook(...)

signInWithFacebook(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the Facebook sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithGithub(...)

signInWithGithub(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the GitHub sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithGoogle(...)

signInWithGoogle(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the Google sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithMicrosoft(...)

signInWithMicrosoft(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the Microsoft sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithPhoneNumber(...)

signInWithPhoneNumber(options: SignInWithPhoneNumberOptions) => Promise<SignInWithPhoneNumberResult>

Starts the sign-in flow using a phone number.

Either the phone number or the verification code and verification ID must be provided.

Only available for Android and iOS.

Param	Type
options	SignInWithPhoneNumberOptions

Returns: Promise<SignInWithPhoneNumberResult>

Since: 0.1.0

---

signInWithPlayGames(...)

signInWithPlayGames(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the Play Games sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithTwitter(...)

signInWithTwitter(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the Twitter sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signInWithYahoo(...)

signInWithYahoo(options?: SignInOptions | undefined) => Promise<SignInResult>

Starts the Yahoo sign-in flow.

Param	Type
options	SignInOptions

Returns: Promise<SignInResult>

Since: 0.1.0

---

signOut()

signOut() => Promise<void>

Starts the sign-out flow.

Since: 0.1.0

---

updateEmail(...)

updateEmail(options: UpdateEmailOptions) => Promise<void>

Updates the email address of the currently signed in user.

Param	Type
options	UpdateEmailOptions

Since: 0.1.0

---

updatePassword(...)

updatePassword(options: UpdatePasswordOptions) => Promise<void>

Updates the password of the currently signed in user.

Param	Type
options	UpdatePasswordOptions

Since: 0.1.0

---

useAppLanguage()

useAppLanguage() => Promise<void>

Sets the user-facing language code to be the default app language.

Since: 0.1.0

---

useEmulator(...)

useEmulator(options: UseEmulatorOptions) => Promise<void>

Instrument your app to talk to the Authentication emulator.

Param	Type
options	UseEmulatorOptions

Since: 0.2.0

---

addListener('authStateChange', ...)

addListener(eventName: 'authStateChange', listenerFunc: AuthStateChangeListener) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for the user's sign-in state changes.

Param	Type
eventName	'authStateChange'
listenerFunc	AuthStateChangeListener

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 0.1.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

---

Interfaces

ApplyActionCodeOptions

Prop	Type	Description	Since
oobCode	string	A verification code sent to the user.	0.2.2

SignInResult

Prop	Type	Description	Since
user	User | null	The currently signed-in user, or null if there isn't any.	0.1.0
credential	AuthCredential | null	Credentials returned by an auth provider.	0.1.0
additionalUserInfo	AdditionalUserInfo | null	Additional user information from a federated identity provider.	0.5.1

User

Prop	Type	Since
displayName	string | null	0.1.0
email	string | null	0.1.0
emailVerified	boolean	0.1.0
isAnonymous	boolean	0.1.0
phoneNumber	string | null	0.1.0
photoUrl	string | null	0.1.0
providerId	string	0.1.0
tenantId	string | null	0.1.0
uid	string	0.1.0

AuthCredential

Prop	Type	Description	Since
providerId	string	The authentication provider ID for the credential.	0.1.0
accessToken	string	The OAuth access token associated with the credential if it belongs to an OAuth provider.	0.1.0
idToken	string	The OAuth ID token associated with the credential if it belongs to an OIDC provider.	0.1.0
secret	string	The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider.	0.1.0
nonce	string	The random string used to make sure that the ID token you get was granted specifically in response to your app's authentication request.	0.1.0

AdditionalUserInfo

Prop	Type	Description	Since
isNewUser	boolean	Whether the user is new (sign-up) or existing (sign-in).	0.5.1
profile	{ [key: string]: unknown; }	Map containing IDP-specific user data.	0.5.1
providerId	string	Identifier for the provider used to authenticate this user.	0.5.1
username	string	The username if the provider is GitHub or Twitter.	0.5.1

CreateUserWithEmailAndPasswordOptions

Prop	Type	Since
email	string	0.2.2
password	string	0.2.2

ConfirmPasswordResetOptions

Prop	Type	Description	Since
oobCode	string	A verification code sent to the user.	0.2.2
newPassword	string	The new password.	0.2.2

GetCurrentUserResult

Prop	Type	Description	Since
user	User | null	The currently signed-in user, or null if there isn't any.	0.1.0

GetIdTokenResult

Prop	Type	Description	Since
token	string	The Firebase Auth ID token JWT string.	0.1.0

GetIdTokenOptions

Prop	Type	Description	Since
forceRefresh	boolean	Force refresh regardless of token expiration.	0.1.0

IsSignInWithEmailLinkResult

Prop	Type	Description
isSignInWithEmailLink	boolean	Whether an incoming link is a signup with email link suitable for signInWithEmailLink(...).

IsSignInWithEmailLinkOptions

Prop	Type	Description	Since
emailLink	string	The link sent to the user's email address.	1.1.0

SendPasswordResetEmailOptions

Prop	Type	Since
email	string	0.2.2

SendSignInLinkToEmailOptions

Prop	Type	Description	Since
email	string	The user's email address.	1.1.0
actionCodeSettings	ActionCodeSettings	Structure that contains the required continue/state URL with optional Android and iOS bundle identifiers.	1.1.0

ActionCodeSettings

An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers.

Prop	Type	Description
android	{ installApp?: boolean; minimumVersion?: string; packageName: string; }	Sets the Android package name.
handleCodeInApp	boolean	When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed.
iOS	{ bundleId: string; }	Sets the iOS bundle ID.
url	string	Sets the link continue/state URL.
dynamicLinkDomain	string	When multiple custom dynamic link domains are defined for a project, specify which one to use when the link is to be opened via a specified mobile app (for example, example.page.link).

SetLanguageCodeOptions

Prop	Type	Description	Since
languageCode	string	BCP 47 language code.	0.1.0

SignInOptions

Prop	Type	Description	Since
customParameters	SignInCustomParameter[]	Configures custom parameters to be passed to the identity provider during the OAuth sign-in flow.	0.1.0
scopes	string[]	Scopes to request from provider.	0.3.1

SignInCustomParameter

Prop	Type	Description	Since
key	string	The custom parameter key (e.g. login_hint).	0.1.0
value	string	The custom parameter value (e.g. [e-mail]).	0.1.0

SignInWithCustomTokenOptions

Prop	Type	Description	Since
token	string	The custom token to sign in with.	0.1.0

SignInWithEmailAndPasswordOptions

Prop	Type	Description	Since
email	string	The users email address.	0.2.2
password	string	The users password.	0.2.2

SignInWithEmailLinkOptions

Prop	Type	Description	Since
email	string	The user's email address.	1.1.0
emailLink	string	The link sent to the user's email address.	1.1.0

SignInWithPhoneNumberResult

Prop	Type	Description	Since
verificationId	string	The verification ID, which is needed to identify the verification code.	0.1.0

SignInWithPhoneNumberOptions

Prop	Type	Description	Since
phoneNumber	string	The phone number to be verified.	0.1.0
verificationId	string	The verification ID which will be returned when signInWithPhoneNumber is called for the first time. The verificationCode must also be provided.	0.1.0
verificationCode	string	The verification code from the SMS message. The verificationId must also be provided.	0.1.0

UpdateEmailOptions

Prop	Type	Description	Since
newEmail	string	The new email address.	0.2.2

UpdatePasswordOptions

Prop	Type	Description	Since
newPassword	string	The new password.	0.2.2

UseEmulatorOptions

Prop	Type	Description	Default	Since
host	string	The emulator host (e.g. 10.0.2.2).		0.2.0
port	number	The emulator port (e.g. 9099).	9099	0.2.0

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

AuthStateChange

Prop	Type	Description	Since
user	User | null	The currently signed-in user, or null if there isn't any.	0.1.0

Type Aliases

AuthStateChangeListener

Callback to receive the user's sign-in state change notifications.

(change: AuthStateChange): void

FAQ

1. What does this plugin do?
   This plugin enables the use of Firebase Authentication in a Capacitor app. It uses the Firebase SDK for Java (Android), Swift (iOS) and JavaScript.
2. What is the difference between the web implementation of this plugin and the Firebase JS SDK?
   The web implementation of this plugin encapsulates the Firebase JS SDK and enables a consistent interface across all platforms. You can decide if you prefer to use the web implementation or the Firebase JS SDK.
3. What is the difference between the native and web authentication?
   For web authentication, the Firebase JS SDK is used. This only works to a limited extent on Android and iOS in the WebViews (see here). For native authentication, the native SDKs from Firebase, Google, etc. are used. These offer all the functionalities that the Firebase JS SDK also offers on the web. However, after a login with the native SDK, the user is only logged in on the native layer of the app. If the user should also be logged in on the web layer, additional steps are required (see here).
4. How can I use this plugin with the Firebase JavaScript SDK?
   See here.

Changelog

See CHANGELOG.md.

License

See LICENSE.

Credits

This plugin is based on the Capacitor Firebase Authentication plugin. Thanks to everyone who contributed to the project!