Expo Auth Session is a foundational module within the Expo ecosystem for implementing web browser-based authentication flows, such as OAuth 2.0 and OpenID Connect, across Android, iOS, and web platforms. It provides a unified API to manage the complexities of these authentication methods, leveraging `expo-web-browser` for browser interaction and `expo-crypto` for secure operations like Proof Key for Code Exchange (PKCE), which is now the recommended grant type over implicit flow due to enhanced security. The current stable version is 55.0.15, with releases typically synchronized with major Expo SDK updates, occurring approximately three times per year. Key differentiators include its seamless integration with Expo development builds and managed workflow capabilities, simplifying the setup of deep linking and redirect URIs across various environments, and providing hooks like `useAuthRequest` for easy React component integration.
npm install expo-auth-sessionVerified import paths — ran on the pinned version, not inferred.
This example demonstrates a basic GitHub OAuth login flow using the `useAuthRequest` hook and `makeRedirectUri`. It showcases how to initiate the authentication process, handle success and error responses, and securely retrieve an authorization code for backend exchange. It also includes the necessary `WebBrowser.maybeCompleteAuthSession()` call for web compatibility and deep linking setup for native platforms.
Migrate to using direct deep links and universal links. Configure your OAuth provider with your app's custom scheme and/or universal link domain. Use `makeRedirectUri({ useProxy: false, scheme: 'your-app-scheme' })` or omit `useProxy` entirely. [13]For robust development and production, use an Expo Development Build (custom dev client) or a standalone app. These allow you to define and use your app's specific deep linking scheme or universal link domain. [4, 5]
Always verify the exact redirect URI generated by `makeRedirectUri()` in your console logs during development. Add this precise URI to your OAuth provider's 'Authorized redirect URIs' list. For native apps, ensure your `app.json` scheme matches. [14]
Implement a backend API endpoint to handle the authorization code exchange for an access token. Send the authorization code received from `expo-auth-session` to your backend, where the secret is securely stored and used. Your client app then receives the access token from your backend. [4]
Add `WebBrowser.maybeCompleteAuthSession();` at the top level of your application (e.g., `App.tsx` or `_layout.tsx` for Expo Router) to ensure it's called early enough to dismiss any lingering authentication sessions. [4]
Double-check the redirect URI generated by `AuthSession.makeRedirectUri()` in your app's logs and ensure it is precisely added to the 'Authorized redirect URIs' list in your OAuth provider's settings (e.g., Google Cloud Console, GitHub OAuth App settings). Ensure your app's scheme in `app.json` is correctly set and matches for native builds.
Remove `useProxy: true` from your `makeRedirectUri` options and configure direct deep linking/universal links with your OAuth provider. If forced to use an older SDK and proxy, ensure your project's full name (`@owner/slug`) is provided to `projectNameForProxy`. [23]
Ensure your app's scheme is correctly defined in `app.json` and in your native project configurations. Test with a custom Expo Development Build or standalone app, rather than Expo Go, as it provides more control over deep linking. Verify `WebBrowser.maybeCompleteAuthSession()` is called.
While user cancellation is expected, if it happens unexpectedly, review redirect URI configurations, network connectivity, and ensure deep linking is correctly set up. For iOS, ensure `WebBrowser.maybeCompleteAuthSession()` is active and prompt for permissions is clear.