Developer Managed Service Accounts

Deprecation of Traditional Service Accounts

Traditional Service Accounts will be deprecated on December 9, 2021. Creation of new traditional service accounts will no longer be allowed after July 31, 2022. All traditional service accounts will be sunset on January 31, 2023. As a result of this deprecation, developers of data connection applications that currently use traditional service accounts must migrate the app to use Developer Managed Service Accounts (DMSAs), and customers must install these migrated apps before the January 31, 2023 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.

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
Account Creation
  • A directory user associated with the DMSA is automatically created in the Company and/or Project Directory tool.
  • A traditional service account must be created and managed manually by a company administrator.
Authorization
  • A single set of credentials (client_id, client_secret) is used to access all companies where the application is installed.
  • Each service account created in a company by an administrator has a unique set of credentials, requiring manual coordination with the developer for successful integration.
Permissions
  • Required permissions are defined by the developer in the application manifest and automatically applied during installation.
  • Permissions for each service account must be configured manually by a company administrator.
Project Configuration
  • During installation, you can select which projects the DMSA application is allowed to run in. Once the application is installed, you can add or remove permitted projects as needed.
  • Project access and must be configured and managed manually by the company administrator.
App Management
  • DMSA-enabled applications are easily installed from the App Marketplace or as a custom install. Company Admin tool (App Management) used for uninstall/reinstall.
  • All aspects of traditional service account installation and management must be handled manually by a company administrator.

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.

    Copy Code Snippet

  4. Paste the code snippet into the manifest editor in the components section.
  5. Enter client_credentials for the component grant_type.

    Manifest Client Credentials

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.

    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.

    Manifest Permissions

  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.

Add Permitted Projects

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.

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 MPZ 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 ‘bot’ 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.

When using DMSA client credentials and authorization code grant flows in the same application, how do I determine if the DMSA ‘bot’ 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 ‘Bot’ User:

{
  "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:

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