Desktop Code Sample Overview

Background

Previously we summarised this blog’s Native Architecture Goals. Secured mobile apps will be covered in later posts. First though, we will implement an initial OpenID Connect secured desktop code sample.

Features

The behaviour provided in our initial sample is summarised below:

Feature Description
Cross Platform The desktop app will run on Windows, macOS and Linux and will be coded in TypeScript
Library Integration A third party library will implement OpenID Connect logins and token handling
System Browser Logins The desktop app will invoke the system browser to sign the user in, then listen for the login response
Reliability We will handle some re-entrancy scenarios when our app interacts with the system browser

Components

The sample connects to components hosted in AWS, so that readers only need to run the Desktop Code to get a complete solution. This will include the use of web content that renders a post login page in the system browser.

Code Download

The code for our Initial Desktop App can be downloaded from here, and we will cover full details of how to run it in the next post:

 Code Sample Behaviour

Our overall Desktop UI will have the same simple theme and views as the earlier SPAs, though the login user experience will feel different:

Desktop App Technology

We will implement our app using Electron, which uses web technologies for desktop screen development. We will therefore be able to re-use most code from the Plain TypeScript SPA we built earlier.

Platform Specific Appearance

Our desktop app will run on Windows, macOS and Linux, and the following screenshots show the minor differences in appearance:

AppAuth Security Library

We will use the AppAuth-JS Library to implement the OpenID Connect  flow. Once the behaviour is understood you should be able to adapt it to any other desktop technology, using a different library. For example, a C# desktop app might use the Identity Model OIDC Client.

Deprecated Web View Logins

A few years ago it was standard for OAuth secured desktop apps to use a web view for logins. In a C# application you might write code like this:

Typically logins would use a popup window hosting a web view browser control. The popup would capture the login response from the web view via an ‘Out of Browser Redirect URI‘ such as urn:ietf:wg:oauth:2.0:oob.

However, using web views is no longer recommended. Web views runs a private browser session, where SSO cookies may be dropped and password autofill may have issues. Authorization servers are encouraged to inspect the user agent and block login requests from web views:

Instead, in 2021 it is recommended to open an external system browser  window on which the user performs their login. Doing so avoids the use of a private browser session, yet feels less integrated into the desktop app.

Native Authorization Responses

A web client runs in a browser and has an addressable URL on which to receive login responses. Native apps need a different mechanism, and RFC8252 explains the 3 options that can be used:

Only the first two options work for a desktop app, and the loopback option will be used for this blog’s initial desktop app. The final desktop app will instead use a private URI scheme. Later, this blog’s mobile apps will use claimed HTTPS schemes.

Option Example Redirect URI Usable By
Loopback Interface http://127.0.0.1:8000 Desktop apps
Private URI Scheme x-mycompany-myapp:/callback Mobile or desktop apps
Claimed HTTPS Scheme https://web.mycompany.com/myapp Mobile apps

The AppAuth Code Sample

To quickly see a login via the System Browser, you can run the AppAuth Electron Sample via these commands:

  • git clone https://github.com/googlesamples/appauth-js-electron-sample
  • cd appauth-js-electron-sample
  • npm install
  • npm start

A simple desktop apps then presented, and we can click Sign In to invoke an OAuth login on the system browser:

When the Sign In link is clicked, the system browser is opened. If the user is not already logged in, there will be a prompt to sign in via Google:

The Desktop App supplies a ‘loopback’ value of http://127.0.0.1:8000 as the OAuth redirect URI, and creates an HTTP endpoint on this port, to listen for the response.

After login, a request is sent to this HTTP endpoint, with the authorization response URL. The desktop app then extracts the returned authorization code and swaps it for tokens, after which it can call APIs.

Login User Experience

The login UX for the desktop view is not ideal. There is a disconnected browser window, and a blank page by default. We will show how to render a custom page, and also how to handle retries, to ensure reliability.

Where Are We?

This post explained the behaviours of the initial desktop code sample, to get logins and API calls working with basic reliability. Next we will show how to build and run it locally.

Next Steps