As I mentioned in my previous post, BIM 360 uses the following Forge API’s:
- Authentication (OAuth)
- BIM 360 (HQ) API
- Data Management API
- Model Derivatives API
So far, my focus has been on a big picture discussion about Forge in respect to BIM 360. Let’s shift a focus a little and look at each component level. As a starting point, let’s take the first one, Authentication or OAuth.
OAuth in Simple Words
What is OAuth, anyway? If you are genuinely new to the web development world, I’m sure OAuth sounds like yet another buzzword. OAuth is an authorization framework that allows a third party application to obtain an access to data stored in the cloud. The name OAuth comes from Open standard for Authorization. It’s an Internet standard developed by Internet Engineering Task Force (IETF). It is implemented by companies like Facebook, Google and Microsoft to support API’s. Forge uses OAuth 2.0, a new version of OAuth framework. It is used as a part of Authentication process of verifying the user and/or application.
2-Legged vs. 3-Legged
Forge supports two type of Authentication workflow: two-legged and three-legged. Here, “leg” implies “party”; i.e., 2-legged means two parties are involved during the authentication process, while 3-legged means three parties. Both types require client ID and client secret which you can obtain from the developer portal (https://developer.autodesk.com); you first register your app, and then you can get them from My Apps page.
In 2-legged, two parties are involved in the process: a third-party application and Forge authorization server. You use client ID and client secret to verify the access. In a way, it is analogous to the user ID and password except that it’s not in the user context. (It is important that you keep the client secret in a safe place as having it allows anybody to access your data.) 2-legged is used for application-to-application context or sometimes called business-to-business or B2B relations.
For example, in the context of BIM 360 HQ API, a typical use case scenario may be for a company or account owner to automate project creation and populate project members based on the directories which exist in the back office. This kind tasks may become tedious if you need to do manually as the number of projects and projects members become large. In this scenario, API user is limited to a small number of personnel with administrative privilege. Implementation wise, this workflow is rather straightforward.
Figure 1 below illustrates 2-legged authentication workflow. Notice that there two parties are involved with this workflow: third party application and authorization server.
Figure 1. 2-legged authentication workflow.
- An 3rd party application (A) send a client id and client secret to the authentication server (B).
- The authentication server (B) verify the client id/secret and return a token to the third party application (A)
3-legged is a little more complex. In addition to a third party application and the Forge authorization server, the end user is involved in the authorization process (thus the name 3-legged, meaning three parties). This method is used in the user context. During this authentication method, it redirects the user to accounts.autodesk.com to verify the user and obtain the consent to allow the third party application to access the data on behalf of the user.
During the 3-legged process, the application makes two requests to the server: (1) to ask for the authorization from the user, and (2) to request for an access token. During the process of the first request, the server prompt the end user for the verification. Figure 2 below illustrates 3-legged authentication workflow. Notice that there are three parties in this workflow: third party application, authorization server and the end user.
Figure 2. 3-legged authentication workflow
- A 3rd party application (A) send an client id and callback URL to the Authorization server (B)
- Authorization server (B) presents login page to the user (C) of the application
- The user (C) logins using Autodesk ID and agree on consent to grant access to the third-party application to their data on his/her behalf.
- Authorization server (B) returns “authorization code” to the registered callback URL of the application (A)
- 3rd party application (A) request authorization server (B) for “access token” using “authorization code”.
- The server (B) returns “access token” to the 3rd party application (A)
Notice in this workflow, the user does not need to expose his/her password to the third party application, providing more secure authentication method.
Implementation wise, 3-legged is more complex than 2-legged, however. You should be aware that this workflow is designed for web services. The process requires to have a callback URL. Even if you are writing a desktop app, its implementation normally involves at least the authorization part on a server side.(*1)
*1) There has been some discussion about documenting “best practice” for desktop application. We hope to provide an example in near future.
Important: In both types, it is important to keep the client secret in the safe place. You should never share the client secret. Typically, you should keep it on a server side, not at client machines.
OAuth for BIM 360
At the time of this writing, BIM 360 supports the authentication as follows:
- HQ – uses 2-legged only. You also need to register your client ID in HQ
- Docs – uses 2-legged and 3-legged. You need to register your client ID in HQ
- Team – uses 3-legged.
Both 2- and 3-legged require to create (or register) your app through developer.autodesk.com. For detailed instruction about creating your app, please refer to this page:
HQ and Docs require additional steps to have an API access to a specific account through HQ UI: https://bim360enterprise.autodesk.com) >> [Account Settings] menu >> [Apps & Integrations] Tab. For a step-by-step instruction about this process, please refer to this post:
BIM 360 Team does not require to go through HQ nor any other special activation process. Anybody can access through API.
- OAuth 2.0 Authorization Fromework specification
- List of OAuth providers