--- title: Customizing Journey module storage in React Native description: Configure the @ping-identity/rn-storage package to customize token storage for session, OIDC, binding, push, and OATH data in React Native apps component: orchsdks page_id: orchsdks:journey:customization/storage/customize-react-native-storage canonical_url: https://developer.pingidentity.com/orchsdks/journey/customization/storage/customize-react-native-storage.html llms_txt: https://developer.pingidentity.com/orchsdks/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Journeys", "React Native", "Storage", "Tokens", "Session", "OIDC", "Keychain", "Keystore"] section_ids: installing_the_storage_module: Installing the storage module configuring_storage: Configuring storage configuring_storage_options: Configuring storage options android_storage_options: Android storage options cache-strategy: Configuring cache strategy on Android ios_storage_options: iOS storage options configuring_oath_storage_options_on_ios: Configuring OATH storage options on iOS error_handling: Error handling --- # Customizing Journey module storage in React Native [icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: react, set=fab]React Native Depending on the authentication use case, your application may need to store SSO session tokens, OAuth 2.0 access tokens, refresh tokens, or ID tokens. The Orchestration SDK for React Native uses encrypted native storage on both Android and iOS by default, following identity best practices for each platform. For most applications, no additional configuration is required. If you need to control specific aspects of how tokens are stored — such as the encryption key alias, the storage file name, or the caching behaviour — you can supply a custom storage configuration by using the `@ping-identity/rn-storage` package. ## Installing the storage module The storage module is provided as a separate package. Install it alongside `@ping-identity/rn-journey`: * yarn * npm ```shell yarn add @ping-identity/rn-storage ``` ```shell npm install @ping-identity/rn-storage ``` After installation, run `pod install` in your `ios/` directory to link the native dependencies on iOS: ```shell cd ios && pod install ``` ## Configuring storage The storage module exposes helpers for the different types of storage that various modules in the Orchestration SDKs use: * `configureSessionStorage()` Registers a storage configuration for SSO session tokens. Used by the **rn-journey** module. * `configureOidcStorage()` Registers a storage configuration for OAuth 2.0 access, refresh, and ID tokens. Used by the **rn-oidc** and **rn-journey** modules. * `configureBindingUserKeyStorage()` Registers a storage configuration for binding user key metadata. Used by the **rn-binding** module. * `configurePushStorage()` Registers a storage configuration for push MFA notification credentials. Used by the **rn-push** module. * `configureOathStorage()` Registers a storage configuration for OATH one-time password credentials. Used by the **rn-oath** module. Specify the handle of the create storage instances when configuring the various clients. For example, you could pass handles for both session and OIDC token storage in the config for your journey client, as follows: Configuring session and OIDC storage for the Journey client ```typescript import { createJourneyClient } from '@ping-identity/rn-journey'; import { configureSessionStorage, configureOidcStorage, } from '@ping-identity/rn-storage'; const sessionStorage = configureSessionStorage({ android: { keyAlias: 'com.example.app.session', fileName: 'ping_session_store', }, ios: { account: 'com.example.app.session', }, }); const oidcStorage = configureOidcStorage({ android: { keyAlias: 'com.example.app.oidc', fileName: 'ping_oidc_tokens', }, ios: { account: 'com.example.app.oidc', encryptor: true, }, }); const journeyClient = createJourneyClient({ serverUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am', realm: 'alpha', cookie: 'ch15fefc5407912', modules: { session: { storage: sessionStorage }, oidc: { storage: oidcStorage }, }, }); ``` ### Configuring storage options All helpers accept a `StorageConfig` object with platform-specific options nested under `android` or `ios` elements. Options under each key are applied only on that platform and ignored on the other. #### Android storage options Android storage is backed by the encrypted [Jetpack DataStore](https://developer.android.com/topic/libraries/architecture/datastore) and uses the Android Keystore system. | Property | Default | Description | | -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `keyAlias` | `'com.pingidentity.rnstorage.storage'` | Alias used to identify the encryption key in the Android Keystore.You can use any value that does not clash with any other key names. A common pattern is `...KEYS`.For example, `com.example.v1.KEYS`. | | `fileName` | `'secure_prefs'` | Name of the file where persistent data is stored.Use a distinct name for each storage instance to avoid data conflicts. | | `strongBoxPreferred` | `false` | When `true`, the SDK attempts to use hardware-backed [StrongBox](https://developer.android.com/privacy-and-security/keystore#StrongBoxKeyMint) for the encryption key.Falls back to the standard Keystore if StrongBox is not available on the device. | | `cacheStrategy` | `CacheStrategy.NO_CACHE` | Controls in-memory caching of storage reads.See [Configuring cache strategy on Android](#cache-strategy). | ##### Configuring cache strategy on Android The `cacheStrategy` option controls how the Android storage layer handles in-memory caching. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Data held in a cache is kept in plain text and is not encrypted.A device that can output a memory dump may expose sensitive information, such as access or ID tokens. | | Value | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CacheStrategy.NO_CACHE` | Default. No in-memory caching. All reads and writes go directly to persistent encrypted storage. Use for sensitive data that must not remain in memory. | | `CacheStrategy.CACHE_ON_FAILURE` | Caches data in memory only when a storage operation fails. Provides a fallback for transient storage interruptions. | | `CacheStrategy.CACHE` | Always caches data in memory. Reduces disk I/O for frequently accessed data. | Enabling cache-on-failure for session storage ```typescript import { configureSessionStorage, CacheStrategy } from '@ping-identity/rn-storage'; const sessionStorage = configureSessionStorage({ android: { keyAlias: 'com.example.app.session', fileName: 'ping_session_store', cacheStrategy: CacheStrategy.CACHE_ON_FAILURE, }, }); ``` #### iOS storage options iOS storage is backed by the device Keychain. | Property | Default | Description | | ----------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account` | `'com.pingidentity.rnstorage.storage'` | Keychain account name used to group items in the Keychain.Typically uses reverse domain notation, for example `com.example.app.session`. | | `encryptor` | `true` | When `true`, the SDK applies an additional encryption layer on top of the Keychain's native encryption.Set to `false` to rely on Keychain encryption only. | | `cacheable` | Platform default | Controls whether the SDK falls back to an in-memory cache when Keychain access is unavailable. | ##### Configuring OATH storage options on iOS `configureOathStorage()` accepts an additional `iosOath` element for iOS-specific OATH credential security options. These are separate from the common `ios` options and are ignored on Android. | Property | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------- | | `service` | Keychain service name used to identify and group OATH credentials in the Keychain. | | `requireBiometrics` | When `true`, requires biometric authentication (Face ID or Touch ID) to access OATH credentials. | | `requireDevicePasscode` | When `true`, requires the device passcode to access OATH credentials. | | `biometricPrompt` | Custom prompt text displayed in the biometric authentication dialog when accessing OATH credentials. | | `accessGroup` | Keychain access group identifier for sharing OATH credentials across app extensions. | ## Error handling Both `configureSessionStorage()` and `configureOidcStorage()` throw a `StorageError` if the configuration is invalid or if native storage registration fails. `StorageError` extends `PingError`, which in turn extends `Error`, and includes a `code` and `type` property for programmatic handling. Handling storage configuration errors ```typescript import { configureSessionStorage, StorageError } from '@ping-identity/rn-storage'; try { const sessionStorage = configureSessionStorage({ android: { keyAlias: 'com.example.app.session', fileName: 'ping_session_store', }, }); } catch (err) { if (err instanceof StorageError) { console.error(err.code, err.type, err.message); } } ```