设置连接器以在预览版中导入 () Set up a connector to import physical badging data (preview)

可以在 Microsoft 365 合规中心中设置数据连接器,以导入物理密码数据,例如员工的原始物理访问事件或组织密码系统生成的任何物理访问警报。You can set up a data connector in the Microsoft 365 compliance center 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. Microsoft 365 内部风险管理解决方案可以使用物理保护数据来帮助保护组织免受组织内部恶意活动或数据盗窃的攻击。Physical badging data can be used by the Microsoft 365 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:

  • 在 Azure Active Directory (Azure AD) ,以访问接受包含物理保护数据的 JSON 负载的 API 终结点。Creating an app in Azure Active Directory (Azure AD) to access an API endpoint that accepts a JSON payload that contains physical badging data.

  • 使用由物理保护数据连接器定义的架构创建 JSON 有效负载。Creating the JSON payload with a schema defined by physical badging data connector.

  • 在 Microsoft 365 合规中心创建物理保护数据连接器。Creating a physical badging data connector in the Microsoft 365 compliance center.

  • 运行脚本以将物理保护代码数据推送到 API 终结点。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.

设置连接器之前Before you set up the connector

  • 必须在 Exchange Online 中为在步骤 3 中创建物理密码连接器的用户分配邮箱导入导出角色。The user who creates the physical badging connector in Step 3 must be assigned the Mailbox Import Export role in Exchange Online. 默认情况下,不会向 Exchange Online 中任何角色组分配此角色。By default, this role isn't assigned to any role group in Exchange Online. 可以将"邮箱导入导出"角色添加到 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. 有关详细信息,请参阅"在Exchange Online中管理角色组"一文的创建角色组或修改角色组部分。For more information, see the Create role groups or Modify role groups sections in the article "Manage role groups in Exchange Online".

  • 您需要确定如何每天从组织的物理密码系统 (检索或导出数据) 并创建步骤 2 中所述的 JSON 文件。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. 在步骤 4 中运行的脚本将 JSON 文件的数据推送到 API 终结点。The script that you run in Step 4 will push the data in the JSON file to the API endpoint.

  • 在步骤 4 中运行的示例脚本将 JSON 文件的物理保护数据推送到连接器 API,以便内部风险管理解决方案可以使用该数据。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. 本示例脚本在任何 Microsoft 标准支持计划或服务下都不受支持。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 进一步拒绝所有默示保证,包括但不限于针对特定用途的适销性或适用性的任何默示保证。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. 在任何情况下,对于由于使用或者无法使用示例脚本或文档所引起的任何损失(包括但不限于商业利润损失、业务中断、商业信息丢失或者其他经济损失),Microsoft、其作者或者参与创建、制作或交付脚本的任何人概不负责,即使 Microsoft 已被告知可能会出现此类损失。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.

步骤 1:在 Azure Active Directory 中创建应用Step 1: Create an app in Azure Active Directory

第一步是在 Azure AD (Azure Active Directory) 。The first step is to create and register a new app in Azure Active Directory (Azure AD). 该应用将对应于在步骤 3 中创建的物理保护连接器。The app will correspond to the physical badging connector that you create in Step 3. 创建此应用将允许 Azure AD 对包含物理保护数据的 JSON 有效负载的推送请求进行身份验证。Creating this app will allow Azure AD to authenticate the push request for JSON payload containing physical badging data. 创建此 Azure AD 应用期间,请务必保存以下信息。During the creation of this Azure AD app, be sure to save the following information. 这些值将在稍后的步骤中使用。These values will be used in later steps.

  • Azure AD 应用程序 ID (也称为 应用 ID客户端 ID) Azure AD application ID (also called the app Id or client Id)

  • Azure AD 应用程序密码 (也称为 客户端密码) Azure AD application secret (also called the client secret)

  • 租户 ID (也称为目录 ID) Tenant Id (also called the directory Id)

有关在 Azure AD 中创建应用的分步说明,请参阅向 Microsoft 标识平台 注册应用程序For step-by-step instructions for creating an app in Azure AD, see Register an application with the Microsoft identity platform.

步骤 2:准备包含物理保护数据的 JSON 文件Step 2: Prepare a JSON file with physical badging data

下一步是创建一个 JSON 文件,其中包含有关员工物理访问数据的信息。The next step is to create a JSON file that contains information about employees’ physical access data. 如开始之前部分所述,你需要确定如何从组织的物理保护系统生成此 JSON 文件。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.

JSON 文件必须符合连接器所需的架构定义。The JSON file must conform to the schema definition required by the connector. 以下是 JSON 文件所需的架构属性的说明:Here are descriptions of the required schema properties for the JSON file:

属性Property 说明Description 数据类型Data type
UserIDUserId 员工可以在系统中具有多个数字标识。An employee can have multiple digital identities across the systems. 输入需要已由源系统解析 Azure AD ID。The input needs to have the Azure AD ID already resolved by the source system. UPN 或电子邮件地址UPN or email address
AssetIdAssetId 物理资产或物理访问点的参考 ID。The reference ID of the physical asset or physical access point. 字母数字字符串Alphanumeric string
AssetNameAssetName 物理资产或物理访问点的友好名称。The friendly name of the physical asset or physical access point. 字母数字字符串Alphanumeric string
EventTimeEventTime 访问时间戳。The time stamp of access. 日期和时间(UTC 格式)Date and time, in UTC format
AccessStatusAccessStatus Success 的值 FailedValue of Success or Failed StringString

下面是符合所需架构的 JSON 文件示例: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",
    }
]

还可以在步骤 3 中创建物理保护连接器时,从向导下载 JSON 文件的以下架构定义。You can also download the following schema definition for the JSON file from the wizard 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"]
}

步骤 3:创建物理保护连接器Step 3: Create the physical badging connector

下一步是在 Microsoft 365 合规中心创建物理保护连接器。The next step is to create a physical badging connector in the Microsoft 365 compliance center. 在步骤 4 中运行脚本后,将在步骤 3 中创建的 JSON 文件进行处理并推送到在步骤 1 中配置的 API 终结点。After you run the script in Step 4, the JSON file that you created in Step 3 will be processed and pushed to the API endpoint you configured in Step 1. 在此步骤中,请确保复制创建连接器时生成的 JobId。In this step, be sure to copy the JobId that's generated when you create the connector. 运行脚本时,将使用 JobId。You'll use the JobId when you run the script.

  1. 转到 , https://compliance.microsoft.com 然后单击左侧 导航中的 "数据连接器"。Go to https://compliance.microsoft.com and then click Data connectors in the left nav.

  2. 在"数据连接器"页上 的"物理保护"下, 单击"查看 "。On the Data connectors page under Physical badging, click View.

  3. 在"物理保护"页上,单击"添加连接器"。On the Physical badging page, click Add connector.

  4. 在"身份验证凭据" 页上,执行以下操作,然后单击"下一步 ":On the Authentication credentials page, do the following and then click Next:

    1. 键入或粘贴你在步骤 1 中创建的 Azure 应用的 Azure AD 应用程序 ID。Type or paste the Azure AD application ID for the Azure app that you created in Step 1.

    2. 下载示例架构,以参考创建 JSON 文件。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 click Finish to create the connector.

  6. 将显示一个状态页,确认连接器已创建。A status page is displayed that confirms the connector was created. 此页面还包含作业 ID。This page also contains the job ID. 可以从此页面或连接器的飞出页复制作业 ID。You can copy job ID from this page or from the flyout page for the connector. 运行脚本时需要此作业 ID。You need this job ID when running the script.

    状态页还包含指向脚本的链接。The status page also contains a link to the script. 请参阅此脚本,了解如何将 JSON 文件张贴到 API 终结点。Refer to this script to understand how to post the JSON file to the API endpoint.

  7. 单击“完成”。Click Done.

    新连接器显示在"连接器"选项卡 上的 列表中。The new connector is displayed in the list on the Connectors tab.

  8. 单击刚创建的物理保护符连接器以显示该飞出页,其中包含有关该连接器的属性和其他信息。Click the physical badging connector that you just created to display the flyout page, which contains properties and other information about the connector.

步骤 4:运行脚本以 POST 包含物理保护数据的 JSON 文件Step 4: Run the script to POST your JSON file containing physical badging data

设置物理保护连接器的下一步是运行一个脚本,该脚本将在步骤 2) 中创建的 JSON 文件 (中将物理保护数据推送到在步骤 1 中创建的 API 终结点。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. 我们提供示例脚本供你参考,你可以选择使用它或创建你自己的脚本将 JSON 文件张贴到 API 终结点。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.

运行脚本后,包含物理保护数据的 JSON 文件将推送到 Microsoft 365 组织,内部风险管理解决方案可在其中访问该文件。After you run the script, the JSON file containing the physical badging data is pushed to your Microsoft 365 organization where it can accessed by the insider risk management solution. 我们建议你每天发布物理保护数据。We recommend you post physical badging data daily. 为此,可以自动执行每天从物理保护系统生成 JSON 文件的过程,然后计划脚本以推送数据。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.

备注

API 可以处理的 JSON 文件中的最大记录数为 50,000 条记录。The maximum number of records in the JSON file that can be processed by the API is 50,000 records.

  1. 转到 此 GitHub 网站 以访问示例脚本。Go to this GitHub site to access the sample script.

  2. 单击" 原始 "按钮以在文本视图中显示脚本Click 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. 使用文件名后缀 .ps1 将文本文件另存为Windows PowerShell脚本文件;例如,PhysicalBadging.ps1。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. 运行以下命令,将 JSON 文件的物理保护数据推送到 Microsoft 云;例如: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
    tenantIdtenantId 这是在步骤 1 中获取的 Microsoft 365 组织的 ID。This is the Id for your Microsoft 365 organization that you obtained in Step 1. 还可以在 Azure AD 管理中心的"概述"边栏选项卡上获取组织的 tenantId。You can also obtain the tenantId for your organization on the Overview blade in the Azure AD admin center. 这用于标识您的组织。This is used to identify your organization.
    appIdappId 这是你在步骤 1 中的 Azure AD 中创建的应用的 Azure AD 应用程序 ID。This is the Azure AD application Id for the app that you created in Azure AD in Step 1. 当脚本尝试访问你的 Microsoft 365 组织时,Azure AD 会使用此功能进行身份验证。This is used by Azure AD for authentication when the script attempts to accesses your Microsoft 365 organization.
    appSecretappSecret 这是你在步骤 1 中的 Azure AD 中创建的应用的 Azure AD 应用程序密码。This is the Azure AD application secret for the app that you created in Azure AD in Step 1. 这还用于身份验证。This is also used for authentication.
    jobIdjobId 这是在步骤 3 中创建的物理保护连接器的作业 ID。This is the Job Id for the physical badging connector that you created in Step 3. 这用于将推送到 Microsoft 云的物理保护数据与物理保护连接器关联。This is used to associate the physical badging data that is pushed to the Microsoft cloud with the physical badging connector.
    JsonFilePathJsonFilePath 这是本地计算机的文件路径 (您用于为步骤 2 中创建的 JSON 文件运行脚本) 的文件路径。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. 此文件必须遵循步骤 3 中所述的示例架构。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 -csvFilePath 'C:\Users\contosoadmin\Desktop\Data\physical_badging_data.json'
    

    如果上传成功,脚本将显示" 上传成功" 消息。If the upload is successful, the script displays the Upload Successful message.

    如果你有多个 JSON 文件,必须运行每个文件的脚本。If you have multiple JSON files, you have to run the script for each file.

备注

还可以选择通过运行前一个脚本的方法将物理保护数据推送到 API 终结点。You can also choose to push the physical badging data to the API endpoint by methods other than running the previous script. 例如,下面是使用 Postman 将数据推送到 API 终结点的示例。For example, here's a sample for using Postman to push your data to the API endpoint.

步骤 5:监视物理保护连接器Step 5: Monitor the physical badging connector

创建物理保护连接器并推送物理保护数据后,可以在 Microsoft 365 合规中心查看连接器和上载状态。After you create the physical badging connector and push your physical badging data, you can view the connector and upload status in the Microsoft 365 compliance center. 如果安排脚本定期自动运行,还可以在上次运行脚本后查看当前状态。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.

  1. 转到左侧 https://compliance.microsoft.com 导航 导航中的"数据 连接器",然后单击" 数据连接器"。Go to https://compliance.microsoft.com and click Data connectors in the left nav.

  2. 单击 "连接器" 选项卡,然后选择物理保护符连接器以显示飞出页。Click 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, click the Download log link to open (or save) the status log for the connector. 此日志包含有关脚本每次运行以及将数据从 CSV 文件上载到 Microsoft 云时的信息。This log contains information about each time the script runs and uploads the data from the CSV file to the Microsoft cloud.

    物理保护连接器日志文件 JSON 文件中上传的行数

    RecordsSaved 字段指示 CSV 文件中上载的行数。The RecordsSaved field indicates the number of rows in the CSV file that uploaded. 例如,如果 CSV 文件包含四行,则 RecordsSaved 字段的值为 4(如果脚本成功上载 CSV 文件的所有行)。For example, if the CSV file contains four rows, then the value of the RecordsSaved fields is 4, if the script successfully uploaded all the rows in the CSV file.

如果尚未在步骤 4 中运行脚本,则"上次导入"下将显示用于下载脚本 的链接If you've haven't run the script in Step 4, a link to download the script is displayed under Last import. 可以下载脚本,然后按照步骤 4 中的步骤运行它。You can download the script and then follow the steps in Step 4 to run it.

(可选) 步骤 6:计划脚本自动运行(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. 这还要求你将物理保护数据更新为类似 ((如果不是同一) 计划)上的 JSON 文件,以便其中包含有关离开组织的员工的最新信息。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 user the Task Scheduler app in Windows to automatically run the script every day.You can user the Task Scheduler app in Windows to automatically run the script every day.

  1. 在本地计算机上,单击 Windows"开始" 按钮,然后键入 "任务计划程序"。On your local computer, click the Windows Start button and then type Task Scheduler.

  2. 单击任务 计划程序 应用以打开它。Click the Task Scheduler app to open it.

  3. 在"操作"部分,单击"创建任务"。In the Actions section, click 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, click 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 every day at the same specified time.

    2. "高级设置"下,确保 选中"已启用 "复选框。Under Advanced settings, make sure the Enabled checkbox is selected.

    3. 单击“确定”。Click Ok.

  7. 选择" 操作" 选项卡,单击 "新建",然后执行以下操作:Select the Actions tab, click New, and then do the following things:

    为物理保护连接器脚本创建新的计划任务的操作设置

    1. "操作 "下拉列表中,确保已 选择"启动程序 "。In the Action dropdown list, make sure that Start a program is selected.

    2. 在"程序/脚本"框中,单击"浏览",然后转到以下位置并选择它,以便路径显示在框中:C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe。In the Program/script box, click 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. 在" 添加 (可选) " 框中,粘贴在步骤 4 中运行相同的脚本命令。In the Add arguments (optional) box, paste the same script command that you ran in Step 4. 例如, .\PhysicalBadging.ps1-tenantId "d5723623-11cf-4e2e-b5a5-01d1506273g9" -appId "c12823b7-b55a-4989-faba-02de 41bb97c3" -appSecret "MNubVGbcQDkGCnn" -jobId "e081f4f4-3831-48d6-7bb3-fcfab1581458" -jsonFilePath "C:\Users\contosoadmin\Desktop\Data\physical_badging_data.csv"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.csv"

    4. " (可选) "框中,粘贴在步骤 4 中运行脚本的文件夹位置。In the Start in (optional) box, paste the folder location of the script that you ran in Step 4. 例如,C:\Users\contosoadmin\Desktop\Scripts。For example, C:\Users\contosoadmin\Desktop\Scripts.

    5. 单击 " 确定"保存新操作的设置。Click Ok to save the settings for the new action.

  8. 在" 创建任务" 窗口中,单击" 确定 "保存计划任务。In the Create Task window, click 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-click 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.