Native and mobile apps cannot keep a secret, cannot prove their identity to an authorisation server on their own, and receive OAuth responses through redirect mechanisms that other apps on the same device can sometimes claim. RFC 8252 (OAuth 2.0 for Native Apps, BCP 212) has defined the safe pattern since 2017: the authorisation code flow in an external user-agent, PKCE, and redirect URIs the operating system can tie to your app. Many apps still sign users in through embedded WebViews, ship client secrets, use generic custom URL schemes or skip PKCE. This guide explains the RFC 8252 model and the later requirements of RFC 9700, how to choose between claimed HTTPS, private-use scheme and loopback redirects, the iOS and Android implementation details, what the authorisation server must enforce, and how to test and monitor it. It is for mobile and desktop developers, identity engineers and application security reviewers.
Key takeaways
- Use the system browser, never an embedded WebView. RFC 8252 section 8.12 says native apps must not use embedded user-agents for authorisation, because the host app can capture credentials and cookies; Google rejects them with a
disallowed_useragenterror. - PKCE with S256 is mandatory. RFC 8252 requires PKCE for native public clients and RFC 9700 makes it a MUST for all public clients, with S256 the only acceptable method in practice.
- Prefer claimed HTTPS redirects. Universal Links and Android App Links let the operating system guarantee which app receives the code; private-use schemes are a fallback and must be reverse-domain names.
- A native app is a public client. Any secret shipped in the binary is public, so the server must not treat it as client authentication or auto-approve consent because of it.
- Protect refresh tokens. RFC 9700 requires refresh tokens for public clients to be sender-constrained (for example DPoP) or rotated, held in the platform keystore.
The RFC 8252 model
RFC 8252 updates RFC 6749 for apps installed on a device, including mobile apps and desktop applications. Its core rule (section 4) is that the app sends the authorisation request through an external user-agent, usually the system browser or an in-app browser tab that runs in the browser's process, not in a web view the app controls. That gives three benefits: the app never sees the user's password or second factor, the user's existing browser session enables single sign-on, and the user can see the real address and browser security indicators.
- The app creates a PKCE
code_verifier(43 to 128 characters; RFC 7636 recommends 32 random octets, base64url-encoded) and its S256code_challenge, plus astatevalue. - It opens the authorisation URL in the external user-agent with
response_type=code, the registeredredirect_uri, the challenge andcode_challenge_method=S256. - The user authenticates with the authorisation server in the browser.
- The server redirects to the app's redirect URI with the code and
state(andiss, per RFC 9207, where supported). - The app checks
stateandiss, then redeems the code at the token endpoint over TLS with thecode_verifier. - The server compares the transformed verifier with the stored challenge and issues tokens only if they match; otherwise it returns
invalid_grant.
PKCE is what makes the redirect safe. RFC 7636 was written for exactly the native case: a malicious app registers the same custom URI scheme and captures the code, but cannot redeem it without the verifier that never left the legitimate app. RFC 7636 also says clients must not downgrade to plain after trying S256. For the wider OAuth picture see the OAuth 2.0 and OpenID Connect Guide.
Choosing a redirect URI
| Redirect type (RFC 8252) | Example | App identity guaranteed by the OS | Best for | Key risks |
|---|---|---|---|---|
| Claimed HTTPS (section 7.2) | https://app.example.com/oauth/callback | Yes, through domain verification | iOS and Android apps, default choice | Verification file errors fall back to opening the browser; domain must be controlled |
| Private-use URI scheme (section 7.1) | com.example.app:/oauth2redirect | No; any app can register the same scheme | Platforms without claimed HTTPS; legacy apps | Code interception (mitigated by PKCE), client impersonation |
| Loopback interface (section 7.3) | http://127.0.0.1:51004/callback | No, but only local processes can listen | Desktop apps and command-line tools | Port squatting by local malware; listener left open |
| Device authorisation grant (RFC 8628) | User enters a code on a second device | Not applicable | TVs, consoles and devices without a browser | Phishing of the user code; see the cross-device guide |
- Claimed HTTPS first: RFC 8252 recommends claimed HTTPS redirects where the platform supports them because the operating system confirms which app owns the domain. RFC 8252 section 8.6 adds that servers should not auto-approve a request without user consent unless the client's identity is proven, and a claimed HTTPS redirect is the usual way to prove it.
- Private-use schemes done properly: use a reverse-domain scheme you control (
com.example.app), never a generic word likemyapp. Google no longer supports custom URI schemes for its Android and iOS clients, citing app impersonation. See the Mobile Deep Link and App Link Security Guide. - Loopback done properly: RFC 8252 section 8.3 says to open the port only for the duration of the request, bind only to the loopback interface, try both
127.0.0.1and[::1], and avoid the namelocalhost. Plain HTTP is acceptable on loopback, and RFC 9700 section 2.6 allows HTTP redirect URIs only in this case. Google's guidance treats loopback as the method for desktop apps and deprecates it for mobile client types. - Input-constrained devices: use the device authorisation grant rather than inventing a flow. See the Cross-Device Flow Security Guide.
Platform implementation details
iOS and macOS
- ASWebAuthenticationSession: Apple's API for web sign-in shows a system prompt naming the domain the app is authenticating with, then loads the page in a secure browser context (an embedded secure web view on iOS, the default browser on macOS where supported). Apple documents that it ensures only the calling app's session receives the callback, even when several apps register the same callback scheme, which closes much of the custom-scheme interception risk on Apple platforms.
- Callbacks: the newer initialiser takes an
ASWebAuthenticationSession.Callbackobject; the oldercallbackURLSchemeinitialiser is marked deprecated in Apple's documentation. HTTPS callbacks rely on your app's Associated Domains entitlement and anapple-app-site-associationfile on the domain. - Session sharing:
prefersEphemeralWebBrowserSessionasks for a private session that does not share cookies with the browser. Use it for shared devices or when single sign-on is not wanted; leave it off when SSO is the goal. - Legacy APIs: RFC 8252 Appendix B, written in 2017, names
SFSafariViewControllerandSFAuthenticationSession; current apps should useASWebAuthenticationSession.WKWebViewis an embedded user-agent and must not host the sign-in.
Android
- Custom Tabs: RFC 8252 Appendix B recommends Android Custom Tabs, which run in the user's browser and share its session. Fall back to the full browser if no Custom Tabs provider is installed; never fall back to
WebView. - App Links: add
android:autoVerify="true"to an intent filter withandroid.intent.action.VIEW, theBROWSABLEandDEFAULTcategories and anhttpsscheme; publish/.well-known/assetlinks.jsonon every host listing the app's package name and signing certificate fingerprint. Check status withadb shell pm get-app-links PACKAGE_NAME, which should showverifiedfor each domain. On Android 11 and lower every host in the manifest must verify; on Android 15 and later the system re-verifies in the background and changes can take up to seven days to reach devices. - Play App Signing: the fingerprint in
assetlinks.jsonmust be the app signing key that Google Play uses, not only the upload key, or verification fails silently in production.
Libraries
The AppAuth libraries for iOS and Android implement RFC 8252 (external user-agent, PKCE, state, token exchange) and are the reference implementations; cross-platform wrappers such as react-native-app-auth build on them. See the Flutter and React Native Security Guide for cross-platform specifics.
What the authorisation server must enforce
| Server control | Source | Why it matters for native apps |
|---|---|---|
| Register native apps as public clients with full redirect URIs | RFC 8252 section 8.4 | Stops secrets being issued that cannot be protected |
| Exact string matching of redirect URIs (port may vary for loopback) | RFC 9700 section 2.1, ASVS 5.0 V10.4.1 | Prevents redirect manipulation to attacker-controlled URIs |
Require PKCE and reject plain | RFC 9700 section 2.1.1, ASVS V10.4.6 | Makes intercepted codes useless |
| No implicit grant, no resource owner password grant | RFC 9700 sections 2.1.2 and 2.4 | Removes token-in-URL and password-in-app patterns |
| Sender-constrain or rotate refresh tokens; absolute expiry | RFC 9700 section 2.2.2, ASVS V10.4.5, V10.4.8 | Limits value of tokens copied from a device |
| Do not auto-approve consent for unproven clients | RFC 8252 section 8.6 | Stops an impersonating app silently obtaining tokens |
Return iss in authorisation responses | RFC 9700 section 4.4.2 (RFC 9207) | Defends apps that support several identity providers against mix-up |
| Short-lived, audience-restricted access tokens | RFC 9700 section 2.3 | Limits damage from token leakage |
Where the server needs stronger assurance that requests come from a genuine app, client attestation (platform attestation such as App Attest or Play Integrity, or the OAuth attestation-based client authentication work) can be layered on; see the OAuth Attestation-Based Client Authentication Guide. DPoP is the usual way to sender-constrain tokens for mobile apps, with the key held in the Secure Enclave or Android Keystore; see the DPoP Guide.
Token handling inside the app
- Access tokens: keep in memory where practical, short lifetime, never in logs, crash reports or URLs (RFC 9700 section 4.3.2 forbids access tokens in query parameters).
- Refresh tokens: store in the iOS Keychain or Android Keystore-backed storage with device-only accessibility so backups do not move them; rotate on every use.
- ID tokens: validate signature, issuer, audience, expiry and nonce if the app consumes identity claims locally; better, let the backend validate and issue its own session.
- Logout: revoke the refresh token at the server, clear the keystore entry, and end the browser session if single sign-on should end too. See the OAuth Token Introspection and Revocation Guide.
- Backend calls: if the app's backend calls other APIs, it should exchange the user's token rather than forward it. See the OAuth Token Exchange and Delegation Guide.
Implementation and migration steps
- Inventory clients: list every native and desktop client registration, its redirect URIs, grant types, whether a secret was issued and whether PKCE is enforced.
- Stand up claimed HTTPS: publish
apple-app-site-associationandassetlinks.json, ship an app build with the entitlement and intent filter, and confirm verification on test devices before switching the redirect. - Switch the sign-in UI: replace any WebView sign-in with AppAuth or the platform session API. Roll out behind a remote flag to a pilot percentage, monitor sign-in completion, and keep the previous path available for one release as rollback.
- Enforce PKCE server-side: start by logging token requests without a verifier, notify owners, then reject them once old app versions fall below an agreed threshold (use minimum version enforcement in the app to retire old builds).
- Retire secrets and weak grants: convert clients to public, rotate out any embedded client secret, disable implicit and password grants.
- Harden refresh tokens: turn on rotation with reuse detection, then DPoP binding for apps that support it.
Decision guidance: first-party apps of large organisations should use claimed HTTPS redirects, AppAuth and DPoP, with attestation for high-risk services such as banking. Small teams can get most of the benefit from AppAuth plus server-enforced PKCE and rotation. A desktop or command-line tool should use loopback redirects with PKCE, and the device authorisation grant only when the device has no usable browser. Native apps that call only their own backend may prefer that backend to act as the OAuth client and issue its own session, which keeps refresh tokens off the device entirely.
Testing, detection and measurement
- Test interception: install a test app that registers the same custom scheme and confirm that a captured code cannot be redeemed without the verifier, and that the server rejects requests with no challenge or with
plain. - Test redirects: try variations of the registered redirect URI (extra path, query, different case, other port for non-loopback) and confirm rejection.
- Test WebView detection: confirm the identity provider blocks sign-in from embedded user-agents.
- Monitor: token requests without PKCE, refresh token reuse after rotation, the same refresh token family used from different devices or networks, spikes in failed
invalid_grantcode redemptions, and new redirect URIs added to client registrations.
Metrics: percentage of native clients enforcing PKCE S256 (target 100); percentage using claimed HTTPS redirects; number of native clients holding a client secret (target zero); refresh token reuse detections per month; share of sign-ins still served by app versions older than the WebView removal.
Framework mapping
| Control | OWASP ASVS 5.0 | NIST SP 800-53 Rev. 5 | NIST CSF 2.0 | ATT&CK |
|---|---|---|---|---|
| Exact redirect matching, claimed HTTPS | V10.4.1 | IA-2 | PR.AA-03 | T1635.001 URI Hijacking (Mobile) |
| PKCE enforcement | V10.4.6 | IA-2, SC-23 | PR.AA-03 | T1635.001 |
| CSRF and state on the client | V10.2.1, V10.1.2 | SC-23 | PR.AA-03 | n/a |
| External user-agent, no WebView | n/a | IA-5 | PR.AA-01 | T1417 Input Capture (Mobile) |
| Refresh token rotation or binding | V10.4.5, V10.4.8 | IA-5 | PR.AA-01 | T1528 Steal Application Access Token |
Common failure patterns
- Sign-in in a WebView: the app can read the password and second factor, users cannot verify the site, SSO breaks, and identity providers increasingly block it.
- Client secret in the binary: extracted in minutes and then used to impersonate the app, especially where the server auto-approves consent for "confidential" clients.
- PKCE supported but not required: the server accepts token requests with no verifier, so an intercepted code still works.
- Generic custom scheme:
myapp://callbackclaimed by any other app; with no PKCE enforcement this hands over codes. - App Links never verified: a wrong signing fingerprint in
assetlinks.jsonmeans the "claimed" HTTPS redirect opens in the browser and the flow breaks, so teams revert to custom schemes. - Long-lived refresh tokens in plain storage: tokens in SharedPreferences or NSUserDefaults survive in backups and are copied by malware; see the OWASP Mobile Top 10 M9 Insecure Data Storage Guide.
Practitioner checklist
- Use AppAuth or the platform session API with the system browser or Custom Tabs; remove WebView sign-in.
- Generate a fresh PKCE verifier per request and use S256 only.
- Use claimed HTTPS redirects; verify
assetlinks.jsonandapple-app-site-associationwith the production signing key. - If a custom scheme is unavoidable, use a reverse-domain scheme you control.
- For desktop tools, use loopback on
127.0.0.1or[::1]with a port opened only during sign-in. - Register native apps as public clients with no secrets; enforce exact redirect matching and PKCE on the server.
- Disable implicit and password grants for all native clients.
- Rotate refresh tokens with reuse detection and bind them with DPoP where supported.
- Store refresh tokens in Keychain or Keystore with device-only accessibility.
- Monitor PKCE-less requests, refresh token reuse and changes to client redirect URIs.
Standards and references
- IETF: RFC 8252 OAuth 2.0 for Native Apps
- IETF: RFC 7636 Proof Key for Code Exchange by OAuth Public Clients
- IETF: RFC 9700 Best Current Practice for OAuth 2.0 Security
- OWASP: Application Security Verification Standard 5.0
- OWASP: Mobile Application Security Verification Standard
- Apple Developer: ASWebAuthenticationSession
- Android Developers: Verify Android App Links
- Google Identity: OAuth 2.0 for native and desktop apps
Related NHI Mgmt Group resources: OWASP Mobile Top 10 M3 Insecure Authentication and Authorization Guide · OAuth 2.0 Security Best Current Practice (RFC 9700) Guide · OAuth Refresh Token Rotation and Expiry Guide · Mobile App Security Guide