react-native-nitro-auth

Google Sign-In, Apple Sign-In, and Microsoft Entra ID for React Native and Expo, powered by Nitro Modules.

Use it when you want one typed authentication API for native social login, web OAuth, token refresh, incremental scopes, account listeners, and consistent AuthError handling. Native refresh tokens stay in memory. Web session metadata uses configurable browser storage, with token persistence disabled by default. Your backend remains responsible for validating tokens and creating application sessions.

Install

bun add react-native-nitro-auth react-native-nitro-modules

For Expo development builds:

bunx expo install react-native-nitro-auth react-native-nitro-modules
bunx expo prebuild

For bare React Native apps:

cd ios && pod install

Expo Go cannot load Nitro native modules. Use an Expo development build or a bare app.

Requirements

| Dependency | Supported range or validated baseline | | ---------------------------- | ------------------------------------- | | React Native | >=0.75.0; validated with 0.86.2 | | React | Validated with 19.2.3 | | React Native Nitro Modules | >=0.36.4 <0.37.0 | | Expo | Development builds; validated with 57 | | iOS | 16.4 or later |

Expo Config

Add the plugin to app.json or app.config.js before prebuild:

export default {
  expo: {
    scheme: "myapp",
    ios: {
      bundleIdentifier: "com.company.myapp",
    },
    android: {
      package: "com.company.myapp",
    },
    plugins: [
      [
        "react-native-nitro-auth",
        {
          ios: {
            googleClientId: process.env.GOOGLE_IOS_CLIENT_ID,
            googleServerClientId: process.env.GOOGLE_SERVER_CLIENT_ID,
            googleUrlScheme: process.env.GOOGLE_IOS_URL_SCHEME,
            appleSignIn: true,
            microsoftClientId: process.env.MICROSOFT_CLIENT_ID,
            microsoftTenant: process.env.MICROSOFT_TENANT,
            microsoftB2cDomain: process.env.MICROSOFT_B2C_DOMAIN,
          },
          android: {
            googleClientId: process.env.GOOGLE_WEB_CLIENT_ID,
            microsoftClientId: process.env.MICROSOFT_CLIENT_ID,
            microsoftTenant: process.env.MICROSOFT_TENANT,
            microsoftB2cDomain: process.env.MICROSOFT_B2C_DOMAIN,
          },
        },
      ],
    ],
    extra: {
      googleWebClientId: process.env.GOOGLE_WEB_CLIENT_ID,
      appleWebClientId: process.env.APPLE_WEB_CLIENT_ID,
      microsoftClientId: process.env.MICROSOFT_CLIENT_ID,
      microsoftTenant: process.env.MICROSOFT_TENANT,
      microsoftB2cDomain: process.env.MICROSOFT_B2C_DOMAIN,
      nitroAuthWebStorage: "session",
    },
  },
};

Plugin options:

| Option | Platform | Required for | | ---------------------------- | -------- | -------------------------------- | | ios.googleClientId | iOS | Google Sign-In on iOS. | | ios.googleServerClientId | iOS | Google server auth code flow. | | ios.googleUrlScheme | iOS | Google redirect URL scheme. | | ios.appleSignIn | iOS | Apple Sign-In entitlement. | | ios.microsoftClientId | iOS | Microsoft Entra ID native login. | | ios.microsoftTenant | iOS | Microsoft tenant override. | | ios.microsoftB2cDomain | iOS | Microsoft B2C hostname. | | android.googleClientId | Android | Google Sign-In on Android. | | android.microsoftClientId | Android | Microsoft Entra ID native login. | | android.microsoftTenant | Android | Microsoft tenant override. | | android.microsoftB2cDomain | Android | Microsoft B2C hostname. |

Web reads provider client IDs from expo.extra; native platforms read values written by the plugin during prebuild.

Web options in expo.extra:

| Option | Default | Purpose | | ----------------------------- | ----------- | -------------------------------------------- | | googleWebClientId | — | Google OAuth client ID. | | appleWebClientId | — | Apple Services ID. | | microsoftClientId | — | Microsoft Entra ID application ID. | | microsoftTenant | common | Microsoft tenant, domain, or B2C policy. | | microsoftB2cDomain | — | Microsoft B2C hostname. | | nitroAuthWebStorage | session | session, local, or memory. | | nitroAuthPersistTokensOnWeb | false | Persist token fields in configured storage. |

On iOS, the plugin also applies the CocoaPods modular-header settings required by the Google Sign-In dependency chain (AppCheckCore, GoogleUtilities, and RecaptchaInterop). Expo apps should not add those pods manually through expo-build-properties.

Microsoft tenant values are validated before opening the authorization URL. Use common, organizations, consumers, a tenant ID, or a tenant domain for standard Entra ID. For B2C, set microsoftB2cDomain to a hostname such as contoso.b2clogin.com and set microsoftTenant to a policy such as B2C_1_signin. For custom B2C domains, set microsoftTenant to a tenant/policy path such as contoso.onmicrosoft.com/B2C_1_signin.

Quick Start

import { Button } from "react-native";
import {
  useAuth,
  type ProviderLoginOptions,
} from "react-native-nitro-auth";

export function SignInButton() {
  const { user, login, logout } = useAuth();

  async function signInWithGoogle() {
    const options: ProviderLoginOptions<"google"> = {
      scopes: ["openid", "profile", "email"],
    };

    await login("google", options);
  }

  if (user) {
    return <Button title="Sign out" onPress={logout} />;
  }

  return <Button title="Continue with Google" onPress={signInWithGoogle} />;
}

Imperative callers can use the same provider-aware options:

import { AuthService } from "react-native-nitro-auth";

async function signInWithMicrosoft() {
  await AuthService.login("microsoft", {
    tenant: "organizations",
    prompt: "select_account",
  });
}

Providers

| Provider | Native | Web | Notes | | --------- | ------------ | --- | --------------------------------------------------------------------- | | Google | iOS, Android | Yes | Supports account picker, login hint, refresh, and incremental scopes. | | Apple | iOS | Yes | Returns name and email only on first authorization. | | Microsoft | iOS, Android | Yes | Supports tenant, B2C, refresh, and incremental scopes. |

Apple Sign-In is unavailable on Android. Use expo-auth-session, react-native-app-auth, Auth0, Firebase Auth, or your identity provider SDK when you need generic OAuth/OIDC providers, password authentication, MFA, hosted user management, or server session management.

API

Main exports:

• useAuth() for reactive user, scope, loading, and error state.
• AuthService for imperative operations and account listeners.
• SocialButton for provider-aware UI.
• AuthProvider for "google", "apple", and "microsoft".
• AuthError and AuthErrorCode for deterministic failures.
• Provider-specific option types for strongly typed login calls.

Both useAuth().login() and AuthService.login() reject option fields that do not belong to the selected provider:

import type {
  ProviderLoginOptions,
  MicrosoftLoginOptions,
} from "react-native-nitro-auth";

const googleOptions: ProviderLoginOptions<"google"> = {
  scopes: ["openid", "email"],
  hostedDomain: "company.com",
  forceAccountPicker: true,
};

const microsoftOptions: MicrosoftLoginOptions = {
  tenant: "organizations",
  prompt: "select_account",
};

Supported login options:

| Provider | Options | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Google | scopes, loginHint, nonce, forceAccountPicker, hostedDomain, useSheet, openIDRealm, useOneTap, filterByAuthorizedAccounts, useLegacyGoogleSignIn, forceCodeForRefreshToken, requestVerifiedPhoneNumber | | Apple | scopes, nonce | | Microsoft | scopes, loginHint, tenant, prompt |

prompt is typed as "login", "consent", "select_account", or "none".

Session operations

• logout() clears package session state and signs out provider SDK state where available. It does not revoke a provider grant or your backend session.
• silentRestore() resolves with or without a restorable session. It rejects configuration, network, and parse failures instead of treating them as a missing session.
• requestScopes() supports Google and Microsoft and may require user interaction.
• revokeScopes() removes scopes from package state; it does not revoke them at the provider.
• getAccessToken() returns the current access token and refreshes near-expiry Google or Microsoft credentials when supported.
• refreshToken() supports Google and Microsoft. Apple token exchange and refresh belong on your backend.
• revokeAccess() clears local state only after provider revocation succeeds. Client-side revocation supports Google web and iOS sessions, plus Android sessions created through legacy Google Sign-In. Unsupported providers and modern Android Google sessions reject with unsupported_provider.

Storage and Security

Native token fields, including Microsoft refresh tokens, are held in memory by this package. Provider SDKs may retain their own sign-in state, which silentRestore() can use. Persist only the minimum application session data you need, preferably in platform secure storage or on your backend.

On web, user metadata and scopes use sessionStorage by default. Choose local, session, or memory with nitroAuthWebStorage. Token fields and the Microsoft refresh token remain in memory unless nitroAuthPersistTokensOnWeb is explicitly enabled. Enabling it places those credentials in the configured storage and changes your XSS risk profile.

JWT decoding in this package is for display and routing only. Validate token signatures, issuer, audience, nonce, and expiry on your server before creating an application session.

Error Contract

AuthService operations and useAuth() mutations throw AuthError with name, stable code, message, and optional underlyingMessage. message equals code; underlyingMessage preserves a differing raw platform message.

import {
  AuthError,
  AuthService,
  type AuthErrorCode,
} from "react-native-nitro-auth";

async function signIn(
  reportFailure: (code: AuthErrorCode, detail: string | undefined) => void,
) {
  try {
    await AuthService.login("google");
  } catch (error) {
    if (error instanceof AuthError) {
      if (error.code === "cancelled") return;
      reportFailure(error.code, error.underlyingMessage);
      return;
    }
    throw error;
  }
}

Error codes are cancelled, timeout, popup_blocked, network_error, configuration_error, not_signed_in, operation_in_progress, unsupported_provider, invalid_state, invalid_nonce, token_error, no_id_token, parse_error, refresh_failed, and unknown.

Platform Support

| Platform | Status | | -------- | ----------------------------------------------------------- | | iOS | Google, Apple, Microsoft native flows. | | Android | Google and Microsoft native flows. | | Web | Google, Apple, and Microsoft OAuth through Expo web config. | | Expo | Development builds with the config plugin. |

Validated baseline: Expo SDK 57, React Native 0.86.2, React 19.2.3, and Nitro Modules 0.36.4. Package peer range: >=0.36.4 <0.37.0.

Troubleshooting

• Expo Go error: build a dev client; Expo Go cannot load Nitro modules.
• Provider not configured: verify plugin values, expo.extra, and that you prebuilt after changing config.
• Apple profile missing name/email: Apple only sends those fields on the first authorization.
• Microsoft redirect mismatch: confirm bundle ID, Android package, microsoftClientId, and tenant/B2C settings match the provider console.

Development

bun install
bun run check
bun run release:preflight
bun run example:android
bun run example:ios

Run native example builds before release when changing plugin, native, Nitro, or packaging files.

Links

• npm package
• GitHub repository
• Issue tracker
• Changelog

License

MIT