Native OIDC clients

Overview

Native OIDC clients are applications that run natively on user devices, such as mobile applications (iOS, Android) and desktop applications (Windows, macOS, Linux). Unlike web-based applications that run in browsers, native applications have different security considerations and capabilities when integrating with Identify.

Characteristics of native OIDC clients

Native OIDC clients have several distinct characteristics:

  • Custom URI schemes: Native apps typically use custom URI schemes (e.g., myapp://callback) for redirect URIs instead of https:// URLs, allowing the operating system to redirect authentication responses back to the app.
  • Independent sessions: Native app sessions operate independently from browser sessions, with their own lifecycle and logout behavior.

Custom URI scheme support

Identify provides enhanced support for native OIDC clients through flexible custom URI scheme configuration.

What are custom URI schemes?

Custom URI schemes allow native applications to register URL patterns that the operating system can recognize and route to the application. For example:

  • myapp://callback
  • com.example.myapp://oauth/redirect
  • http://127.0.0.1:44038/

When the OIDC provider redirects to these URLs after authentication, the operating system launches or activates the registered application and passes the authentication response.

Configuring validation for multiple URI schemes (optional)

Native OIDC clients can use custom URI schemes by adding them to redirect URIs in connection settings. However, if you want to enforce validation rules and restrict which URI schemes are allowed in authorization requests, you can configure the AdditionalValidationRules setting on your OIDC client connection:

{
  "authorize": {
    "requiredParameters": "code_challenge, code_challenge_method",
    "redirectUriScheme": "myapp,com.mycompany.myapp,http",
    "codeChallengeMethod": "S256"
  }
}

Configuration example

Step 1: Configure Redirect URIs in Connection Settings

In the OIDC client connection settings, add all redirect URIs your native app will use:

http://localhost:8080/callback
myapp://callback
com.mycompany.myapp://oauth/redirect

Step 2: (Optional) Add AdditionalValidationRules

If you want to enforce validation rules for redirect URI schemes and require PKCE, you can add the AdditionalValidationRules configuration in the Additional Settings section:

  • Setting name: AdditionalValidationRules
  • Setting value:
{
  "authorize": {
    "requiredParameters": "code_challenge, code_challenge_method",
    "redirectUriScheme": "http,myapp,com.mycompany.myapp",
    "codeChallengeMethod": "S256"
  }
}

Single logout (SLO) behavior

Starting from version 5.20, Identify implements improved Single Logout (SLO) behavior that properly handles native OIDC client sessions independently from browser-based sessions.

Session isolation

Native applications maintain separate session contexts from browser-based OIDC clients:

  • Browser-based OIDC clients: Share Single Sign-On (SSO) context through browser cookies
  • Native OIDC clients: Maintain independent sessions with tokens stored locally on the device

SLO behavior for native clients

When a browser-based OIDC client initiates logout:

  • Browser SP sessions: Affected by the logout request; users are logged out from all browser-based OIDC clients that share the same SSO context
  • Native client tokens: Preserved and not deleted; native applications remain authenticated

Why this matters:

Logging out of a web browser session should not invalidate the authentication state of native applications running on the same device. Native apps have independent lifecycle management and users expect them to remain logged in even after closing browser sessions.

Example client implementations

Safewhere provides sample implementations for native OIDC clients: