Using 3-legged OAuth Tokens
You can write client applications that use a 3-legged OAuth token with the Automation Service when the code making the call to the Automation API resides on the end-user’s device (for example, a mobile app or web app). You must exercise caution so as not to expose your apps to undue risk. There is a security risk when storing the Client ID or Client Secret on the end-user device (as required when you want to use a 2-legged token), which is the reason to use a 3-legged token. However, there are additional risks that you must consider. This topic describes some of these risks and the facilities that the Automation API offers to mitigate them.
The problem with scenarios involving 3-legged OAuth tokens is that when the end user makes a REST API call, the payer is not the end user, at least not directly. The payer is the app that allows the end user to obtain the 3-legged token. The payer wants to control which APS APIs the 3-legged token is allowed to call. This problem is traditionally solved with scopes. However, scopes can only restrict endpoints; they cannot restrict the request body. A malicious user can change the request body to call a different activity than you intended.
To solve this problem, the Automation API offers the following protections:
- 3-legged tokens can only call the POST workitems operation. 3-legged tokens are not authorized to call any other endpoints.
- Your client can digitally sign the parts of the workitem request message that you want to be tamper-resistant. See the Signatures field in the Workitem. Autodesk offers a utility to sign a string with the right algorithm and parameters.
- Your client can upload the public key for its digital signature into the Automation Service using the PUT users/me operation.
- The Automation API only accepts POST workitems requests accompanied by a 3-legged token if the activityId field is digitally signed (other parts can also be signed, but
activityId
must be signed).
The following steps demonstrate what developers need to do to sign their WorkItems. Before you continue, download the latest Das.WorkitemSigner for Windows from here.
- Generate a public/private key pair using Das.WorkitemSigner.
Das.WorkitemSigner.exe generate mykey.json
- Export the public key into a JSON file using Das.WorkitemSigner.
Das.WorkitemSigner.exe export mykey.json mypublickey.json
- Upload the public key using the PATCH forgeapps id API page.
curl forgeapps/me -X PATCH -d `{"publicKey" : <contents of mypublickey.json>}`
- Generate a digital signature for the activityId you want to call using Das.WorkitemSigner (note, the activity ID must be the fully qualified ID).
Das.WorkitemSigner.exe sign mykey.json <ForgeAppNickNameOrId>.PlotToPdf+<Alias>
- Ship the digital signature with your application and use it in each POST workitems request payload to ensure that only the activity you choose (PlotToPdf, in this example) can be used with the 3-legged token.
These changes aim to improve clarity and structure while maintaining the technical accuracy of the document.