@itwin/browser-authorization

Description

The @itwin/browser-authorization package contains a browser based client for authorization with the iTwin platform.

Usage

Create a new instance of BrowserAuthorizationClient, passing in needed credentials:

const client = new BrowserAuthorizationClient({
  clientId: // find at developer.bentley.com
  redirectUri: // find/set at developer.bentley.com
  scope: // find/set at developer.bentley.com
  authority: // ims.bentley.com
  postSignoutRedirectUri: // find/set at developer.bentley.com (see note below)
  responseType: "code",
  silentRedirectUri: // find/set at developer.bentley.com
});

Important! The above postSignoutRedirectUri will not fully work if the url ends with /logout and https is not supported on your site. For local development where https is less common, we suggest using /logout-local for the url path.

The most common way to use an instance of BrowserAuthorizationClient will depend on your specific application and workflow. Here's one common way:

// will attempt to sign in silently,
// and then via redirect if not possible.
await client.signInRedirect();

Instead of a redirect, you may want to trigger a pop up to handle the sign in process:

await client.signInPopup();

After the user signs in, they will be redirected to the redirect url specified in your oidc configuration (developer.bentley.com) Once on that page, you must call:

await client.handleSigninCallback();

to complete the process. Once back on your initial page, the call to client.signInSilent will succeed and you should be authorized.

If the callback occurs on a page where the configured client is not available, you can use the static method to complete the process:

await BrowserAuthorizationClient.handleSigninCallback();

// This library defaults to localStorage for storing state.
// To use sessionStorage (or another Storage object), you can pass it as an argument.
// If overriding the default localStorage, also set the stateStore via client.setAdvancedSettings({stateStore: yourStore})
await BrowserAuthorizationClient.handleSigninCallback(window.sessionStorage);

This will pull the client configuration from localStorage, using the state nonce provided by OIDC to select the proper configuration.

Other notable methods: client.signOutRedirect() - starts the signout flow via redirect client.signOutPopup() - starts the signout flow via popup. client.setAdvancedSettings(userManagerSettings) - Allows for advanced options to be supplied to the underlying UserManager.

Authorization Overview

For information about the browser authorization workflow please visit the Authorization Overview Page.

Running integration tests

Ensure you've run rush update (or rush install) and rush build
Create an .env file based on .env.example - ask Arun G or Ben P for the values.
rush test:integration will run integration tests for the entire repo.
rushx test:integration runs the tests only in the Browser package.
Playwright options are in playwright.config.ts (head-ful vs headless, timeouts, etc).
The tests start the /test-app using parcel before running.
To run only the test app: rushx test:integration:start-test-app and access localhost:1234 in your browser.