Agent Wranglers

MOB-43Required

Sign in through the system browser with PKCE

Run OAuth and OpenID Connect sign-in in the system browser session, never in a web view inside the app. Every request uses PKCE, and the redirect goes to a claimed https address.

By Agent Wranglers. Updated .

How to do it

RFC 8252 says native apps must not use embedded user agents for authorization requests. A web view lets the app read the password and gives people no way to see the address. Use ASWebAuthenticationSession on iOS and Custom Tabs on Android, often through a library such as AppAuth. A custom scheme such as exampleapp:// can be registered by another app on the device, which can then catch the code. PKCE makes a caught code useless, and a claimed https redirect lets the system prove which app receives it. Verify the redirect domain as open deep links only from verified domains says. The flow itself follows let people sign in with an account they already have. Store the tokens as keep tokens and keys in the Keychain or Keystore says.

Examples

Plain text example

let session = ASWebAuthenticationSession(
    url: authorizeURL(codeChallenge: pkce.challenge),
    callback: .https(host: "app.example.com", path: "/oauth/callback")
) { callbackURL, error in
    guard let code = callbackURL?.queryValue("code") else { return }
    Task { try await auth.exchange(code: code, verifier: pkce.verifier) }
}
session.presentationContextProvider = self
session.start()

Kotlin example

val request = AuthorizationRequest.Builder(serviceConfig, clientId, ResponseTypeValues.CODE,
    Uri.parse("https://app.example.com/oauth/callback"))
    .setCodeVerifier(CodeVerifierUtil.generateRandomCodeVerifier())
    .setScopes("openid", "profile")
    .build()
startActivityForResult(authService.getAuthorizationRequestIntent(request), REQUEST_SIGN_IN)

How to check

A search of the source finds no sign-in page loaded in WKWebView or android.webkit.WebView. A token request without code_verifier gets an error from the authorization server.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/mobile-apps/network-links-and-web-views/system-browser-sign-in">Agent Wranglers mobile apps playbook</a>. In code you write, add a comment next to it with the same link.