Native sign-in

Use the operating system browser for authorization code with PKCE S256. A native client is public: it has a client ID and exact registered callback, but no client secret. Never embed a central password form or use email to select a local officer account.

Run the reference tests

The generic desktop reference binds an ephemeral listener on 127.0.0.1, opens the system browser, checks state before exchange, and validates nonce and the ID token through openid-client. It prints only issuer and subject. It neither creates a product role nor requests a management API token.

cd examples/native
npm ci
npm test

A live run needs only OIDC_ISSUER and OIDC_CLIENT_ID in its runtime environment. The issuer must be trusted HTTPS, and that reviewed public client must permit http://127.0.0.1:{ephemeral-port}/callback under its native redirect policy. The owned issuer has no such client today. Once one exists, run:

cd examples/native
npm start

A successful run prints a JSON object shaped like this, with the actual issuer and subject:

{"identity":{"issuer":"https://issuer.example.test","subject":"SUBJECT_FROM_ID_TOKEN"},"product_access":"requires separate local authorization"}

The fixed Mail mobile and desktop profiles use different exact callbacks, so they cannot run this generic loopback reference as-is.

Build a product client

Bind the callback listener before launching the browser. Generate a fresh state, nonce and S256 verifier for each attempt. Match the callback to the exact request, redeem the code once, and validate the signed ID token for issuer and client audience. Store any retained tokens in platform secure storage. Send an access token to a backend only when it is issued for that backend’s audience and scope.

The backend maps (iss, sub) to an existing local account, checks current product eligibility, Institution and role, then creates its own session. A native app should refresh or reauthenticate when that local session is revoked. For Mail-specific audience and callbacks, see Taifa Mail.