Scoped Tokens are Here !

INTRODUCTION

Tokens are the core of Forge/APS platform's access control mechanism.

Tokens act like a temporary password and grant access to sensitive data and resources, only to authorized users, while keeping the system secure.

Today, we are introducing "Scoped Tokens"

WHAT ARE SCOPED TOKENS ?

Unlike traditional tokens, "Scoped Tokens" are a token that embeds a list of URNs, which restrict what Forge Viewer (now APS) is allowed to view.

When the Forge Viewer wants to read SVF2 derivative files from OSS (Forge Buckets), the OSS permission system decides if the token has access or not.

If yes.... then the Viewer will load the 2D/3D model

if no.... then the Viewer is blocked.

Simple.

The list of URNs, is specified at the time of issuance of a token, and it can’t be changed later.

See our API documentation page, under oAuth, for more details:

scoped tokens api page

HOW TO CREATE A SCOPED TOKEN ?

Let's go through an example of how to create a scoped token.

First, we create a token as before, but instead of 'read:data' as the scope, we will specify a URN as the scope.

Start with a URN of a 3D Model (or 2D). The URN has SVF2 derivative files sitting on a Forge OSS bucket and I want to "secure" this 3D model.

Here is the URN...

dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6dHJhbnN1cmJhbi10ZXN0L3JhY19iYXNpY19zYW1wbGVfcHJvamVjdC5ydnQ

If we "base64 decode" this URN, then it reveals the filename "rac_basic_sample_project.rvt" and the bucket 'transurban-test/', like this...


urn:adsk.objects:os.object:transurban-test/rac_basic_sample_project.rvt

Let's generate a Scoped Token of this URN. Do the following:

> Append "data:read:" to the front of the "base64 decoded" URN.

Like this string...

data:read:urn:adsk.objects:os.object:transurban-test/rac_basic_sample_project.rvt

Now, generate an Access Token, using this new string, and this CURL command (or Postman):

curl --location --request POST 'https://developer.api.autodesk.com/authentication/v1/authenticate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=5K...Tc' \
--data-urlencode 'client_secret=By8j....A3' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=data:read:urn:adsk.objects:os.object:transurban-test/rac_basic_sample_project.rvt'

I run this command and it returns this response containing my new Access Token:

{"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IlU3c0dGRldUTzlBekNhSzBqZURRM2dQZXBURVdWN2VhIn0.eyJ..........I2NH0.WPmB7UUuGaV__n_XOxI_o-Y4pmmm5dIgp3LIssvLEpUR60eKOf1vYBs24OY8Cn1SMyPPEbAQ97z-hpeR3YzqMgUQm54aDXcRUt8_5ctt9HimfwMzcwkIVGpu5OUXDWCPGuo021EhNAnDiMDncRV7C9BL8nB64MkQcyRzmIiHzexsoLiY0Zopa-vJqBhXIYQGy7hlExbql1PbfO6a90X7lwimCd_fkp788LIyXRIwZzO1o9zwGaxQgwfEZ3xG25uXtegcaGcRpWkFC5GI7EiEWDQFQdvDT7Z0QSe5bo6ntSIZ1rMzEaZCqLfigp13bZCv2fmkZXKZuo8_bF77r-qg0g","token_type":"Bearer","expires_in":3599}

NOTE: My example is using v1 oAuth API, but the new v2 oAuth API also works. I have carefully removed my personal key/secret from the command, so add your own and try the command yourself.

Let's debug the Scoped Access Token, using https://jwt.io

The JWT report shows our URN scope (circled in RED) ... great !

HOW TO USE A SCOPED TOKEN ?

Now let's try out our new SCOPED_TOKEN with the Viewer. I run the viewer, and it successfully loads and views my transurban-test/rac_basic_sample_project.rvt 3D model, using this snippet of javascript:

function startViewer( URN ) {
	AV.Initializer({ 
                     accessToken: SCOPED_TOKEN 
                     env: "AutodeskProduction2", 
                     api: 'streamingV2', 
        }, () => {
		  const viewer = new AV.Private.GuiViewer3D( div );
		  viewer.start();
		  AV.Document.load(`urn:${URN}`, (doc) => {
			var viewables = doc.getRoot().getDefaultGeometry();
			viewer.loadDocumentNode(doc, viewables);
		  });
... etc

If I try load/view a different model using the same SCOPED_TOKEN, say... transurban-test/stadium_navis_project.nwd then the Viewer fails - it is blocked access to the derivative files.

PERFECT - My URN's are secured !

BONUS: GROUPS of URNs

I can also create a scoped token on a "group of URNs". I do this by appending URNs together, with a space separator.

Here's an example of a Scoped Token containing 3 read-only URNs, separated by a 'space'...

data:read:urn:adsk.objects:os.object:transurban-test/rac_basic_sample_project.rvt data:read:urn:adsk.objects:os.object:transurban-test/rac_advanced_sample_project.rvt data:read:urn:adsk.objects:os.object:transurban-test/stadium_navis_project.nwd

And... that's a wrap !

CONCLUSION

Using the old 'data:read' scope, my viewer could read any URN within in my Forge App. Now, with Scoped Tokens, I can tighten my security requirements.

Scoped Tokens are a new feature of the APS oAuth and Model Derivative Services and provide a more secure, manageable and compliant way to manage URN access, while avoiding the need to build your own proxy service.

For help, support or questions on Scoped Tokens, feel free to ping me at aps.help@autodesk.com

Book a zoom call with Calendly here: https://calendly.com/michael-beale

Follow me on Twitter: https://twitter.com/micbeale

Tags:

Viewer