Set up a connector to import physical badging data

You can set up a data connector to import physical badging data, such as employee’s raw physical access events or any physical access alarms generated by your organization's badging system. Examples of physical access points are an entry to a building or an entry to server room or data center. Physical badging data can be used by the Microsoft Purview Insider Risk Management solution to help protect your organization from malicious activity or data theft inside your organization.

Setting up a physical badging connector consists of the following tasks:

• Creating an app in Microsoft Entra ID to access an API endpoint that accepts a JSON payload that contains physical badging data.

• Creating the JSON payload with a schema defined by physical badging data connector.

• Creating a physical badging data connector in the Microsoft Purview portal or the Microsoft Purview compliance portal.

• Running a script to push the physical badging data to the API endpoint.

• Optionally, scheduling the script to run automatically to import currently physical badging data.

Tip

If you're not an E5 customer, use the 90-day Microsoft Purview solutions trial to explore how additional Purview capabilities can help your organization manage data security and compliance needs. Start now at the Microsoft Purview trials hub. Learn details about signing up and trial terms.

Before you set up the connector

• The user who creates the physical badging connector in Step 3 must be assigned the Data Connector Admin role. This role is required to add connectors on the Data connectors page in the Microsoft Purview portal or the compliance portal. This role is added by default to multiple role groups. For a list of these role groups, see Roles in Microsoft Defender for Office 365 and Microsoft Purview compliance. Alternatively, an admin in your organization can create a custom role group, assign the Data Connector Admin role, and then add the appropriate users as members. For instructions, see:

  • Permissions in the Microsoft Purview portal
  • Permissions in the compliance portal
  • Roles and role groups in Microsoft Defender for Office 365 and Microsoft Purview compliance

  Note

  The Data Connector Admin role is currently not supported in US Government GCC High and DoD environments. Therefore, the user who creates the HR connector in GCC High and DoD environments must be assigned the Mailbox Import Export role in Exchange Online. By default, this role isn't assigned to any role group in Exchange Online. You can add the Mailbox Import Export role to the Organization Management role group in Exchange Online. Or you can create a new role group, assign the Mailbox Import Export role, and then add the appropriate users as members. For more information, see the Create role groups or Modify role groups sections in the article "Manage role groups in Exchange Online".

• You need to determine how to retrieve or export the data from your organization's physical badging system (on a daily basis) and create a JSON file that's described in Step 2. The script that you run in Step 4 will push the data in the JSON file to the API endpoint.

• The sample script that you run in Step 4 pushes the physical badging data from JSON file to the connector API so that it can be used by the insider risk management solution. This sample script isn't supported under any Microsoft standard support program or service. The sample script is provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample script and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.

• This connector is available in GCC environments in the Microsoft 365 US Government cloud. Third-party applications and services might involve storing, transmitting, and processing your organization's customer data on third-party systems that are outside of the Microsoft 365 infrastructure and therefore are not covered by the Microsoft Purview and data protection commitments. Microsoft makes no representation that use of this product to connect to third-party applications implies that those third-party applications are FEDRAMP compliant.

Step 1: Create an app in Microsoft Entra ID

The first step is to create and register a new app in Microsoft Entra ID. The app will correspond to the physical badging connector that you create in Step 3. Creating this app will allow Microsoft Entra ID to authenticate the push request for JSON payload containing physical badging data. During the creation of this Microsoft Entra app, be sure to save the following information. These values are used in later steps.

• Microsoft Entra application ID (also called the app Id or client Id)

• Microsoft Entra application secret (also called the client secret)

• Tenant Id (also called the directory Id)

For step-by-step instructions for creating an app in Microsoft Entra ID, see Register an application with the Microsoft identity platform.

Step 2: Prepare a JSON file with physical badging data

The next step is to create a JSON file that contains information about employees’ physical access data. As explained in the before you begin section, you'll need to determine how to generate this JSON file from your organization's physical badging system.

Note

Do not add non-english characters to the JSON file. Only english characters are supported by the connector; ingestion of data might fail if the JSON contains non-english characters.

The JSON file must conform to the schema definition required by the connector. Here are descriptions of the required schema properties for the JSON file:

Property	Description	Data type
UserId	An employee can have multiple digital identities across the systems. The input needs to have the Microsoft Entra ID already resolved by the source system.	UPN or email address
AssetId	The reference ID of the physical asset or physical access point.	Alphanumeric string
AssetName	The friendly name of the physical asset or physical access point.	Alphanumeric string
EventTime	The time stamp of access.	Date and time, in UTC format
AccessStatus	Value of Success or Failed	String

Here's an example of a JSON file that conforms to the required schema:

[
    {
        "UserId":"sarad@contoso.com",
        "AssetId":"Mid-Sec-7",
        "AssetName":"Main Building 1st Floor Mid Section",
        "EventTime":"2019-07-04T01:57:49",
        "AccessStatus":"Failed"
    },
    {
        "UserId":"pilarp@contoso.com",
        "AssetId":"Mid-Sec-7",
        "AssetName":"Main Building 1st Floor Mid Section",
        "EventTime":"2019-07-04T02:57:49",
        "AccessStatus":"Success"
    }
]

You can also download the following schema definition for the JSON file from the workflow when you create the physical badging connector in Step 3.

{
   "title" : "Physical Badging Signals",
   "description" : "Access signals from physical badging systems",
   "DataType" : {
      "description" : "Identify what is the data type for input signal",
      "type" : "string",
   },
   "type" : "object",
   "properties": {
      "UserId" : {
         "description" : "Unique identifier AAD Id resolved by the source system",
         "type" : "string",
      },
      "AssetId": {
         "description" : "Unique ID of the physical asset/access point",
         "type" : "string",
      },
      "AssetName": {
         "description" : "friendly name of the physical asset/access point",
         "type" : "string",
      },
      "EventTime" : {
         "description" : "timestamp of access",
         "type" : "string",
      },
      "AccessStatus" : {
         "description" : "what was the status of access attempt - Success/Failed",
         "type" : "string",
      },
   }
   "required" : ["UserId", "AssetId", "EventTime" "AccessStatus"]
}

Step 3: Create the physical badging connector

The next step is to create a physical badging connector in the Microsoft Purview portal or the compliance portal. After you run the script in Step 4, the JSON file that you created in Step 3 is processed and pushed to the API endpoint you configured in Step 1. In this step, be sure to copy the JobId that's generated when you create the connector. You'll use the JobId when you run the script.

Select the appropriate tab for the portal you're using. Depending on your Microsoft 365 plan, the Microsoft Purview compliance portal is retired or will be retired soon.

To learn more about the Microsoft Purview portal, see Microsoft Purview portal. To learn more about the Compliance portal, see Microsoft Purview compliance portal.

Microsoft Purview portal

1. Sign into the Microsoft Purview portal.

2. Select Settings > Data connectors.

3. Select My connectors, then select Add connector.

4. From the list, choose Physical badging.

5. On the Authentication credentials page, do the following and then select Next:

   1. Type or paste the Microsoft Entra application ID for the Azure app that you created in Step 1.

   2. Download the sample schema for your reference to create the JSON file.

   3. Type a unique name for the physical badging connector.

6. On the Review page, review your settings and then select Finish to create the connector.

7. A status page is displayed that confirms the connector was created. This page also contains the job ID. You can copy job ID from this page or from the flyout page for the connector. You need this job ID when running the script.

   The status page also contains a link to the script. Refer to this script to understand how to post the JSON file to the API endpoint.

8. Select Done.

   The new connector is displayed in the list on the Connectors tab.

9. Select the physical badging connector that you just created to display the flyout page, which contains properties and other information about the connector.

Compliance portal

1. Go to the compliance portal, and select Data connectors.

2. On the Data connectors page under Physical badging, select View.

3. On the Physical badging page, select Add connector.

4. On the Authentication credentials page, do the following and then select Next:

   1. Type or paste the Microsoft Entra application ID for the Azure app that you created in Step 1.

   2. Download the sample schema for your reference to create the JSON file.

   3. Type a unique name for the physical badging connector.

5. On the Review page, review your settings and then select Finish to create the connector.

6. A status page is displayed that confirms the connector was created. This page also contains the job ID. You can copy job ID from this page or from the flyout page for the connector. You need this job ID when running the script.

   The status page also contains a link to the script. Refer to this script to understand how to post the JSON file to the API endpoint.

7. Select Done.

   The new connector is displayed in the list on the Connectors tab.

8. Select the physical badging connector that you just created to display the flyout page, which contains properties and other information about the connector.

Step 4: Run the script to POST your JSON file containing physical badging data

The next step in setting up a physical badging connector is to run a script that will push the physical badging data in the JSON file (that you created in Step 2) to the API endpoint you created in Step 1. We provide a sample script for your reference and you can choose to use it or create your own script to post the JSON file to the API endpoint.

After you run the script, the JSON file containing the physical badging data is pushed to your Microsoft 365 organization where it can be accessed by the insider risk management solution. We recommend you post physical badging data daily. You can do this by automating the process to generate the JSON file every day from your physical badging system and then scheduling the script to push the data.

Note

The maximum number of records in the JSON file that can be processed by the API is 50,000 records.

1. Go to this GitHub site to access the sample script.

2. Select the Raw button to display the script in text view

3. Copy all the lines in the sample script and then save them to a text file.

4. Modify the sample script for your organization, if necessary.

5. Save the text file as a Windows PowerShell script file by using a filename suffix of .ps1; for example, PhysicalBadging.ps1.

6. Open a Command Prompt on your local computer, and go to the directory where you saved the script.

7. Run the following command to push the physical badging data in the JSON file to the Microsoft cloud; for example:

   .\PhysicalBadging.ps1 -tenantId "<Tenant Id>" -appId "<Azure AD App Id>" -appSecret "<Azure AD App Secret>" -jobId "Job Id" -jsonFilePath "<records file path>"
   

   The following table describes the parameters to use with this script and their required values. Information you obtained in the previous steps is used in the values for these parameters.

   Parameter	Description
   tenantId	This is the Id for your Microsoft 365 organization that you obtained in Step 1. You can also obtain the tenantId for your organization on the Overview blade in the Microsoft Entra admin center. This is used to identify your organization.
   appId	This is the Microsoft Entra application Id for the app that you created in Microsoft Entra ID in Step 1. This is used by Microsoft Entra ID for authentication when the script attempts to access your Microsoft 365 organization.
   appSecret	This is the Microsoft Entra application secret for the app that you created in Microsoft Entra ID in Step 1. This is also used for authentication.
   jobId	This is the Job Id for the physical badging connector that you created in Step 3. This is used to associate the physical badging data that is pushed to the Microsoft cloud with the physical badging connector.
   JsonFilePath	This is the file path on the local computer (the one you're using to run the script) for the JSON file that you created in Step 2. This file must follow the sample schema described in Step 3.

   Here's an example of the syntax for the physical badging connector script using actual values for each parameter:

   .\PhysicalBadging.ps1 -tenantId d5723623-11cf-4e2e-b5a5-01d1506273g9 -appId 29ee526e-f9a7-4e98-a682-67f41bfd643e -appSecret MNubVGbcQDkGCnn -jobId b8be4a7d-e338-43eb-a69e-c513cd458eba -jsonFilePath 'C:\Users\contosoadmin\Desktop\Data\physical_badging_data.json'
   

   If the upload is successful, the script displays the Upload Successful message.

   If you have multiple JSON files, you have to run the script for each file.

Step 5: Monitor the physical badging connector

After you create the physical badging connector and push your physical badging data, you can view the connector and upload status in the Microsoft Purview portal or the compliance portal. If you schedule the script to run automatically on a regular basis, you can also view the current status after the last time the script ran.

Select the appropriate tab for the portal you're using. Depending on your Microsoft 365 plan, the Microsoft Purview compliance portal is retired or will be retired soon.

To learn more about the Microsoft Purview portal, see Microsoft Purview portal. To learn more about the Compliance portal, see Microsoft Purview compliance portal.

Microsoft Purview portal

1. Sign into the Microsoft Purview portal.

2. Select Settings > Data connectors.

3. Select My connectors, then select the physical badging connector that you created to display the flyout page. This page contains the properties and information about the connector.

4. Under Last import, select the Download log link to open (or save) the status log for the connector. This log contains information about each time the script runs and uploads the data from the JSON file to the Microsoft cloud.

   

   The RecordsSaved field indicates the number of records in the JSON file that were uploaded. For example, if the JSON file contains four records, then the value of the RecordsSaved fields is 4 if the script successfully uploaded all the records in the JSON file. The RecordsSkipped field indicates the number of records in the JSON file that were skipped. Before uploading records in the JSON file, the Email IDs of the records are validated. Any record with an invalid Email ID is skipped and the corresponding Email ID is displayed in the field EmailIdsNotSaved

If you've haven't run the script in Step 4, a link to download the script is displayed under Last import. You can download the script and then follow the steps in Step 4 to run it.

Compliance portal

1. Go to the compliance portal, and select Data connectors.

2. Select the Connectors tab and then select the physical badging connector to display the flyout page. This page contains the properties and information about the connector.

   

3. Under Last import, select the Download log link to open (or save) the status log for the connector. This log contains information about each time the script runs and uploads the data from the JSON file to the Microsoft cloud.

   

   The RecordsSaved field indicates the number of records in the JSON file that were uploaded. For example, if the JSON file contains four records, then the value of the RecordsSaved fields is 4 if the script successfully uploaded all the records in the JSON file. The RecordsSkipped field indicates the number of records in the JSON file that were skipped. Before uploading records in the JSON file, the Email IDs of the records are validated. Any record with an invalid Email ID is skipped and the corresponding Email ID is displayed in the field EmailIdsNotSaved

If you've haven't run the script in Step 4, a link to download the script is displayed under Last import. You can download the script and then follow the steps in Step 4 to run it.

(Optional) Step 6: Schedule the script to run automatically

To make sure the latest physical badging data from your organization is available to tools like the insider risk management solution, we recommend that you schedule the script to run automatically on a recurring basis, such as once a day. This also requires that you update the physical badging data to JSON file on a similar (if not the same) schedule so that it contains the latest information about employees who leave your organization. The goal is to upload the most current physical badging data so that the physical badging connector can make it available to the insider risk management solution.

You can use the Task Scheduler app in Windows to automatically run the script every day.

1. On your local computer, select the Windows Start button and then type Task Scheduler.

2. Select the Task Scheduler app to open it.

3. In the Actions section, select Create Task.

4. On the General tab, type a descriptive name for the scheduled task; for example, physical badging connector Script. You can also add an optional description.

5. Under Security options, do the following things:

   1. Determine whether to run the script only when you're logged on to the computer or run it when you're logged on or not.

   2. Make sure that the Run with the highest privileges checkbox is selected.

6. Select the Triggers tab, select New, and then do the following things:

   1. Under Settings, select the Daily option, and then choose a date and time to run the script for the first time. The script will run every day at the same specified time.

   2. Under Advanced settings, make sure the Enabled checkbox is selected.

   3. Select Ok.

7. Select the Actions tab, select New, and then do the following things:

   

   1. In the Action dropdown list, make sure that Start a program is selected.

   2. In the Program/script box, select Browse, and go to the following location and select it so the path is displayed in the box: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe.

   3. In the Add arguments (optional) box, paste the same script command that you ran in Step 4. For example, .\PhysicalBadging.ps1-tenantId "d5723623-11cf-4e2e-b5a5-01d1506273g9" -appId "c12823b7-b55a-4989-faba-02de41bb97c3" -appSecret "MNubVGbcQDkGCnn" -jobId "e081f4f4-3831-48d6-7bb3-fcfab1581458" -jsonFilePath "C:\Users\contosoadmin\Desktop\Data\physical_badging_data.json"

   4. In the Start in (optional) box, paste the folder location of the script that you ran in Step 4. For example, C:\Users\contosoadmin\Desktop\Scripts.

   5. Select Ok to save the settings for the new action.

8. In the Create Task window, select Ok to save the scheduled task. You might be prompted to enter your user account credentials.

   The new task is displayed in the Task Scheduler Library.

   

The last time the script ran and the next time it's scheduled to run is displayed. You can double-select the task to edit it.

You can also verify the last time the script ran on the flyout page of the corresponding physical badging connector in the compliance center.