Skip to main content

Native applications

Integrating with CIS2 Authentication from native desktop or mobile applications.

Page contents

Overview

The Open ID Connect (OIDC) Authorization Code Flow that we use for integrating with CIS2 Authentication is primarily a browser-based integration, but it can also be used with native desktop or mobile applications.

There are two key aspects to consider:

  1. Triggering, and handling the outcome from, the browser-based sign in journey.
  2. Calling our APIs securely.

Sign in journey

There are 2 main options available to native application developers for launching the authentication journey:

  1. System browser.
  2. Embedded browser.

Using the system browser is considered the best practice by https://www.rfc-editor.org/rfc/rfc8252, however we do support both options.

Both options have the same fundamental challenge - how to receive the authorisation code from the redirected callback once the authentication journey has completed. In a web-based application, this is just a query parameter appended to the redirection URL such that the web component can extract it, and then use on the token endpoint to retrieve the ID and access tokens. 

This is described in the OAuth 2.0 specification at https://www.rfc-editor.org/rfc/rfc6749#section-9:

OAuth 2.0 Native Applications

Native applications are clients installed and executed on the device used by the resource owner (i.e., desktop application, native mobile application). Native applications require special consideration related to security, platform capabilities, and overall end-user experience.
The authorization endpoint requires interaction between the client and the resource owner's user-agent. Native applications can invoke an external user-agent or embed a user-agent within the application. For example:

  • External user-agent - the native application can capture the response from the authorization server using a redirection URI with a scheme registered with the operating system to invoke the client as the handler, manual copy-and-paste of the credentials, running a local web server, installing a user-agent extension, or by providing a redirection URI identifying a server-hosted resource under the client's control, which in turn makes the response available to the native application.
  • Embedded user-agent - the native application obtains the response by directly communicating with the embedded user-agent by monitoring state changes emitted during the resource load, or accessing the user-agent's cookies storage.

When choosing between an external or embedded user-agent, developers should consider the following:

  • An external user-agent may improve completion rate, as the resource owner may already have an active session with the authorization server, removing the need to re-authenticate. It provides a familiar end-user experience and functionality. The resource owner may also rely on user-agent features or extensions to assist with authentication (e.g., password manager, 2-factor device reader).
  • An embedded user-agent may offer improved usability, as it removes the need to switch context and open new windows.
  • An embedded user-agent poses a security challenge because resource owners are authenticating in an unidentified window without access to the visual protections found in most external user-agents. An embedded user-agent educates end-users to trust unidentified requests for authentication (making phishing attacks easier to execute).

Other considerations

System browser

When an application launches the system browser, and the authentication has taken place, the browser window will remain open and 'orphaned' until the user closes it. 

If the user closes the whole browser (all tabs and windows) between each authentication, then CIS2 Authentication cannot re-use that session for future authentications. This will mean that the authentication session quota will be used up with each authentication journey until the limit is hit. At this point a back-channel logout notification will be triggered for the first session that was created. For more details, see Session management.

Embedded browser

You should also consider the capabilities of any embedded browser that is chosen. CIS2 Authentication is designed to use multiple forms of authentication that include:

  • JavaScript localhost communications to the Credential Management application for Smartcard auth
  • FIDO2 platform and cross-platform authenticators
  • username / password / TOTP code 

You should ensure that any choice of embedded browser component can support these to allow the best user experience. You should also ensure that the component is kept up to date with new features available from the underlying browser engine to maintain security and support any future authentication options that the platform may introduce.

Using an embedded browser also requires careful management of any cookies created during the authentication session. In particular, CIS2 Authentication uses a persistent preference cookie that holds the user's selected method of authentication so that the next time they authenticate, the user does not have to select the method again. In the system browser, this preference cookie will be maintained. If this cookie is not preserved in the embedded browser, the user experience will be degraded as the choice will have to be made every time the user authenticates.

Calling our APIs securely

You must not call our APIs directly from a native application. To do this you would need to expose your secret credentials to the client device, which would be a security risk.

Rather, you must call our APIs from a secure server-side component.

For more details, see Confidential client.

Last edited: 26 January 2026 12:23 pm