@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)
}

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
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
`skipNativeAuth`	`boolean`	Configure whether the plugin should skip the native authentication. Only needed if you want to use the Firebase JavaScript SDK. Only available for Android and iOS.	`false`
`providers`	`string[]`	Configure which providers you want to use so that only the providers you need are fully initialized. If you do not configure any providers, they will be all initialized. Please note that this does not prevent the automatic initialization of third-party SDKs. Only available for Android and iOS.	`["apple.com", "facebook.com", "github.com", "google.com", "microsoft.com", "playgames.google.com", "twitter.com", "yahoo.com", "phone"]`

Examples

In capacitor.config.json:

{
  "plugins": {
    "FirebaseAuthentication": {
      "skipNativeAuth": false,
      "providers": ["apple.com", "google.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", "google.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: 'mail@exmaple.com',
    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: 'mail@example.com',
  });
};

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: 'mail@example.com',
    password: '1234',
  });
  return result.user;
};

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: 'new.mail@example.com',
  });
};

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(...)
sendEmailVerification()
sendPasswordResetEmail(...)
setLanguageCode(...)
signInWithApple(...)
signInWithCustomToken(...)
signInWithEmailAndPassword(...)
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`

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>

confirmPasswordReset(...)

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

Completes the password reset process

Param	Type
`options`	`ConfirmPasswordResetOptions`

getCurrentUser()

getCurrentUser() => Promise<GetCurrentUserResult>

Fetches the currently signed-in user.

Returns: Promise<GetCurrentUserResult>

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>

sendEmailVerification()

sendEmailVerification() => Promise<void>

Sends a verification email to the currently signed in user.

sendPasswordResetEmail(...)

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

Sends a password reset email.

Param	Type
`options`	`SendPasswordResetEmailOptions`

setLanguageCode(...)

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

Sets the user-facing language code for auth operations.

Param	Type
`options`	`SetLanguageCodeOptions`

signInWithApple(...)

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

Starts the Apple sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

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>

signInWithEmailAndPassword(...)

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

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

Param	Type
`options`	`SignInWithEmailAndPasswordOptions`

Returns: Promise<SignInResult>

signInWithFacebook(...)

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

Starts the Facebook sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

signInWithGithub(...)

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

Starts the GitHub sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

signInWithGoogle(...)

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

Starts the Google sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

signInWithMicrosoft(...)

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

Starts the Microsoft sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

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>

signInWithPlayGames(...)

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

Starts the Play Games sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

signInWithTwitter(...)

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

Starts the Twitter sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

signInWithYahoo(...)

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

Starts the Yahoo sign-in flow.

Param	Type
`options`	`SignInOptions`

Returns: Promise<SignInResult>

signOut()

signOut() => Promise<void>

Starts the sign-out flow.

updateEmail(...)

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

Updates the email address of the currently signed in user.

Param	Type
`options`	`UpdateEmailOptions`

updatePassword(...)

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

Updates the password of the currently signed in user.

Param	Type
`options`	`UpdatePasswordOptions`

useAppLanguage()

useAppLanguage() => Promise<void>

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

useEmulator(...)

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

Instrument your app to talk to the Authentication emulator.

Param	Type
`options`	`UseEmulatorOptions`

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

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Interfaces

ApplyActionCodeOptions

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

SignInResult

Prop	Type	Description
`user`	`User \| null`	The currently signed-in user, or null if there isn't any.
`credential`	`AuthCredential \| null`	Credentials returned by an auth provider.

User

Prop	Type
`displayName`	`string \| null`
`email`	`string \| null`
`emailVerified`	`boolean`
`isAnonymous`	`boolean`
`phoneNumber`	`string \| null`
`photoUrl`	`string \| null`
`providerId`	`string`
`tenantId`	`string \| null`
`uid`	`string`

AuthCredential

Prop	Type	Description
`providerId`	`string`	The authentication provider ID for the credential. Example: `google.com`.
`accessToken`	`string`	The OAuth access token associated with the credential if it belongs to an OAuth provider.
`idToken`	`string`	The OAuth ID token associated with the credential if it belongs to an OIDC provider.
`secret`	`string`	The OAuth access token secret associated with the credential if it belongs to an OAuth 1.0 provider.
`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.

CreateUserWithEmailAndPasswordOptions

Prop	Type
`email`	`string`
`password`	`string`

ConfirmPasswordResetOptions

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

GetCurrentUserResult

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

GetIdTokenResult

Prop	Type	Description
`token`	`string`	The Firebase Auth ID token JWT string.

GetIdTokenOptions

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

SendPasswordResetEmailOptions

Prop	Type
`email`	`string`

SetLanguageCodeOptions

Prop	Type	Description
`languageCode`	`string`	BCP 47 language code. Example: `en-US`.

SignInOptions

Prop	Type	Description
`customParameters`	`SignInCustomParameter[]`	Configures custom parameters to be passed to the identity provider during the OAuth sign-in flow.

SignInCustomParameter

Prop	Type	Description
`key`	`string`	The custom parameter key (e.g. `login_hint`).
`value`	`string`	The custom parameter value (e.g. `user@firstadd.onmicrosoft.com`).

SignInWithCustomTokenOptions

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

SignInWithEmailAndPasswordOptions

Prop	Type	Description
`email`	`string`	The users email address.
`password`	`string`	The users password.

SignInWithPhoneNumberResult

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

SignInWithPhoneNumberOptions

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

UpdateEmailOptions

Prop	Type	Description
`newEmail`	`string`	The new email address.

UpdatePasswordOptions

Prop	Type	Description
`newPassword`	`string`	The new password.

UseEmulatorOptions

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

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

AuthStateChange

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

Type Aliases

AuthStateChangeListener

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

(change: AuthStateChange): void

FAQ

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.
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.
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).
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!

Files

README.md

Latest commit

History

README.md

File metadata and controls

@capacitor-firebase/authentication

Installation

Configuration

Examples

Demo

Usage

API

applyActionCode(...)

createUserWithEmailAndPassword(...)

confirmPasswordReset(...)

getCurrentUser()

getIdToken(...)

sendEmailVerification()

sendPasswordResetEmail(...)

setLanguageCode(...)

signInWithApple(...)

signInWithCustomToken(...)

signInWithEmailAndPassword(...)

signInWithFacebook(...)

signInWithGithub(...)

signInWithGoogle(...)

signInWithMicrosoft(...)

signInWithPhoneNumber(...)

signInWithPlayGames(...)

signInWithTwitter(...)

signInWithYahoo(...)

signOut()

updateEmail(...)

updatePassword(...)

useAppLanguage()

useEmulator(...)

addListener('authStateChange', ...)

removeAllListeners()

Interfaces

ApplyActionCodeOptions

SignInResult

User

AuthCredential

CreateUserWithEmailAndPasswordOptions

ConfirmPasswordResetOptions

GetCurrentUserResult

GetIdTokenResult

GetIdTokenOptions

SendPasswordResetEmailOptions

SetLanguageCodeOptions

SignInOptions

SignInCustomParameter

SignInWithCustomTokenOptions

SignInWithEmailAndPasswordOptions

SignInWithPhoneNumberResult

SignInWithPhoneNumberOptions

UpdateEmailOptions

UpdatePasswordOptions

UseEmulatorOptions

PluginListenerHandle

AuthStateChange

Type Aliases

AuthStateChangeListener

FAQ

Changelog

License

Credits