AuthSession

Platform Compatibility

Installation

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

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage in standalone apps

{
  "expo": {
    "scheme": "mycoolredirect"
  }
}

Guides

The guides have moved: Authentication Guide.

How web browser based authentication flows work

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

What auth.expo.io does for you

The auth.expo.io proxy is only used when startAsync is called, or when useProxy: true is passed to the promptAsync() method of an AuthRequest.

It reduces boilerplate

• It opens the sign in URL for your authentication provider (authUrl, you must provide it) in a web browser that shares cookies with your system browser.
• It handles success redirects and extracts all of the data encoded in the URL.
• It handles failures and provides information to you about what went wrong.

It makes redirect URL allowlists easier to manage for development and working in teams

Security considerations

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, { useProxy: true });

// 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:19000/--/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:19000
// Web dev: https://localhost:19006
// Web prod: https://yourwebsite.com

const redirectUri3 = makeRedirectUri({
  useProxy: true,
});
// Development Build: https://auth.expo.io/@username/slug
// Expo Go: https://auth.expo.io/@username/slug
// Web dev: https://localhost:19006
// Web prod: https://yourwebsite.com

Interfaces

Types

Enums

Providers

Google

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 ['openid', 'https://www.googleapis.com/auth/userinfo.profile', 'https://www.googleapis.com/auth/userinfo.email'] for optimal usage with services like Firebase and Auth0.
• By default, the authorization code will be automatically exchanged for an access token. This can be overridden with shouldAutoExchangeCode.
• Automatically uses the proxy in Expo Go because native auth is not supported due to custom build time configuration. This can be overridden with redirectUriOptions.useProxy.
• 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()

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 makeRedirectUriAsync()).

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. This should not be used to enable the Expo proxy service auth.expo.io, as the proxy will be automatically enabled based on the platform.

discovery

Facebook

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.
• Automatically uses the proxy in Expo Go because native auth is not supported due to custom build time configuration.
• The URI redirect must be added to your app.config.js or app.json as facebookScheme: 'fb<YOUR FBID>'.
• Disables PKCE for implicit auth response.
• On web, the popup is presented with the dimensions { width: 700, height: 600 }

useAuthRequest()

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 makeRedirectUriAsync()).

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

Usage in the bare React Native app

Proxy Service

• redirecting traffic from your application to the authentication service
• redirecting response from the auth service to your application using a deep link

const http = require('http');
const url = require('url');

const PORT = PORT;
const DEEP_LINK = DEEP_LINK_TO_YOUR_APPLICATION;

const redirect = (response, url) => {
  response.writeHead(302, {
    Location: url,
  });
  response.end();
};

http
  .createServer((request, response) => {
    // get parameters from request
    const parameters = url.parse(request.url, true).query;

    // if parameters contain authServiceUrl, this request comes from the application
    if (parameters.authServiceUrl) {
      // redirect user to the authUrl
      redirect(response, decodeURIComponent(parameters.authServiceUrl));
      return;
    }

    // redirect response from the auth service to your application
    redirect(response, DEEP_LINK);
  })
  .listen(PORT);

const authServiceUrl = encodeURIComponent(YOUR_AUTH_URL); // we encode this, because it will be send as a query parameter
const authServiceUrlParameter = `authServiceUrl=${authServiceUrl}`;
const authUrl = `YOUR_PROXY_SERVICE_URL?${authServiceUrlParameter}`;
const result = await AuthSession.startAsync({
  authUrl,
  returnUrl: YOUR_DEEP_LINK,
});

Advanced usage

Filtering out AuthSession events in Linking handlers

With React Navigation v5