diff --git a/A0Auth0.podspec b/A0Auth0.podspec index bf37d2a3..d9571722 100644 --- a/A0Auth0.podspec +++ b/A0Auth0.podspec @@ -16,7 +16,7 @@ Pod::Spec.new do |s| s.source_files = 'ios/**/*.{h,m,mm,swift}' s.requires_arc = true - s.dependency 'Auth0', '2.16.1' + s.dependency 'Auth0', '2.16.2' install_modules_dependencies(s) end diff --git a/EXAMPLES.md b/EXAMPLES.md index 62a11e86..a789e7c3 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -13,6 +13,13 @@ - [Set global headers during initialization](#set-global-headers-during-initialization) - [Using custom headers with Auth0Provider component](#using-custom-headers-with-auth0provider-component) - [Set request-specific headers](#set-request-specific-headers) +- [Credential Renewal Retry](#credential-renewal-retry) + - [Overview](#credential-renewal-retry-overview) + - [Prerequisites](#credential-renewal-retry-prerequisites) + - [Using Retry with Hooks](#using-retry-with-hooks) + - [Using Retry with Auth0 Class](#using-retry-with-auth0-class) + - [Platform Support](#credential-renewal-retry-platform-support) + - [Error Handling](#credential-renewal-retry-error-handling) - [Biometric Authentication](#biometric-authentication) - [Biometric Policy Types](#biometric-policy-types) - [Using with Auth0Provider (Hooks)](#using-with-auth0provider-hooks) @@ -259,6 +266,194 @@ auth0.auth .catch(console.error); ``` +## Credential Renewal Retry + +> **Platform Support:** iOS only. + +Automatic retry mechanism for credential renewal to improve reliability in unstable network conditions, particularly important for mobile applications with refresh token rotation enabled. + + + +### Overview + +When your application operates on unstable mobile networks, credential renewal requests may fail due to transient network issues. The `maxRetries` configuration option enables automatic retry with exponential backoff for the following error scenarios: + +- **Network errors**: Connection timeouts, DNS failures, unreachable hosts +- **Rate limiting**: HTTP 429 (Too Many Requests) +- **Server errors**: HTTP 5xx responses + +> **Important:** While the retry mechanism is particularly valuable for refresh token rotation (RRT) scenarios, it can be used to improve credential renewal reliability in any configuration, including non-RRT deployments. The retry logic helps handle transient network failures regardless of your token rotation strategy. + +**Example scenario with Refresh Token Rotation:** + +1. Request A calls `getCredentials()` and starts a token refresh +2. Request A successfully hits the server and gets new credentials +3. Request A fails on the way back (network issue), never reaching the client +4. The retry mechanism automatically retries the failed request using the same (old) refresh token +5. The retry succeeds within the refresh token rotation overlap window + +> **Critical for RRT:** If you have refresh token rotation enabled, you **must** configure a token overlap period of at least **180 seconds (3 minutes)** in your Auth0 tenant. This overlap window allows retries to succeed using the old refresh token before it expires, preventing users from being locked out due to network failures. + + + +### Prerequisites + +To use the retry mechanism: + +1. **SDK Version**: Requires react-native-auth0 v5.4.0 or later +2. **Scope**: Ensure your authentication requests include the `offline_access` scope to receive refresh tokens + +**Additional requirements for Refresh Token Rotation:** + +If you have refresh token rotation enabled in your Auth0 tenant: + +1. **Token Overlap Period**: Configure an overlap period of at least **180 seconds (3 minutes)** in your Auth0 tenant settings. This is **critical** to ensure retries can succeed using the old refresh token before it expires. + + + +### Using Retry with Hooks + +```jsx +import React from 'react'; +import { View, Button, Alert } from 'react-native'; +import { Auth0Provider, useAuth0 } from 'react-native-auth0'; + +function App() { + return ( + + + + ); +} + +function MyComponent() { + const { getCredentials } = useAuth0(); + + const fetchCredentialsWithRetry = async () => { + try { + // The retry mechanism is automatically applied to all credential renewal attempts + const credentials = await getCredentials(); + + console.log('Access Token:', credentials.accessToken); + // Use credentials for API calls... + } catch (error) { + console.error('Failed to get credentials after retries:', error); + Alert.alert( + 'Error', + 'Unable to refresh credentials. Please log in again.' + ); + } + }; + + return ( + +