Choosing an OAuth 2.0 Grant Type

Overview

The first step to implementing an OAuth 2.0 solution for your application or integration is to select the proper OAuth 2.0 authorization grant type for your use case. The grant type, or means by which a client application acquires an authorized access token, is used to authenticate a request to a Procore API endpoint. Normally, you determine the proper grant type based on the architecture and framework of your particular project. Let’s outline the OAuth 2.0 grant types supported by the Procore API.

Authorization Code Grant (Web Server Applications)

Note: It is important to keep in mind that when you create any new application on the developer portal, OAuth 2.0 credentials for the Authorization Code grant type are provided automatically by the system. You do not need to explicitly select or specify this grant type in your application configuration.

If you are developing a web server-based solution, then you will want to implement the Authorization Code grant type. Web server applications are written in a server-side language where the source code of the application is not visible to the public. This means the application is able to take advantage of the Client Secret when communicating with the authorization server, which provides more robust security. The authorization grant type is considered a “redirection-based” flow. As such, your application must be capable of interacting with the user’s web browser as well as receiving incoming requests (via redirection) from the Procore authorization server.

Here is a diagram illustrating the flow for the Authorization Code grant type. Let’s walk through each step in the flow.

Auth code grant type

  1. When a Procore user accesses your application, it initiates the authorization grant flow and redirects the user’s web browser to the Procore API Grant App Authorization endpoint (/authorize), so the user can authenticate.
  2. The Procore authorization server authenticates the user (via the browser) and displays a consent dialog where the user can choose to allow or deny your application access to their data in Procore.
  3. Once the user allows access, the Procore authorization server redirects the user back to your application with an Authorization Code that can only be used once and has a 10 minute expiration.
  4. Your application then sends the Authorization Code to the authentication server and asks to exchange it with an access token. This is accomplished using the /token endpoint. When making this request, your application authenticates with the Procore server using your Client ID and Client Secret.
  5. The Procore authentication server authenticates your application, validates the Authorization Code and responds back with the access token.
  6. Your application can now use the access token to make calls to the Procore API on behalf of the user.

Using the State Parameter to Enhance Security

The OAuth 2.0 specification provides for enhanced security through the use of the state parameter. By incorporating the state parameter into the Authorization Grant flow for your application, you can reduce the likelihood of a Cross-site Request Forgery (CSRF) attack. CSRF is an exploit in which an attacker causes the user-agent of an end-user to follow a malicious URI to a trusting server. The state parameter is intended to preserve a state object set by the client in the Authorization request and make it available to the client in the response. The client can then verify the state parameter value in the response - something an attacker could not know. If the client successfully verifies the value returned, it will reject authorization responses that were generated as the result of requests by third-party attackers trying to log in as the user in the background without the user’s knowledge.

In the context of the Procore API, the state parameter is passed with the GET request to the Grant App Authorization endpoint. The state parameter is an arbitrary alphanumeric string that can represent any value you choose. Your application uses the state request parameter to deliver a unique value to the Procore authorization server when making an authorization request. Once authorization has been granted by the end-user, the Procore authorization server redirects the end user’s user-agent (browser) back to your application with the required binding state value included as a query parameter in the redirect URI along with the authorization code.

Though not required for implementing OAuth 2.0 in your Procore integration, we highly recommend including the state parameter in your authentication architecture.

Client Credentials Grant (Data Connection Applications, userless access)

If you are developing an application or integration that does not rely on or require access authorization from a specific Procore user, then you will want to implement the Client Credentials grant type using a Developer Managed Service Account (DMSA). The Client Credentials grant type is used for data connection integrations between Procore and other systems. If you define company level and/or project level tool permissions for your DMSA application, your client credentials will be generated by the system and can be accessed in the OAuth Credentials section of the Manage App page. See OAuth 2.0 Using Client Credentials and Developer Managed Service Accounts for additional information.

Here is a diagram illustrating the flow for the Client Credentials grant type. Let’s walk through each step in the flow.

Client grant type

  1. Client requests an access token from the Procore Authentication Server using the Client ID and Client Secret credentials associated with the DMSA in Procore.
  2. The Procore Authentication Server returns a JSON response that includes the access token and other supporting data.
  3. Your application can now use the access token to make calls to the Procore API.