Skip to content

Mobile and native apps

A mobile or desktop app cannot keep a secret: anything shipped in it can be read. LexOpti follows RFC 8252 (OAuth 2.0 for native apps) for those apps, and lets them show the embedded components inside a webview.

Your product Register Where the tokens live
An app with your own server (most business software) a web application: your server is the client, the app talks to your server on your server, never on the device
An app with no server of its own a native app: a public client, no secret on the device, in the Keychain (iOS, macOS) or a Keystore-backed store (Android)

When you have a server, keep it the client: the member authorizes in the system browser, LexOpti redirects to your server’s HTTPS callback, and your app never holds a LexOpti token. The rest of this page is about the second case, and about the embedded components in a webview, which works in both.

In the developer console, choose Native or mobile app as the application type. LexOpti registers a public client: no client secret (none is shown, none can be rotated), PKCE S256 required at every authorization. Its redirect URIs take one of the three forms of RFC 8252, each compared exactly:

Form Example Rule
Loopback interface, for desktop apps (§7.3) http://127.0.0.1/oauth/callback, http://[::1]/oauth/callback the IP literal, never localhost (§8.3); the port is left out and any port matches at authorization, so the app listens on whichever port the system gives it
Private-use URI scheme (§7.1) com.example.crm:/oauth/callback a reverse domain name you control, with a period (§8.4)
Claimed HTTPS URI (§7.2) https://app.example.com/oauth/callback an iOS universal link or an Android app link, verified for your domain; the rule of a web application

Prefer a claimed HTTPS URI when you can verify your domain: another app on the device can register the same private-use scheme and receive the code (§8.1), and only PKCE then keeps an intercepted code useless. A loopback listener binds the loopback interface only, accepts one redirect, and stops.

Open the authorization URL in the system browser, never in a webview of your app (RFC 8252 §8.12: the app could read the member’s password, and the member could not check the address): ASWebAuthenticationSession on iOS and macOS, Custom Tabs on Android, the default browser on the desktop. The request is the one of a web application (authentication), with your redirect URI and a fresh PKCE verifier and state for each attempt.

With a loopback or private-use redirect, nothing proves which program asks (RFC 8252 §8.6): any one on the device could send your client_id. LexOpti therefore shows the consent page, naming your app, at every authorization, even when the member already approved it, and refuses prompt=none with interaction_required at your redirect URI. A claimed HTTPS redirect is bound to your verified domain and follows the web application’s rule.

Then call the token endpoint with your client_id in the form, and no Authorization header:

Grant Parameters at the token endpoint
authorization_code client_id, code, code_verifier, redirect_uri, resource
refresh_token client_id, refresh_token, resource

A code that fails once, with a missing or wrong verifier, is spent: start the authorization again. Refresh tokens rotate as a web application’s do: each refresh answers a new one, valid 30 days, and the old one stops working (a concurrent refresh within 10 seconds gets the same answer). Store the new refresh token in the Keychain or the Keystore before using the access token, and let one refresh run at a time (lifetimes and rotation).

To show LexOpti’s screens in your app, host the components on your own HTTPS page, as on the web (embedded components), and load that page in a webview (WKWebView on iOS, WebView on Android). What works and what to set:

  • The page’s origin. Register the page’s exact origin (https://crm.example.com) as an embed origin, and load the page by its URL. A page loaded from a file, a custom scheme or an HTML string has no origin LexOpti can allow: the frame refuses to show, since it only accepts the registered origins as parent and as postMessage partner.
  • Sessions. The session provider asks your server for each session code from that page, with your own session with your server, first-party in the webview as in a browser. A new webview, or a reload, opens new sessions: a code is single use for 60 seconds, a session token lives 10 minutes in the frame’s memory.
  • Cookies and storage. LexOpti’s session token never leaves the frame’s memory, but the frame keeps its interface preferences (a list’s cards or table view, a dismissed notice) in DOM storage and the language in a cookie. When storage or the third-party cookie is refused (WebKit’s Intelligent Tracking Prevention in WKWebView, CookieManager.setAcceptThirdPartyCookies off by default in Android WebView), the frame keeps working with its defaults: the table view, nothing remembered from one page to the next, the language your page gives the components. Do not loosen cookie blocking for LexOpti.
  • JavaScript and DOM storage. Enable both on Android (settings.javaScriptEnabled = true, settings.domStorageEnabled = true); WKWebView has both by default.
  • New windows. Signing in to LexOpti, billing, a PDF and the links to LexOpti open in a new tab (flows in LexOpti’s own window). A webview opens nothing until you handle it: open those URLs in the system browser (SFSafariViewController or the default browser) from WKUIDelegate‘s webView(_:createWebViewWith:for:windowFeatures:) on iOS, and from WebChromeClient.onCreateWindow with setSupportMultipleWindows(true) on Android (Custom Tabs). A page may open a window only if the webview allows it: javaScriptCanOpenWindowsAutomatically = true (WKPreferences on iOS, WebSettings on Android). On Android, onCreateWindow must hand the new window a transport WebView (WebView.WebViewTransport, then resultMsg.sendToTarget()) and read the URL that webview is asked to load, to open it in a Custom Tab. These settings come from the platforms’ documentation: LexOpti has not tested them on a device.
  • Versions. WKWebView is the system’s WebKit: iOS 16.4 or later, as Safari 16.4. Android WebView follows Chrome through the Play Store.
  • Not in the webview. The OAuth authorization of the member (above) never runs in it.
  • No client secret exists for a native app: nothing to protect in your binary, nothing to rotate. PKCE binds each code to the app that asked for it.
  • localhost is refused: the name may resolve elsewhere, and another program could answer on another interface (§8.3).
  • A private-use scheme without a period, such as myapp:, is refused: any app could claim it (§8.4).
  • A refresh token on the device is the member’s access for 30 days: keep it in the Keychain or the Keystore, never in plain preferences, and revoke it when the member signs out of your app: POST https://app.lexopti.com/api/auth/oauth2/revoke with client_id, token and token_type_hint=refresh_token, no secret (disconnect a member).