Using OAuth 2.0

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

Newforma Konekt 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 Newforma Konekt 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:

Entity	Role
Application	It is a web or desktop application responsible for making API calls.
Authentication server	The Newforma Konekt authentication server is responsible for authenticating a user (user sign in).
Authorization server	The Newforma Konekt authorization server is responsible for authorizing an application to access the Newforma Konekt and BCF APIs on behalf of users.
User	This is a typical Newforma Konekt user.
Newforma Konekt server	It exposes the Newforma Konekt API and BCF API endpoints.
Protected resource	A resource returned or modified by the API endpoints.

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. Newforma Konekt 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 Newforma Konekt 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 Newforma Konekt 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 Newforma Konekt 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 Newforma Konekt 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.

Code Challenge Generation Methods
S256	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 

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

Parameters
client_id	Required The client ID for your application
redirect_uri	Required 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. http://127.0.0.1:port 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.
response_type	Required Set the parameter value to code for installed applications.
scope	Required 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 Newforma Konekt 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.
code_challenge	Recommended The code_challenge value computed above.
code_challenge_method	Recommended The only supported value for this parameter is S256.
state	Recommended 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

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:

Fields
client_id	Required The client ID for your application.
client_secret	Required The client secret computed earlier.
code	Required The authorization code received in step 5.
code_verifier	Required The code verifier value created earlier.
grant_type	Required The value of authorization_code.
redirect_uri	Required The same redirect URI as in step 2.

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 Newforma Konekt 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/