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 define which projects the application can access using those permissions. Developers utilise DMSAs to provide a more convenient and secure alternative to traditional service accounts. Company administrators benefit from DMSAs through improved application management and better visibility into application usage.
deprecation of traditional Service AccountsTraditional 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 install these updated applications before the sunset date. See Deprecation of Traditional Service Accounts for more details.
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 co-ordination 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 utilise 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 behaviour.
How does a DMSA differ from a traditional service account?
Here are some of the primary differences between DMSAs and traditional service accounts.
|Developer Managed Service Account||Traditional Service Account|
What will I see in my account after installing an application that uses a DMSA?
During the installation process, a new user record may be created in the Company and/or Project Directory tool that represents the DMSA. The DMSA contact name follows a distinct format with the application name converted to lower case and separated by dashes followed by an eight-character randomly generated id. For example, installing the application My DMSA Test App would create the user my-dmsa-test-app-469b1f7f in the Company Directory. It is important that you do not edit or delete directory users created by DMSA application installations as this may cause problems with the operation of the application.
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 organisation'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.
Understanding Procore API Authentication
Applications built on the Procore platform use the industry standard OAuth 2.0 Authorisation Framework for authentication with the API. The Procore API supports the following two authorisation 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.
Authorisation Code (user login flow) - Web server and browser-based applications often use this grant type for authentication with the API. With the Authorisation 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 Authorisation Code grant type, see OAuth 2.0 Authorisation Code Grant Flow.
Procore company administrators are ultimately responsible for managing the permissions of their directory users regardless of the authorisation grant type used by an integration - authorisation_code (logged in user's permissions) or client_credentials (service account/DMSA permissions).
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.
- Deprecation of Traditional Service Accounts
- Migrating a Data Connection App to use DMSA
- Install a Data Connection App from the Marketplace
- Add a Permitted Project to Data Connection App
- Remove a Permitted Project from a Data Connection App
- View DMSAs in the Company Directory