Expo Docs MCP Server

--- title: AuthSession description: A universal library that provides an API to handle browser-based authentication. sourceCodeUrl: https://github.com/expo/expo/tree/sdk-51/packages/expo-auth-session packageName: expo-auth-session platforms: ["android", "ios", "web"] --- `AuthSession` enables web browser-based authentication (for example, browser-based OAuth flows) in your app by utilizing [WebBrowser](webbrowser.md) and [Crypto](crypto.md). For implementation details, refer to this reference, and for usage, see the [Authentication](/guides/authentication/) guide. ## Installation > `expo-crypto` is a peer dependency and must be installed alongside `expo-auth-session`. ## Configuration To use this library, you need to set up deep linking in your app by setting up a `scheme`. Use the [`uri-scheme` CLI][n-uri-scheme] utility to easily add, remove, list, and open your URIs. For example, to make your native app handle `mycoolredirect://`, run: You should now be able to see a list of all your project's schemes by running: You can test it to ensure it works like this: ### Usage in standalone apps ```json app.json { "expo": { "scheme": "mycoolredirect" } } ``` To be able to deep link back into your app, you will need to set a `scheme` in your project **app.config.js**, or **app.json**, and then build your standalone app (it can't be updated with an update). If you do not include a scheme, the authentication flow will complete, but it will be unable to pass the information back into your application and the user will have to manually exit the authentication modal (resulting in a canceled event). ## Guides > The guides have moved: [Authentication Guide](/guides/authentication/). ## How web browser based authentication flows work The typical flow for browser-based authentication in mobile apps is as follows: - **Initiation**: the user presses a sign in button - **Open web browser**: the app opens up a web browser to the authentication provider sign in page. The url that is opened for the sign in page usually includes information to identify the app, and a URL to redirect to on success. _Note: the web browser should share cookies with your system web browser so that users do not need to sign in again if they are already authenticated on the system browser -- Expo's [WebBrowser](webbrowser.md) API takes care of this._ - **Authentication provider redirects**: upon successful authentication, the authentication provider should redirect back to the application by redirecting to URL provided by the app in the query parameters on the sign in page ([read more about how linking works in mobile apps](/linking/overview/)), _provided that the URL is in the allowlist of allowed redirect URLs_. Allowlisting redirect URLs is important to prevent malicious actors from pretending to be your application. The redirect includes data in the URL (such as user id and token), either in the location hash, query parameters, or both. - **App handles redirect**: the redirect is handled by the app and data is parsed from the redirect URL. ## Security considerations - **Never put any secret keys inside your application code, there is no secure way to do this!** Instead, you should store your secret key(s) on a server and expose an endpoint that makes API calls for your client and passes the data back. ## API ```js ``` ## Providers AuthSession has built-in support for some popular providers to make usage as easy as possible. These allow you to skip repetitive things like defining endpoints and abstract common features like `language`. ## Google > **warning** **Deprecated:** This provider is deprecated and will be removed in a future SDK version. See [Google authentication](/guides/google-authentication/) instead. ```jsx ``` - Provides an extra `loginHint` parameter. If the user's email address is known ahead of time, it can be supplied to be the default option. - Enforces minimum scopes to the following APIs for optimal usage with services like Firebase and Auth0. ```text ['openid', 'https://www.googleapis.com/auth/userinfo.profile', 'https://www.googleapis.com/auth/userinfo.email'] ``` - By default, the authorization `code` will be automatically exchanged for an access token. This can be overridden with `shouldAutoExchangeCode`. - Defaults to using the bundle ID and package name for the native URI redirect instead of the reverse client ID. - Disables PKCE for implicit and id-token based auth responses. - On web, the popup is presented with the dimensions that are optimized for the Google login UI (`{ width: 515, height: 680 }`). ### `useAuthRequest()` A hook used for opinionated Google authentication that works across platforms. #### Arguments - **config (`GoogleAuthRequestConfig`)** - A [`GoogleAuthRequestConfig`](#googleauthrequestconfig) object with client IDs for each platform that should be supported. - **redirectUriOptions (`AuthSessionRedirectUriOptions`)** - Optional properties used to construct the redirect URI (passed to `makeRedirectUri()`). #### Returns - **request (`GoogleAuthRequest | null`)** - An instance of [`GoogleAuthRequest`](#googleauthrequest) that can be used to prompt the user for authorization. This will be `null` until the auth request has finished loading. - **response (`AuthSessionResult | null`)** - This is `null` until `promptAsync` has been invoked. Once fulfilled it will return information about the authorization. - **promptAsync (`function`)** - When invoked, a web browser will open up and prompt the user for authentication. Accepts an [`AuthRequestPromptOptions`](#authrequestpromptoptions) object with options about how the prompt will execute. ### `discovery` A [`DiscoveryDocument`](#discoverydocument) object containing the discovery URLs used for Google auth. ## Facebook > **warning** **Deprecated:** This provider is deprecated and will be removed in a future SDK version. See [Facebook authentication](/guides/facebook-authentication/) instead. ```jsx ``` - Uses implicit auth (`ResponseType.Token`) by default. - Enforces minimum scopes to `['public_profile', 'email']` for optimal usage with services like Firebase and Auth0. - Uses `display=popup` for better UI results. - Disables PKCE for implicit auth response. - On web, the popup is presented with the dimensions `{ width: 700, height: 600 }` ### `useAuthRequest()` A hook used for opinionated Facebook authentication that works across platforms. #### Arguments - **config (`FacebookAuthRequestConfig`)** - A [`FacebookAuthRequestConfig`](#facebookauthrequestconfig) object with client IDs for each platform that should be supported. - **redirectUriOptions (`AuthSessionRedirectUriOptions`)** - Optional properties used to construct the redirect URI (passed to `makeRedirectUri()`). #### Returns - **request (`FacebookAuthRequest | null`)** - An instance of [`FacebookAuthRequest`](#facebookauthrequest) that can be used to prompt the user for authorization. This will be `null` until the auth request has finished loading. - **response (`AuthSessionResult | null`)** - This is `null` until `promptAsync` has been invoked. Once fulfilled it will return information about the authorization. - **promptAsync (`function`)** - When invoked, a web browser will open up and prompt the user for authentication. Accepts an [`AuthRequestPromptOptions`](#authrequestpromptoptions) object with options about how the prompt will execute. ### `discovery` A [`DiscoveryDocument`](#discoverydocument) object containing the discovery URLs used for Facebook auth. ## Advanced usage ### Filtering out AuthSession events in Linking handlers There are many reasons why you might want to handle inbound links into your app, such as push notifications or just regular deep linking (you can read more about this in the [Linking guide](/linking/overview/)); authentication redirects are only one type of deep link, and `AuthSession` handles these particular links for you. In your own `Linking.addEventListener` handlers, you can filter out deep links that are handled by `AuthSession` by checking if the URL includes the `+expo-auth-session` string -- if it does, you can ignore it. This works because `AuthSession` adds `+expo-auth-session` to the default `returnUrl`; however, if you provide your own `returnUrl`, you may want to consider adding a similar identifier to enable you to filter out `AuthSession` events from other handlers. ### With React Navigation If you are using deep linking with React Navigation, filtering through `Linking.addEventListener` will not be sufficient because deep linking is [handled differently](https://reactnavigation.org/docs/configuring-links/#advanced-cases). Instead, to filter these events, add a custom `getStateFromPath` function to your linking configuration, and then filter by URL in the same way as described above. [n-uri-scheme]: https://www.npmjs.com/package/uri-scheme