Developer Managed Service Accounts

Deprecation of Traditional Service Accounts

Traditional Service Accounts were deprecated on December 9, 2021. All traditional service accounts will be sunset on a future date to be announced. As a result of this deprecation, developers of data connection applications that currently use traditional service accounts are required to update their applications to use DMSAs, and customers will be required to install these updated applications before the sunset date. See Deprecation of Traditional Service Accounts for additional information.

Background

For developers building applications using data connection components we recommend leveraging the new Developer Managed Service Accounts (DMSA) feature as a streamlined approach to providing Procore administrators the ability to easily install and provision data connection applications in their company accounts. The DMSA feature allows developers to specify the exact company and project level tool permissions that are required for their application to run properly on the Procore platform. Company administrators can specify which projects the App can access using those permissions.

A DMSA is automatically created in the Company Directory tool when a company administrator installs a data connection App from the Procore App Marketplace, or during a custom install from within Procore. During the installation process, the company administrator can select which projects the App is allowed to run in. Once the App is installed, the company administrator can add or remove permitted projects as needed.

Developers utilize DMSAs to provide a more convenient and secure alternative to traditional service accounts that must be created, configured, and managed manually by a company administrator.

Benefits of Using Developer Managed Service Accounts (DMSAs)

There are a number of benefits to be gained by using DMSAs over traditional service accounts:

• Simplified App Management - DMSAs are installed and managed by company administrators using the App Management feature in the Company Admin tool. The Directory user associated with the DMSA is automatically created as part of the application installation process. With traditional service accounts, company administrators have to manually create and manage the account and its access permissions, which requires additional communication and coordination with the third-party developer to get the application installed and configured.

• More Secure Permissions Management - All required company level and project level tool permissions for a given DMSA application are defined in an application manifest that is applied to your company account during the installation process. When an application incorporates new functionality and releases an updated version, the developer can request new permissions via the upgrade process to be reviewed and approved.

• Improved Project Access Control - During the installation and configuration process, company administrators select exactly which projects the DMSA application is allowed to use. With traditional service accounts, project access is configured and managed manually by the company administrator, which can be time consuming and costly, and may be less secure as described below.

• Better Insight on Application Usage - Because DMSAs are installed using App Management, company administrators have visibility into application usage in the form of application metrics such as the number of API requests, which users have installed and/or used an application, which projects are permitted to use an application, and more With traditional service accounts, such metrics are neither gathered nor accessible.

Risks Associated with Traditional Service Accounts

Installing and using applications that utilize traditional service accounts comes with the following risks:

• Unsecured Transmission of API Credentials - Because a traditional service account is created manually in Procore by a company administrator, the unique set of generated API credentials (client_id and client_secret) must be provided back to the developer in order to successfully complete the integration setup. The transmission of this sensitive information can unfortunately occur through unsecured means such as email, text message, etc., leaving company data potentially vulnerable.

• Lack of Usage Data - If a traditional service account becomes compromised, it is difficult to track where it is being used because the account does not generate usage data.

• Potential for Human Error - The requirement to manually configure and manage the permissions associated with a traditional service account can be error prone and lead to unexpected application behavior.

How does a DMSA differ from a traditional service account?

Here are some of the primary differences between DMSAs and traditional service accounts.

Building a Data Connection App with DMSA

The following sections provide step-by-step instructions for creating a new data connection App that utilizes a DMSA. You can also view this short video demonstration that walks through the process.

Create a New App

(Note: If you have an existing App that does not currently have an OAuth component defined in the manifest, you do not need to create a new App. You can skip this step and use your existing App.)

1. Open your browser and navigate to the Developer Portal landing page.
2. Click Sign In to log in to your Developer Portal account.
3. Navigate to the My Apps page and click Create a New App. The Create New App dialog displays.
4. Enter an App Name. This will be the name you use to refer to your application internally within your organization.
5. Click Create. A development sandbox is generated for your new App. You will receive an email notification when your new sandbox is ready.

Add OAuth Component with ‘client_credentials’ Grant Type

DMSA-enabled data connection Apps specify the OAuth component grant type as client_credentials in your App manifest. Use the following steps to add an OAuth component to the manifest and define the grant type. See Creating an App Manifest for additional information on manifest structure and format.

1. In the Developer Portal, navigate to the Manage Manifests panel for your App.
2. Click Create New Version.

3. To add an OAuth component to your manifest, click Copy Code Snippet under Data Connection.

   

4. Paste the code snippet into the manifest editor in the components section.

5. Enter client_credentials for the component grant_type.

   

Specify Tool Permissions Using Permission Builder

Once you have defined the grant type for your OAuth component as client_credentials, you can use the Permission Builder to specify the company level and project level tool permissions that are required to install and use your application.

1. On the Create New Version panel, click Open Builder to display the Permission Builder.

   

2. On the Company tab, define the required permission levels (Read Only, Standard, or Admin) for each tool that is accessed by your App.
3. Repeat the previous step on the Project tab to define project tool permissions.

4. Click Update Manifest. The OAuth component in your manifest is updated with the permissions you defined in the Permission Builder.

   

5. Click Create to save your updates and create the new version of your manifest.

Promote Updated Sandbox Manifest to Production

After you have successfully tested and validated your updated manifest in the development sandbox environment, you can promote it to the production environment and use your production OAuth credentials with your App. See Promoting a Sandbox Manifest to Production for additional information.

App Installation and Management

DMSA-enabled Apps are installed by Procore company administrators either from the Procore App Marketplace or as custom installations. See Install a Data Connection App from the Marketplace and Install a Custom App.

During the installation process, the company administrator is given the opportunity to add one or more permitted projects that the App will be allowed to access.

The App will only have access to the data in these permitted projects. After the App is installed, company administrators can use the App Management feature in Procore to add/remove permitted projects as needed. See What is App Management?, Add a Permitted Project to a Data Connection App, and Remove a Permitted Project from a Data Connection App.

Implications of Granting Directory Admin Permissions to Apps

Company administrators are strongly cautioned against granting admin access to the Company level Directory tool to applications using DMSAs or traditional service accounts. Applications with this highest level of access have the ability to make changes that can adversely affect all the tools across an entire project or all the projects across your organization’s entire Procore company account. While some applications may require this to function, we recommend thoroughly reviewing the need for the integration and understanding the impact prior to allowing.

Common Questions About DMSAs

What do I need to change on the backend for my integration to work?

The backend for your integration needs to change in the following ways.

• A new OAuth component must be defined in the application manifest with a grant type of client_credentials.
• Required tool permissions for the application must be specified using the Permissions Builder.
• Calls to the Procore API must use the DMSA client_id and client_secret for authorization and authentication.
• Must include the Procore-Company-Id request header when making calls to the /rest/v1.0/me or /rest/v1.0/companies endpoints. See Using Developer Managed Service Accounts with MPR for additional information.

How do we see which companies have the App installed?

Installation metrics are captured and available for viewing and downloading from your application page on the Procore developer portal. See Working with App Metrics for additional information. In addition, the following steps can be used to retrieve the list of company accounts in which your DMSA application has been installed.

1. Use the DMSA production client ID and client secret to obtain an API access token.
2. Call the List Companies endpoint using that API access token to retrieve the company accounts in which the DMSA application is installed.

How do I make sure users don’t access the wrong company’s data?

The same DMSA credentials created for your data connection application can also be used with the Authorization Code Grant Flow. In this case, the access token you receive is for a specific logged in user, rather than for the DMSA Directory user. Before showing a user any specific company data or allowing them to trigger actions using your DMSA app, first have them sign in using the authorization code grant flow and check that they are a user on the correct company using the List Companies endpoint. See Handling Multiple Companies for additional information.

How is API authentication handled on the Procore platform?

Applications built on the Procore platform use the industry standard OAuth 2.0 Authorization Framework for authentication with the API. The Procore API supports the following two authorization grant types, or authentication flows:

• Client Credentials (DMSAs and traditional service accounts) - Most data connection applications use this grant type for authentication with the API. With the Client Credentials grant type, a single set of API credentials is used (via a DMSA or traditional service account) to authenticate with the Procore API. Access to tools and data on the Procore platform is governed by the permissions settings associated with that one account. As a result, developers and company administrators can specify the exact tools and projects an application has access to. This is the preferred approach for data connection applications. For additional information on the Client Credentials grant type, see Using the OAuth 2.0 Client Credentials Grant Type.

• Authorization Code (user login flow) - Web server and browser-based applications often use this grant type for authentication with the API. With the Authorization Code grant type, the application operates on behalf of the currently logged in user when authenticating with the Procore API. In this scenario, the application assumes the permissions of the logged in user and has access to any tool, project, or data that particular user is allowed to interact with. Because permissions governance can be challenging under this grant type, it is not recommended for data connection applications. For additional information on the Authorization Code grant type, see OAuth 2.0 Authorization Code Grant Flow.

Procore company administrators are ultimately responsible for managing the permissions of their directory users regardless of the authorization grant type used by an integration - authorization_code (logged in user’s permissions) or client_credentials (service account/DMSA permissions).

When using DMSA client credentials and authorization code grant flows in the same application, how do I determine if the DMSA Directory user and the logged in user have access to the same projects?

You can make two separate calls to the List Projects endpoint - one using the client credentials flow and one using the authorization code flow.

For the DMSA Directory User:

• Make a POST call to the Get or Refresh an Access Token endpoint with a request body formatted as follows:

{
  "grant_type": "client_credentials",
  "client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

• Make a GET call to the List Projects endpoint using the retreived access token for authorization.

For the Logged in User:

• Make a GET call to the Grant App Authorization endpoint specifying response_type=code as a query parameter.
• With the retrieved authorization code, make a POST call to the Get or Refresh an Access Token to obtain an access token.
• Make a GET call to the List Projects endpoint using the access token for authorization.

The response objects from these two call sequences can then be compared by your application to determine which projects the DMSA Directory user is able to access, and which projects the logged in user is able to access.

What is the Procore Platform ‘Shared Responsibility Security Model’?

As a Software as a Service (SaaS) provider, Procore follows a shared responsibility model in the context of platform security.

• Customers are responsible for the integrations they install, permissions they approve for those integrations to use, and any changes they make to the directory users (DMSA or traditional) associated with those integrations outside of what Procore provides.
• Partners/Developers are responsible for the handling of credentials, the code that calls the API and what they do with the data. The customer provides the keys to the Developers to be used by the Developers.
• Procore is responsible for providing developers a means to request permissions of customers via OAuth and customers the ability to install and manage applications.