OAuth: Native Setup

Maintainer side of native OAuth. The web team's page (OAuth Integration in the web team docs) covers the /_oauth_callback contract and the backend changes; this page covers the native clients, build flags and implementation.

How native OAuth works

Native intercepts the provider's authorization URL and restarts the flow in a system browser with the native client id and a custom-scheme redirect, adding PKCE for Google (Facebook is a confidential client, so PKCE is disabled for it):

iOS: ASWebAuthenticationSession(url:callbackURLScheme:).
Android: AppAuth Custom Tab; the redirect is caught by AppAuth's RedirectUriReceiverActivity.

On completion native loads <initialUrl>/_oauth_callback?… in the WebView and the web app finishes the token exchange.

Provider / cloud configuration

Google
- Create a dedicated iOS OAuth client and an Android OAuth client (package name + signing SHA-1) in Google Cloud.
- iOS: put the real CLIENT_ID/REVERSED_CLIENT_ID in ios/App/App/GoogleService-Info.plist. The custom-scheme redirect is <REVERSED_CLIENT_ID>:/oauth2redirect.
- Android: set the redirect scheme to the Android client's reversed client id (see build flags below).
Facebook — register iOS + Android platforms in the Facebook app. On iOS set the app id in FACEBOOK_APP_ID; Android has no Facebook app id setting.
Redirect URIs per platform:
- iOS Google: <REVERSED_CLIENT_ID>:/oauth2redirect
- iOS Facebook: fb<appid>://authorize
- Android, every provider: <OAUTH_REDIRECT_SCHEME>://oauth (one scheme for all providers)
Register every custom-scheme redirect URI in the respective provider console.

Build flags

Native OAuth is off by default on both platforms; enable it once the real client ids + redirect scheme are configured.

Android (`android/app/build.gradle`)

Field	Default	Effect
`OAUTH_ENABLED`	`false`	Activates the AppAuth interception in `MainActivity`
`OAUTH_REDIRECT_SCHEME`	`applicationId`	Custom-scheme for the redirect. Must equal the `appAuthRedirectScheme` manifest placeholder (both are driven by the single `oauthRedirectScheme` variable). Set to the Google reversed client id when using Google
`DEEPLINK_ENABLED`	`false`	Unrelated to OAuth return (the Custom-Tab result returns via `onActivityResult`); only needed for host deep links

iOS (user-defined build settings in `project.pbxproj`, surfaced via `Info.plist`)

Build setting	`Info.plist` key	Default	Effect
`OAUTH_ENABLED`	`OAuthEnabled` (`$(OAUTH_ENABLED)`)	`NO`	Activates `OAuthCoordinator` interception
`FACEBOOK_APP_ID`	`FacebookAppID` (`$(FACEBOOK_APP_ID)`)	(empty)	Facebook app id; also forms the `fb<appid>` redirect scheme

Google config on iOS comes from GoogleService-Info.plist (CLIENT_ID/REVERSED_CLIENT_ID).

Platform notes

iOS — OAuthCoordinator.swift drives ASWebAuthenticationSession. The callback scheme is not registered in CFBundleURLTypes: ASWebAuthenticationSession catches its own callbackURLScheme, and registering the same scheme would risk the redirect routing to application(_:open:) instead of the session callback. PKCE uses CryptoKit (SHA-256). No new pod.
Android — MainActivity uses AppAuth (net.openid:appauth), authorization step only. PKCE is added by AppAuth automatically for Google and disabled for Facebook (setCodeVerifier(null)); the verifier is read back from AuthorizationResponse.request.codeVerifier and forwarded to the web app. No native token storage.

15 November 2026