Secure sessions

Some providers refuse to run inside a web view, like Plaid Hosted Link or Stripe Connect onboarding. A secure session opens them in the system's secure browser instead, then brings people back to your app, still signed in, when the provider is done.

Add data-native-secure-session to the link:

<%= link_to "Connect your bank", @hosted_link_url, data: { native_secure_session: true } %>

On iOS it opens in a sign-in sheet (ASWebAuthenticationSession), and on Android in a Custom Tab. Outside the app the attribute does nothing, so the same link keeps working in browsers.

#Bring people back

When the provider finishes, it redirects to a completion URL you give it up front. native_secure_session_completion_url builds one that closes the browser and loads return_to in your app:

completion_url = native_secure_session_completion_url(return_to: bank_connected_path)

return_to must be a path on your site. The helper returns nil outside the app, so keep your existing web flow for browsers:

completion_url = native_secure_session_completion_url(return_to: bank_connected_path) || bank_connected_url

Nothing sensitive comes back through the redirect. Read the result on your server, from the provider's webhook or API, like you do on the web.

Pass the completion URL as completion_redirect_uri in a hosted_link block when you create the link token:

request = Plaid::LinkTokenCreateRequest.new(
  # ...your user, products, country_codes, and so on
  hosted_link: {
    completion_redirect_uri: native_secure_session_completion_url(return_to: bank_connected_path),
    is_mobile_app: true
  }
)

Then link to the hosted_link_url from the response.

OAuth banks. UK and EU banks, and some US ones, use OAuth, where the bank's own app takes over and hands back to yours. That needs two more things:

  • A redirect_uri on your own domain in the link token, registered in the Plaid Dashboard. The route just needs to exist.
  • Your domain linked to your app, so the bank's app can hand back to it. Follow Linked domains, and add the redirect path to linked_paths if you use it.

Your return page can't assume success. Plaid sends people to the completion URL when they finish and when they cancel, and says nothing about which. Ask Plaid what happened (/link/token/get, or the SESSION_FINISHED webhook) before showing a thank-you message.

#What people see

On iOS, the system asks before the sheet opens: "Your App" Wants to Use "secure.plaid.com" to Sign In. The wording is Apple's and can't be changed. It says "sign in" even for a payment, so a line of copy next to your button saying what comes next helps.

Requires Ruby Native 0.21.0 and a build made with it. Older builds open the link in the web view, where providers like Plaid refuse to load.