GuidesAPI ReferenceChangelogHelp
Guides

Native and Mobile Apps

This section covers additional requirements and implementation details specific to native desktop and mobile applications. See Authorization Code Flow for general information.

Redirect Approaches

Native apps may take different approaches for redirecting the user back to the application. In all cases, the app developer will need to register the desired redirect URIs with FamilySearch — see API Key Management.

Register Custom Protocol Handler

Some modern operating systems support a mechanism for registering a custom protocol handler which can be used to open up a specific native application while passing parameters to the app. This approach is supported very well on iOS and Android operating systems and is the recommended approach for handling OAuth 2.0 redirects for mobile applications.

When using a custom protocol handler, the redirect URI will look something like this:

com.your-domain.your-app://familysearch-auth

Please note that some platforms recommend using a reverse domain name convention to ensure uniqueness.

Potential Advantages: The user is seamlessly redirected back to the native app, resulting in a better user experience.

Potential Challenges: This approach can be more difficult for desktop apps, where the operating system may launch a new process and require interprocess communication to pass the authorization code back to the original process. Windows, Mac, and Linux all handle registering protocol handlers in different ways.

Listen on Loopback Port

Another approach involves opening up a network handler on the loopback address and listening on a specific port. The native app acts as a very simple web server running on the local machine. When the user is directed to the redirect URI, the browser passes the needed parameters in the query string, and the native app completes the token exchange and responds with a page prompting the user to return to the app.

When using the loopback approach, your redirect URI will look something like this:

IP v4: http://127.0.0.1:57938/familysearch-auth
IP v6: http://[::1]:57938/familysearch-auth

Potential Advantages: This is the simplest way to capture the redirect with a desktop application. There is no need for complex interprocess messaging.

Potential Challenges: Users can potentially get lost getting back to your application. It is important to give clear instruction on your response page that guides the user back to your application. Some desktop firewall software has been known to block listening on local ports.

Listen with a Server

If you have the capability to run a secure web service, you can use it to handle the redirect:

  1. Native app establishes a session with secure web service
  2. User is sent to the Authorization URL in browser
  3. User completes Authorization flow
  4. User is redirected to secure web service
  5. User closes browser window and returns to app
  6. Native app retrieves token from server based upon established session
https://example.com/familysearch-auth

Potential Advantages: This is a reliable and secure option for handling the redirect.

Potential Challenges: This approach introduces additional infrastructure and technology to manage.

Redirect URIs

Depending upon the approach chosen for your redirect, you will need to register your redirect URI with FamilySearch. Please know that your app key (client_id) can be associated with multiple redirect URIs.

If you wish to register redirect URIs for the Beta or Production environments, please see Developer Support for instructions.

PKCE

The Proof Key for Code Exchange (PKCE) is a protocol that helps to ensure that the process that initiated the flow is the same process to complete the flow after the redirect. Native and mobile apps are required to use PKCE. The OAuth 2.0 Simplified book provides a fantastic chapter which describes PKCE and how to implement it.

Requirements and Best Practices

Requirements:

  1. Native applications must use PKCE as part of the authorization process.
  2. The Authorization flow must be performed by the system's default web browser.
    • In the case of iOS, it is acceptable to use SFSafariViewController.
    • In the case of Android, it is acceptable to use Chrome Custom Tabs in Chrome 45+.

Best Practices when using the loopback address for redirect:

  1. Use http://127.0.0.1:{port} (IP v4) or http://[::1]:{port} (IP v6) instead of localhost. Using localhost has been known to cause problems with some client firewalls.
  2. Use a port number greater than 1024 to avoid conflict with reserved ports and to avoid Windows UAC privileged user requirements.

Helpful Implementation Resources


Updated 2 days ago

Did this page help you?