Using OAuth 2.0

Working with the BIM Track API or BCF REST APIs, your application will access endpoints on behalf of a BIM Track user. The users will need to authenticate with BIM Track in order to confirm their identity and give your application permission to access data and perform actions on their behalf.

BIM Track uses the OAuth 2.0 protocol to give third-party applications access to the data. OAuth 2.0 is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords. This mechanism is used by companies to permit the users to share information about their accounts with third party applications or websites.

Become a BIM Track partner and get started with OAuth by filling out this form this form.

Useful resources

If you need more information about the protocol itself. You can review the official specification here: RFC 6749 - The OAuth 2.0 Authorization Framework. You can get your hands on the OAuth 2.0 Simplified book by Aaron Parecki. Also you can check out these other resources How to Use OAuth2, Google Sample OAuth Desktop App Sample and OAuth 2.0 for Mobile & Desktop Apps for more detailed usage implementations.

OAuth roles

The various OAuth roles are:

Definitions

Here are some definitions to help guide you.

• Client ID: its a public unique identifier that identifies the application interacting with the authorization server.
• Client secret: it’s a private code given along with the client ID acting like a password. It must be securely stored because it is only known by the application and the authorization server.
• Authorization code: it is a code, only used once, to perform an access token request.
• Acces token: it is a code used to perform API requests on behalf of a user.
• Refresh token: it is a code used to request a new access token when the previous one has expired.
• PKCE: it is an acronym that stands for Proof Key for Code Exchange. It offers a more secure way to obtain access tokens and thus preventing attackers to get them. It incorporates a code verifier and challenge in the authorization process to tighten  the security.
• Code verifier: it is a cryptographically random string used by the authorization server to correlate the access token request with a previously made authorization request.
• Transformation or code challenge method: it indicates the algorithm applied on the code verifier to obtain the code challenge.
• Code challenge: it is a challenge derived from the code verifier (using a transformation method).

Proof Key for Code Exchange (PKCE)

There are two types of authorization code flows: standard and PKCE enhanced. When native and single-page applications request access tokens, some security concerns arise and they are not covered by the standard authorization code flow alone. BIM Track only implements the PCKE enhanced authorization code flow.

OAuth 2.0 provides a version of the authorization code flow that uses the Proof Key for Code Exchange (PKCE) where the specifications can be found here: OAuth 2.0 RFC 7636.

Authorization process

To get started, follow these instructions.

1. You need to provide your application name to the BIM Track Team. The name will be presented to the user on the authentication page.
2. During authorization code flow, the authorization server requires a redirection URI to redirect the user when the authentication is completed. The URI is provided by your application waiting for a request from the server. It is a URI formed like the following http://127.0.0.1:port. If you need something different for special needs or constraints, you must to provide us the URI you need to add the support in the authorization server.
3. The BIM Track team will then provide you the client ID and secret.
4. When applicable, it is strongly recommended to store the client secret in a secure encrypted storage. For web applications, it is recommended to use the backend storage. For desktop applications, we recommend using encrypted storage or user a proxy service on a backend (if applicable).

The authorization server is located here: https://auth.bimtrackapp.co.

The BIM Track API endpoints are located here: https://api.bimtrackapp.co. The documentation can be found here: https://bimtrackapis.readme.io/docs.

The BCF API endpoints are located here: https://bcfrestapi.bimtrackapp.co. The documentation can be found here: https://bcfrestapi.bimtrackapp.co/swagger/index.

N.B.: It is not recommended to call the BIM Track and BCF REST APIs within a Javascript client application (running in the browser). We would strongly suggest implementing a proxy service on the backend to perform the actual API calls.

PKCE Enhanced Authorization Code Flow

Here is a description of the steps to acquire the access token for making calls to the APIs:

Step 1. The user clicks on the Sign In button.

Step 2. The application sends the authorization request to the authorization server endpoint. 

Create the code verifier

A code_verifier is a high-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters.

The code verifier should have enough entropy to make it impractical to guess the value.

Create the code challenge

Two methods of creating the code challenge are supported.

To obtain the user authorization, send a request to the authorization server at 

https://auth.bimtrackapp.co//connect/authorize.

Sample authorization request URL

https://auth.bimtrackapp.co/connect/authorize?

response_type=code&

scope=BIMTrack_Api%20openid&

redirect_uri=http%3A%2F%2F127.0.0.1%3A18215&

client_id=your_client_id&

state=-XGJum969rPJU3NUmzwYUuyrGR7S098u_SQMuxcu1WY&

code_challenge=v0jvOB_WGqP349D-ahfv7V5-ANvZfV7gMai1x-Obsj0&

code_challenge_method=S256

Step 3. User gets redirected to the authentication server page to enter his credentials.

Step 4. User enters his credentials and click on the Sign in button and give his consent to the application.

Step 5. Once authorized, the authorization server redirects the user to the redirect_uri and sends back an authorization code to the application.

Step 6. The application sends the access token request.

To exchange an authorization code for an access token, call the https://auth.bimtrackapp.co/connect/token endpoint and set the following parameters:

Sample access token request URL

POST /connect/token HTTP/1.1

Host: https://auth.bimtrackapp.co

Content-Type: application/x-www-form-urlencoded

code=4f46b8cc568bf2426263e6ebcc5300b3ba5da7e84ac829c826635bdce8bd2196&

client_id=your_client_id&

client_secret=your_client_secret&

redirect_uri=http%3A%2F%2F127.0.0.1%3A18215&

grant_type=authorization_code

Step 7. The authorization server responds by sending the access tokens. If the scope offline_access was provided earlier, the response will also contain a refresh token. This token is used by your application to refresh your access token when it expires. The access tokens have a 2 hours life time. When applicable, it is strongly recommended to store the access and refresh token(s) in a secure encrypted storage. For web applications, it is recommended to use the backend storage. For desktop applications, we recommend using encrypted storage (when there is no backend available).

Step 8. The application can now make calls to the API endpoints using the access token.

Sample API request URL

GET /v3/hubs HTTP/1.1

Host: https://api.bimtrackapp.co

Authorization: bearer access_token

Step 9. The BIM Track server responds by sending back the requested protected resource.

Keeping the access and refresh tokens securely stored allows subsequent reuse of the same session. This improves the user experience by removing the need to re-authenticate every time the application is restarted.

N.B.: All the details about the requests and responses content can be found in the OAuth 2.0 links provided at the top of this section.

The following libraries may be used for many interactions with endpoints defined OpenID Connect and OAuth:

• https://identitymodel.readthedocs.io/en/latest/index.html
• https://openid.net/developers/certified/