halkyon/packages/halkyon_oidc_flutter/README.md

halkyon_oidc_flutter

The device's half of halkyon_oidc (halkyon_oidc_server, halkyon_oidc_client), signing in with OpenID Connect for Serverpod v4. It opens the provider's page for an attempt the server began, waits until the browser comes back, and checks that it came back for that attempt. The code it returns goes back to the server, which ends the sign-in. Halkyon signs in with it (ADR 0020, ADR 0023); nothing of Halkyon's is in it.

Using it

final browser = OidcBrowser(loopback: LoopbackWebAuth(appName: 'My App'));

// The app's endpoint on OidcIdpBaseEndpoint (halkyon_oidc_server's README).
final start = await client.signIn.begin(provider: 'keycloak');
switch (await browser.open(start, const OidcReturn.scheme('my.app'))) {
  case null:
    // The person closed the browser.
  case OidcDenied(:final error):
    // The person said no at the provider (`access_denied`).
  case OidcCode(:final code):
    final session = await client.signIn.login(attempt: start.attempt, code: code);
}

open throws an OidcCallbackException when the browser came back for another sign-in (wrongState), with neither one code nor one refusal (malformed), when there's no browser (noBrowser), or when the way back failed otherwise (failed).

The state is checked here, on the device: the server keeps the attempt's nonce, which ties the code to the attempt, but never compares the state.

The way back

Pick one per sign-in, before opening the browser: each must match the redirect the server's provider names, or the address its forwarding page sends the browser on to (addOidcCallbackForwarding).

• OidcReturn.scheme('my.app') on Android, iOS and macOS. The system's browser sheet catches the scheme, even after a redirect: Chrome's Auth Tab (Chrome 132 on), a Custom Tab after the person's click on the consent page in other browsers, and ASWebAuthenticationSession. Android needs flutter_web_auth_2's CallbackActivity with the scheme, for the browsers without Auth Tab:

  <activity android:name="com.linusu.flutter_web_auth_2.CallbackActivity"
            android:exported="true" android:taskAffinity="">
    <intent-filter android:label="flutter_web_auth_2">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="my.app" />
    </intent-filter>
  </activity>
  

• OidcReturn.loopback(port: 43823, path: '/oidc-callback') on Linux and Windows: LoopbackWebAuth opens the system browser and waits on 127.0.0.1 alone (RFC 8252, 7.3), five minutes at most, until cancel. It takes the place of flutter_web_auth_2's own, which ends the wait whenever the window regains focus. Give each app its own port.

• OidcReturn.https(host: 'example.org', path: '/oidc-callback') where the system hands the address to the app alone: Android's App Links with Chrome's Auth Tab (the host's assetlinks.json), iOS v17.4 and macOS v14.4 on with associated domains (webcredentials:). It protects only where nothing else can come back: a hostile app that begins a sign-in of its own may ask for any way back the server still forwards to. On Android it fails where the app isn't verified, as a debug build isn't, and in browsers without Auth Tab (Firefox, as of v156).

A code caught on its way is worthless without the attempt's ID, which only the device holds, so the scheme and the loopback are safe for the sign-ins the app begins itself.

Licence

BSD-3-Clause, as Serverpod's own (ADR 0023, D2).