@itwin/browser-authorization

Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.

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.