Using 3-legged OAuth Tokens with Design Automation
You can write client applications that use a 3-legged OAuth token with Design Automation when the code making the call to an FDA REST 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 Design Automation 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 end points; 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, FDA offers the following protections:
- 3-legged tokens can only call the POST workitems endpoint. 3-legged tokens are not authorized to call any other APIs.
- 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 FDA using the PUT users/me API.
- FDA 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 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 `{'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 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.