CONNECTION Client Integration in iTwin Studio

iTwin Studio can leverage the CONNECTION Client for seamless authentication when specific conditions are met. This integration provides a better user experience by reducing sign-in prompts when users are already authenticated with the CONNECTION Client.

Prerequisites

For CONNECTION Client integration to work, all of the following conditions must be satisfied:

1. Windows Platform Required

The integration only works on Windows platforms. macOS and Linux are not supported.

2. CONNECTION Client Installation

The CONNECTION Client must be installed on the system.

3. OIDC Client Configuration

Your OIDC client must be configured with a redirect URI that follows the CONNECTION Client protocol handler format. This special protocol handler enables communication between iTwin Studio and the CONNECTION Client.

Redirect URI Format

The redirect URI must follow this specific pattern:

com-bentley-cc-{GPRID}://connectionclient-ts-callback

Where {GPRID} is your product’s GPRID (e.g., 3441 for iTwin Studio Visualizer). If you don’t have a GPRID yet, use a unique number.

Example Configuration in app.config.json:

{
  "appId": "appId",
  "authentication": {
    "clientId": "clientId",
    "redirectUri": "http://127.0.0.1:33386/signin-callback/;com-bentley-cc-3441://connectionclient-ts-callback",
    "scopes": "openid enterprise map-layer provision-service itwin-platform offline_access"
  },
  "gprId": "3441"
}

Important:

• The redirect URI must be registered both in your app configuration and with your OIDC provider
• Use your product’s GPRID in the protocol handler for consistency
• Include other redirect URIs (like localhost) for fallback scenarios

How It Works

When all prerequisites are met, iTwin Studio will:

1. Automatically detect the CONNECTION Client installation
2. Check region compatibility between iTwin Studio’s configuration and CONNECTION Client’s environment
3. Use the CONNECTION Client’s authentication instead of prompting for browser-based sign-in
4. Silently refresh tokens using the CONNECTION Client when needed

Region Compatibility

iTwin Studio performs a compatibility check between:

• The issuer URL in your app configuration
• The CONNECTION Client’s current environment (QA vs Production)

If the environments don’t match, iTwin Studio will fall back to the standard browser-based authentication. For more information on how to switch environments, see Using CONNECT Client Environment Switcher.

[!IMPORTANT] Older versions of the CONNECT Client Environment Switcher may not properly set the region information, causing the compatibility check to fail even when environments are correctly configured. If you encounter region compatibility failures, ensure you’re using the latest version of the CONNECT Client Environment Switcher.

Fallback Behavior

If any prerequisite is not met, iTwin Studio will automatically fall back to the standard browser-based authentication. This ensures the application continues to work even when Connection Client integration is unavailable.

Troubleshooting

CONNECTION Client Not Being Used

If you expect CONNECTION Client integration but it’s not working, check:

1. Platform: Verify you’re on Windows
2. CONNECTION Client Status: Confirm CONNECTION Client is installed and running
3. Redirect URI: Verify your OIDC client has a redirect URI following the format com-bentley-cc-{GPRID}://connectionclient-ts-callback
4. Region Compatibility: Check that your issuer URL matches CONNECTION Client’s environment
5. CONNECT Client Environment Switcher Version: Ensure you’re using the latest version of the CONNECT Client Environment Switcher. Older versions may not properly set region information, causing compatibility checks to fail

Logs and Debugging

iTwin Studio logs detailed information about the CONNECTION Client integration process. Look for log entries containing:

• getAuthorizationClient: Attempting to use CCAuthorizationClient
• Region compatibility check passed/failed
• Failed to initialize CCAuthorizationClient, falling back to StudioElectronAuthorizationClient