One scope to call them all

By Caleb Shafer and Arun George

NOTE: This post is only applicable to iTwin.js 2.0. For iTwin.js 3.0, please refer to this announcement for new scope requirements.

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, and add 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 issuing tokens for contacting all of the services required for your iTwin.js 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 (granting 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 an access token that could be used with the new iTwin Platform APIs, but not with the "initial APIs" listed above. So up until now, users would have to manage two different tokens issued by these two different authorities.

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 will single-handedly allow you 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 any of the 9 scopes above (that you were previously requesting) from your list. And then once you start using the new iTwin Platform APIs, it will all be handled with a single access token rather than two. This will also resolve the previously mentioned "Authorization scheme is not supported" issue.

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 itwinjs 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.)

For Web Apps:

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

• 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:

For Desktop Apps:

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

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

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

• Currently, you’ll need to do this every time you change your desktop app’s required scopes.

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.