@chipmobilesdk/rn-auth

Reusable Microsoft Entra External ID authentication for ChipMobileSdk-family React Native apps. The library is a public OAuth2/OIDC client (Authorization Code + PKCE, no backend, no client secret). Android presents Continue with Google, iOS presents Continue with Apple, and either platform can also present Continue with Facebook; all start the same External ID sign-up/sign-in user flow, routed to the right social provider with a domain_hint. Google, Apple, and Facebook are federated inside the External ID tenant, so the app embeds no native social SDK and no Sign in with Apple entitlement. Each platform renders all of its configured providers as separate buttons in configuration order.

License: UNLICENSED. Published publicly for use by the owner's applications; no open-source license is granted.

• Version: 0.2.0

• Entrypoint: @chipmobilesdk/rn-auth

• Single active account, session restore, local + global sign-out.

• Per-resource delegated access tokens for Azure resources.

• Group/role/claim access-tier evaluation that fails closed.

• Tokens persist only in platform secure storage (Keychain / Keystore).

• No i18n runtime dependency: user-facing copy is stable keys + English defaults.

Install (consuming app)

npm install @chipmobilesdk/rn-auth react-native-app-auth react-native-keychain
cd ios && pod install

react, react-native, react-native-app-auth, and react-native-keychain are peer dependencies. The two native libraries are only required by the default adapters — an app injecting custom ports may omit them.

See native setup for the iOS Info.plist URL scheme and the Android appAuthRedirectScheme Gradle placeholder.

Quick start

import {
  AuthProvider,
  createAuth,
  createAppAuthClient,
  createKeychainSecureStore,
  useAuth,
  useSignInProvider,
} from '@chipmobilesdk/rn-auth';

const auth = createAuth({
  authority: 'https://<tenant>.ciamlogin.com/<tenant>.onmicrosoft.com',
  clientId: '<public-client-id>',
  redirectUrl: 'com.yourapp://oauthredirect',
  scopes: ['openid', 'profile', 'offline_access'],
  providers: [
    { id: 'google', platforms: ['android'], domainHint: 'google.com', labelKey: 'auth.action.continueGoogle' },
    { id: 'apple', platforms: ['ios'], domainHint: 'apple.com', labelKey: 'auth.action.continueApple' },
    // Optional third provider, shown on both platforms after the platform-native one:
    { id: 'facebook', platforms: ['ios', 'android'], domainHint: 'facebook.com', labelKey: 'auth.action.continueFacebook' },
  ],
  resources: [{ key: 'storage', scopes: ['https://storage.azure.com/user_impersonation'] }],
  accessTierMapping: { premiumGroupObjectIds: ['<premium-group-object-id>'] },
  secureStore: createKeychainSecureStore(),
  authClient: createAppAuthClient(),
});

export const App = () => (
  <AuthProvider auth={auth}>
    <Screen />
  </AuthProvider>
);

Hooks: useAuth() (state + signIn/signOut/signOutGlobal/restore/requirePremium), useProfile(), useAccessTier(), useAccessToken(resourceKey), useSignInProviders() (all platform providers, in config order — map to one button each) and useSignInProvider() (first available, for a single-button UI).

Configuration contract (LIB-010)

The library accepts public values only. Provider secrets, Apple keys, and client secrets are configured in the External ID tenant, never in the app (FR-017).

| Section | Keys | |---------|------| | A — Tenant / client | authority, clientId, redirectUrl, scopes (include offline_access) | | B — Android Google | providers[google]: domainHint, platforms: ['android'], labelKey | | C — iOS Apple | providers[apple]: domainHint, platforms: ['ios'], labelKey | | C2 — Facebook (optional) | providers[facebook]: domainHint: 'facebook.com', platforms: ['ios','android'], labelKey: 'auth.action.continueFacebook', optional available | | D — Resources | resources[].key, resources[].scopes, resources[].displayName? | | E — Access tier | accessTierMapping.premiumGroupObjectIds (+ optional role names / claim matchers; display names are diagnostics-only) | | F — Ports | secureStore (required), authClient (optional), messages (optional copy override) |

Full contract: auth-config.md and public-api.md.

Tenant / provider prerequisite checklist (LIB-018)

These are external prerequisites (FR-013/FR-018) completed before the library can sign users in:

External ID tenant

• [ ] Customer (CIAM) tenant created; sign-up/sign-in user flow configured.
• [ ] App registration created as a public client; redirect URI added (must match the native scheme, e.g. com.yourapp://oauthredirect).
• [ ] API permissions / scopes for each target Azure resource consented.
• [ ] Premium group(s) created; record the group object id (not the name).
• [ ] Groups (or roles) emitted in the token; plan for groups overage.

Google (federated in the tenant)

• [ ] Google Cloud OAuth client configured; client id/secret stored in the tenant IdP config (never in the app).
• [ ] Google added as an identity provider in the External ID user flow.

Apple (federated in the tenant)

• [ ] Apple Services ID + Sign in with Apple key configured; stored in the tenant IdP config.
• [ ] Apple added as an identity provider in the External ID user flow.
• [ ] Note: Apple sign-in operational credentials expire on a schedule and must be rotated tenant-side.

Facebook (federated in the tenant — optional)

• [ ] Facebook app created in Meta for Developers; App ID + App Secret stored in the tenant IdP config (never in the app).
• [ ] Facebook added as an identity provider in the External ID user flow; domain_hint confirmed (expected facebook.com).
• [ ] Facebook app OAuth redirect / valid OAuth domains match the tenant federation redirect.
• [ ] iOS: because Facebook is a third-party login, keep Sign in with Apple offered on iOS (Apple guideline 4.8).
• [ ] Update Apple App Privacy and Google Play Data Safety to include Facebook as an identity provider before release.

Security & privacy

• Tokens and refresh artifacts persist only in SecureTokenStore (Keychain / Keystore). Access tokens are kept in memory only.
• Access-tier decisions prefer stable group object ids; display names never grant access; missing/overage claims fail closed.
• Diagnostics (AuthError) never contain secrets or token values.
• Authentication and profile data are collected and transmitted to the identity providers and configured Azure resources — update Apple App Privacy and Google Play Data Safety before release.

Public API

Everything below is exported from @chipmobilesdk/rn-auth; deep imports into config/, core/, tokens/, oidc/, access/, diagnostics/, or react/ are unsupported.

• Controller and configuration: createAuth, Auth, AuthConfig, CreateAuthOptions, AuthState, AuthStatus, RestoreStatus
• Identity and access: Profile, ProviderConfig, ProviderIdentity, ResourceConfig, AccessTier, AccessTierMapping, AccessTokenResult, PremiumGateResult, evaluateAccessTier, failClosedTier
• Ports and default adapters: SecureTokenStore, createKeychainSecureStore, AUTH_STORAGE_KEY, OidcAuthClient, createAppAuthClient and the public OIDC request/token types
• React: AuthProvider, useAuth, useProfile, useAccessTier, useAccessToken, useSignInProvider, useSignInProviders
• Diagnostics and copy: AuthError, AuthConfigError, isAuthError, redact, DEFAULT_MESSAGES, resolveMessages and their public code/message types

Compatibility and validation

React ≥19 · React Native ≥0.85 · react-native-app-auth ≥8 · react-native-keychain ≥10 · iOS + Android · Node ≥22.11 for tooling.

The demo integration lives in src/screens/AuthDemoScreen.tsx. Run from the repository root:

npm run typecheck:auth
npm run pack:auth
npm run validate:auth

Distribution and license

Published as a public npm package (publishConfig.access: public) for use by the owner's applications. License: UNLICENSED; no open-source license is granted.