Expo AuthSession

A universal library that provides an API to handle browser-based authentication.

AuthSession enables web browser-based authentication (for example, browser-based OAuth flows) in your app by utilizing WebBrowser and Crypto. For implementation details, refer to this reference, and for usage, see the Authentication guide.

Installation

expo-crypto is a peer dependency and must be installed alongside expo-auth-session.

If you are installing this in an existing React Native app, start by installing expo in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.

Usage in standalone apps

{
  "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.

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 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), 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

import * as AuthSession from 'expo-auth-session';

Hooks

const [request, response, promptAsync] = useAuthRequest({ ... }, { ... });

const discovery = useAutoDiscovery('https://example.com/auth');

Classes

// Create a request.
const request = new AuthRequest({ ... });

// Prompt for an auth code
const result = await request.promptAsync(discovery);

// Get the URL to invoke
const url = await request.makeAuthUrlAsync(discovery);

// Get the URL to invoke
const parsed = await request.parseReturnUrlAsync("<URL From Server>");

Methods

const url = AuthSession.getRedirectUrl('redirect');

// Managed: https://auth.expo.io/@your-username/your-app-slug/redirect
// Web: https://localhost:19006/redirect

const redirectUri = makeRedirectUri({
  scheme: 'my-scheme',
  path: 'redirect'
});
// Development Build: my-scheme://redirect
// Expo Go: exp://127.0.0.1:8081/--/redirect
// Web dev: https://localhost:19006/redirect
// Web prod: https://yourwebsite.com/redirect

const redirectUri2 = makeRedirectUri({
  scheme: 'scheme2',
  preferLocalhost: true,
  isTripleSlashed: true,
});
// Development Build: scheme2:///
// Expo Go: exp://localhost:8081
// Web dev: https://localhost:19006
// Web prod: https://yourwebsite.com

Interfaces

Types

Enums

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

Deprecated: This provider is deprecated and will be removed in a future SDK version. See Google authentication instead.

import * as Google from 'expo-auth-session/providers/google';

• See the guide for more info on usage: Google Authentication.

• 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.

  ['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 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 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 object with options about how the prompt will execute.

discovery

A DiscoveryDocument object containing the discovery URLs used for Google auth.

Facebook

Deprecated: This provider is deprecated and will be removed in a future SDK version. See Facebook authentication instead.

import * as Facebook from 'expo-auth-session/providers/facebook';

• Uses implicit auth (ResponseType.Token) by default.
• See the guide for more info on usage: Facebook Authentication.
• 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 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 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 object with options about how the prompt will execute.

discovery

A 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); 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. 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.