What do you mean my authorization scheme isn't supported?

[aruniverse]

tl;dr

If you'd like to use iTwin.js along with the rest of our iTwin Platform APIs, you'll need to change the OIDC Issuing Authority from imsoidc.bentley.com to ims.bentley.com, along with adding the new itwinjs scope under the Visualization API Association in your client's registration at developer.bentley.com

New OIDC Authority

Recently a change was made in the iTwin Developer Portal to simplify authorization and the usage of our APIs; namely consolidating some scopes and the authority.

You might have seen the following error when trying to use one of our API's, "Authorization scheme is not supported", due to a mismatch in the OIDC authority that issues your auth token.

The iTwin Platform currently supports two different OIDC issuing authorities for requesting an access token; imsoidc.bentley.com and ims.bentley.com.

The imsoidc issuer has been the main authority used over the past few years for iTwin.js and issuing tokens that allowed contacting all of the services required to make your application (We'll refer to these as the initial APIs). This authority allowed you to get an access token with the following set of scopes that granted you access to their respective services:

• rbac-user:external-client
• projectwise-share
• imodeljs-router
• general-purpose-imodeljs-backend
• product-setting-service
• context-registry-service:read-only
• imodelhub
• urlps-third-party
• reality-data:read

With the recent release of iTwin Platform APIs, a new OIDC authority has been introduced,  ims.bentley.com. This new authority, initially, issued you an access token that could be used with all of the new iTwin Platform APIs but did not allow you to contact any of the "initial APIs" listed above that iTwin.js still uses. So previously, users would have to manage two different tokens issued by the two different authorities above, one to use the "initial APIs" and another for the iTwin Platform APIs.

This was a pain, so we have introduced a new way of getting an access token for the "initial APIs". We've added the itwinjs scope as a supported scope on the new ims authority. This scope technically wraps up all of the scopes listed above and if you request an access token with just that single scope it will have access to call any and all of the "initial APIs".

So now, the recommended workflow is to always use the new authority, ims.bentley.com, and the itwinjs scope to call any of the "initial APIs". This will allow you to remove from your list any of the 9 scopes above you were previously requesting and then once you start using the new iTwin Platform APIs, it can all be handled with a single access token rather than two, resolving the "Authorization scheme is not supported" error.

To learn more about our platform's authentication workflow, please refer to this overview. You can also inspect your auth token at jwt.ms to learn more.

---

To recap:

Previously

Issuer:

imsoidc.bentley.com

Scopes:

• rbac-user:external-client
• projectwise-share
• imodeljs-router
• general-purpose-imodeljs-backend
• product-setting-service
• context-registry-service:read-only
• imodelhub
• urlps-third-party
• reality-data:read

Now

Issuer:

ims.bentley.com

Scopes:

• itwinjs

---

So what does this mean for you as a developer?

Are you just getting started out with your first application powered by iTwin.js?

If so, you're in luck; both our Web and Desktop viewer templates use the new ims issuer by default. You can follow the getting started guides for Web and Desktop and start building an application powered by iTwin.js and our Platform.

Do you have an existing application?

• Go to the developer portal and select your app.
• Under the Visualization API Association add the itwinjs scope to your app, then click save.
• Update the list of scopes your app requests to add the itiwnjs scope and use the new auth issuer, https://ims.bentley.com. (You can remove any and all of the 9 scopes required for the old imsoidc issuer.)

  1. For Web Apps:

     1. If you're using BrowserAuthorizationClient, the authority will need to point to the new issuer.

        1. If you're using the iTwin Web Viewer, you'll need to update the authConfig object that's passed into the Viewer component to add the authority like so:

           const authConfig: BrowserAuthorizationClientConfiguration = {
               scope: process.env.IMJS_AUTH_CLIENT_SCOPES ?? "",
               clientId: process.env.IMJS_AUTH_CLIENT_CLIENT_ID ?? "",
               redirectUri: process.env.IMJS_AUTH_CLIENT_REDIRECT_URI ?? "",
               postSignoutRedirectUri: process.env.IMJS_AUTH_CLIENT_LOGOUT_URI,
               responseType: "code",
               authority: "https://ims.bentley.com",
             };

           <Viewer authConfig={{ config: authConfig }} ... />

  2. For Desktop Apps:

     1. You'll want to make sure the NativeAppAuthorization singleton is initialized with the issuerUrl pointing to the new issuer.

        1. If you're using the iTwin Desktop Viewer, you'll need to update the electronHost.authConfig object to add the issuer like so:

           const electronHost: ElectronHostOptions = {
               webResourcesPath: path.join(__dirname, "..", "..", "build"),
               rpcInterfaces: viewerRpcs,
               developmentServer: process.env.NODE_ENV === "development",
               ipcHandlers: [ViewerHandler],
               authConfig: {
                 clientId,
                 scope,
                 redirectUri: redirectUri || undefined,
                 issuerUrl: "https://ims.bentley.com",
               },
             };

           await ElectronHost.startup({ electronHost });

     2. You'll need to clear out the cached auth token in Windows Credential Manager or MacOS KeyChain. They key will include your desktop app's client id.

        1. Currently you'll need to do this every time you change your desktop app's required scopes.

  3. For Service Apps (using client-credentials):

     1. You'll need to add an env var for your service, imjs_itwin_platform_authority and set it to the new issuer.