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.
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.
The various OAuth roles are:
|Application||It is a web or desktop application responsible for making API calls.|
|Authentication server||The BIM Track authentication server is responsible for authenticating a user (user sign in).|
|Authorization server||The BIM Track authorization server is responsible for authorizing an application to access the BIM Track and BCF APIs on behalf of users.|
|User||This is a typical BIM Track user.|
|BIM Track server||It exposes the BIM Track API and BCF API endpoints.|
|Protected resource||A resource returned or modified by the API endpoints.|
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.
To get started, follow these instructions.
- You need to provide your application name to the BIM Track Team. The name will be presented to the user on the authentication page.
- 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.
- The BIM Track team will then provide you the client ID and secret.
- 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.
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.
|Code Challenge Generation Methods|
The code challenge is the same value as the code verifier generated above.
code_challenge = code_verifier
The code challenge is the Base64URL (with no padding) encoded SHA256 hash of the code verifier.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
To obtain the user authorization, send a request to the authorization server at
The client ID for your application
Used by the authorization server to redirect the user when the authentication is completed. Your application will wait for a request from the authorization server.
If this value doesn't match an authorized URI, you will get a invalid redirect_uri error.
Query your platform for the relevant loopback IP address and start an HTTP listener on a random available port. Substitute port with the actual port number your app listens on.
Set the parameter value to code for installed applications.
A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. The supported values are:
BIMTrack_Api: to access the BIM Track API endpoints.
BcfWebApi:to access the BCF API endpoints.
offline_access: to request a refresh token.
openid: this is required. It indicates that the application intends to use OIDC to verify the user's identity.
The code_challenge value computed above.
The only supported values for this parameter are S256 or plain.
Specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response. The server returns the exact value that you send as a name=value pair.
You can validate the response to additionally ensure that the request and response originated in the same browser, providing protection against attacks such as cross-site request forgery.
Sample authorization request URL
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:
The client ID for your application.
The client secret computed earlier.
The authorization code received in step 5.
The code verifier value created earlier.
The value of authorization_code.
The same redirect URI as in step 2.
Sample access token request URL
POST /connect/token HTTP/1.1
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
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: