教程:使用 Microsoft Graph API 识别和修正风险Tutorial: Identify and remediate risks using Microsoft Graph APIs

Azure AD Identity Protection 使组织能够深入了解基于标识的风险以及调查和自动修正风险的不同方法。Azure AD Identity Protection provides organizations insight into identity-based risk and different ways to investigate and automatically remediate risk. 本教程中使用的 Identity Protection API 可帮助你识别风险并配置工作流以确认泄露或启用修正。The Identity Protection APIs used in this tutorial can help you identify risk and configure a workflow to confirm compromise or enable remediation. 有关详细信息,请参阅 什么是风险?For more information, see What is risk?

本教程介绍如何生成有风险的登录,以及使用要求使用 MFA 身份验证的多重身份验证的条件访问策略修正用户 (状态) 。In this tutorial, you learn how to generate a risky sign-in and remediate the risk status of the user with a conditional access policy that requires multi-factor authentication (MFA). 可选部分显示如何阻止用户也使用条件访问策略登录,并消除用户风险。An optional section shows you how to block the user from signing in also using a conditional access policy, and dismissing the user risk.

注意: 为了可读性,本教程中显示的响应对象可能会缩短。Note: The response objects shown in this tutorial might be shortened for readability.

先决条件Prerequisites

若要成功完成本教程,请确保你满足以下先决条件:To successfully complete this tutorial, make sure that you have the required prerequisites:

  • 必须具有 Azure AD Premium P1 或 P2 许可证才能使用风险检测 API。You must have an Azure AD Premium P1 or P2 license to use the risk detection API.
  • 本教程使用 Tor 浏览器匿名登录 Azure 门户。This tutorial uses the Tor browser to sign in to the Azure portal anonymously. 可以使用任何匿名浏览器来完成该任务。You can use any anonymous browser to accomplish the task. 若要下载 Tor 浏览器,请参阅"下载 Tor 浏览器"。To download the Tor browser, see Download Tor Browser.
  • 本教程假定你使用的是 Microsoft Graph 资源管理器,但可以使用 Postman,也可以创建自己的客户端应用来调用 Microsoft Graph。This tutorial assumes that you are using Microsoft Graph Explorer, but you can use Postman, or create your own client app to call Microsoft Graph. 若要在本教程中调用 Microsoft Graph API,你需要使用具有 全局管理员角色 和相应权限的帐户。To call the Microsoft Graph APIs in this tutorial, you need to use an account with the global administrator role and the appropriate permissions. 完成以下步骤以在 Microsoft Graph 资源管理器中设置权限:Complete the following steps to set permissions in Microsoft Graph Explorer:
    1. 启动 Microsoft Graph 浏览器Start Microsoft Graph Explorer.

    2. 选择 "使用 Microsoft 登录 ",然后使用 Azure AD 全局管理员帐户登录。Select Sign-In with Microsoft and sign in using an Azure AD global administrator account. 成功登录后,可以在左侧窗格中看到用户帐户详细信息。After you successfully sign in, you can see the user account details in the left-hand pane.

    3. 选择用户帐户详细信息右边的设置图标,然后选择"选择权限"。Select the settings icon to the right of the user account details, and then select Select permissions.

      设置权限

    4. 滚动浏览这些权限的列表:Scroll through the list of permissions to these permissions:

      • IdentityRiskEvents (2) , 展开,然后选择 IdentityRiskEvent.Read.AllIdentityRiskEvents (2), expand and then select IdentityRiskEvent.Read.All
      • IdentityRiskyUser (2) , 展开并选择 IdentityRiskyUser.ReadWrite.AllIdentityRiskyUser (2), expand and then select IdentityRiskyUser.ReadWrite.All
      • 策略 (13) , 展开,然后选择 Policy.Read.All``Policy.ReadWrite.ConditionalAccessPolicy (13), expand and then select Policy.Read.All and Policy.ReadWrite.ConditionalAccess
      • 用户 (8) , 展开,然后选择 User.ReadWrite.AllUser (8), expand and then select User.ReadWrite.All

      搜索权限

    5. 选择 " 同意",然后选择" 接受 "以接受权限的同意。Select Consent, and then select Accept to accept the consent of the permissions. 无需代表组织同意这些权限。You do not need to consent on behalf of your organization for these permissions.

      接受权限

步骤 1:创建用户帐户Step 1: Create a user account

对于本教程,您将创建用于测试风险检测的用户帐户。For this tutorial, you create a user account that is used to test risk detections. 在请求正文中, contoso.com 更改为租户的域名。In the request body, change contoso.com to the domain name of your tenant. 可以在 Azure Active Directory 概述页面上找到租户信息。You can find tenant information on the Azure Active Directory overview page.

请求Request

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
  "accountEnabled":true,
  "displayName":"MyTestUser1",
  "mailNickname":"MyTestUser1",
  "userPrincipalName":"MyTestUser1@contoso.com",
  "passwordProfile": {
    "forceChangePasswordNextSignIn":true,
    "password":"Contoso1234"
  }
}

响应Response

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
  "id": "4628e7df-dff3-407c-a08f-75f08c0806dc",
  "businessPhones": [],
  "displayName": "MyTestUser1",
  "givenName": null,
  "jobTitle": null,
  "mail": null,
  "mobilePhone": null,
  "officeLocation": null,
  "preferredLanguage": null,
  "surname": null,
  "userPrincipalName": "MyTestUser1@contoso.com"
}

步骤 2:触发风险检测Step 2: Trigger a risk detection

触发风险检测Trigger a risk detection

触发用户帐户风险检测的一种方式是匿名登录 Azure 门户。One way to trigger a risk detection on a user account is to sign in to the Azure portal anonymously. 在本教程中,Tor 浏览器用于匿名登录。In this tutorial, the Tor browser is used to sign in anonymously.

  1. 打开浏览器并 portal.azure.com 输入站点地址。Open the browser and enter portal.azure.com for the site address.
  2. 使用之前创建的 MyTestUser1 帐户的凭据登录到门户。Sign in to the portal using the credentials for the MyTestUser1 account that you previously created. 将要求您更改现有密码。You will be asked to change the existing password.

列出风险检测List risk detections

使用匿名浏览器登录 Azure 门户时, anonymizedIPAddress 检测到风险事件。When you signed in to the Azure portal using the anonymous browser, an anonymizedIPAddress risk event was detected. 查询参数可用于仅获取与 $filter MyTestUser1 用户帐户关联的风险检测。You can use the $filter query parameter to get only the risk detections that are associated with the MyTestUser1 user account.

请求Request

GET https://graph.microsoft.com/v1.0/identityProtection/riskDetections?$filter=userDisplayName eq 'MyTestUser1'

响应Response

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#riskDetections",
  "value": [
    {
      "id": "d52a631815aaa527bf642b196715da5cf0f35b6879204ea5b5c99b21bd4c16f4",
      "requestId": "06f7fd18-b8f1-407d-86a3-f6cbe3a4be00",
      "correlationId": "2a38abff-5701-4073-a81e-fd3aac09cba3",
      "riskType": "anonymizedIPAddress",
      "riskEventType": "anonymizedIPAddress",
      "riskState": "atRisk",
      "riskLevel": "medium",
      "riskDetail": "none",
      "source": "IdentityProtection",
      "detectionTimingType": "realtime",
      "activity": "signin",
      "tokenIssuerType": "AzureAD",
      "ipAddress": "178.17.170.23",
      "activityDateTime": "2020-11-03T20:51:34.6245276Z",
      "detectedDateTime": "2020-11-03T20:51:34.6245276Z",
      "lastUpdatedDateTime": "2020-11-03T20:53:12.1984203Z",
      "userId": "4628e7df-dff3-407c-a08f-75f08c0806dc",
      "userDisplayName": "MyTestUser1",
      "userPrincipalName": "MyTestUser1@contoso.com",
      "additionalInfo": "[{\"Key\":\"userAgent\",\"Value\":\"Mozilla/5.0 (Windows NT 10.0; rv:78.0) Gecko/20100101 Firefox/78.0\"}]",
      "location": {
        "city": "Chisinau",
        "state": "Chisinau",
        "countryOrRegion": "MD",
        "geoCoordinates": {
          "latitude": 47.0269,
          "longitude": 28.8416
        }
      }
    }
  ]
}

注意: 可能需要几分钟时间才能返回事件。Note: It may take a few minutes for the event to be returned.

步骤 3:创建条件访问策略Step 3: Create a conditional access policy

您可以利用组织中的条件访问策略,以允许用户在检测到风险时自行修正。You can leverage conditional access policies in your organization to allow users to self-remediate when risk is detected. 利用自我修正,用户可以在完成策略提示后自行取消阻止,从而安全地访问其资源。Self-remediation enables your users to unblock themselves to access their resources securely after completing the policy prompt. 在此步骤中,您将创建一个条件访问策略,要求用户在出现中等或高风险检测时使用 MFA 登录。In this step, you create a conditional access policy that requires the user to sign in using MFA if a medium or high risk detection occurs.

设置多重身份验证Set up multi-factor authentication

为 MFA 设置帐户时,可以从多种方法中选择用于验证用户。When setting up an account for MFA, you can choose from several methods for authenticating the user. 选择最适合你的情况的方法来完成本教程。Choose the best method for your situation to complete this tutorial.

  1. 使用 MyTestUser1 帐户登录到帐户安全网站。Sign in the to the keep your account secure site using the MyTestUser1 account.
  2. 使用适用于你的情况的方法完成 MFA 设置过程,例如向手机发送短信。Complete the MFA setup procedure using the appropriate method for your situation, such as having a text message sent to your phone.

创建条件访问策略Create the conditional access policy

条件访问策略提供设置策略条件以确定登录风险级别的能力。The conditional access policy provides the ability to set the conditions of the policy to identify sign-in risk levels. 风险级别可以是 lowmediumhighnoneRisk levels can be low, medium, high, none. 在从列出 MyTestUser1 的风险检测返回的响应中,可以看到风险级别是 mediumIn the response that was returned from listing the risk detections for MyTestUser1, we can see that the risk level is medium. 此示例演示如何为标识为风险用户的 MyTestUser1 要求 MFA。This example shows how to require MFA for MyTestUser1 who was identified as a risky user.

请求Request

POST https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies 
Content-type: application/json
 
{ 
  "displayName": "Policy for risky sign-in", 
  "state": "enabled", 
  "conditions": { 
    "signInRiskLevels": [ 
      "high", 
      "medium" 
    ], 
    "applications": { 
      "includeApplications": ["All"]
    }, 
    "users": { 
      "includeUsers": [ 
        "4628e7df-dff3-407c-a08f-75f08c0806dc" 
      ] 
    } 
  }, 
  "grantControls": { 
    "operator": "OR", 
    "builtInControls": [ 
      "mfa" 
    ] 
  } 
} 

响应Response

{ 
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identity/conditionalAccess/policies/$entity", 
  "id": "9ad78153-b1f8-4714-adc1-1445727678a8", 
  "displayName": "Policy for risky sign-in", 
  "createdDateTime": "2020-11-03T20:56:38.6210843Z", 
  "modifiedDateTime": null, 
  "state": "enabled", 
  "sessionControls": null, 
  "conditions": { 
    "signInRiskLevels": [ 
      "high", 
      "medium" 
    ], 
    "clientAppTypes": [  
      "all"  
    ], 
    "platforms": null, 
    "locations": null, 
    "applications": { 
      "includeApplications": [ 
        "All" 
      ], 
      "excludeApplications": [], 
      "includeUserActions": [] 
    }, 
    "users": { 
      "includeUsers": [ 
        "4628e7df-dff3-407c-a08f-75f08c0806dc" 
      ], 
      "excludeUsers": [], 
      "includeGroups": [], 
      "excludeGroups": [], 
      "includeRoles": [], 
      "excludeRoles": [] 
    } 
  }, 
  "grantControls": { 
    "operator": "OR", 
    "builtInControls": [ 
      "mfa" 
    ], 
    "customAuthenticationFactors": [], 
    "termsOfUse": [] 
  } 
} 

在设置此条件访问策略后, 现在需要 MyTestUser1 帐户在登录时使用 MFA,因为登录风险级别为中或   高。With this conditional access policy in place, the MyTestUser1 account is now required to use MFA when signing in because the sign-in risk level is medium or high.

登录并完成多重身份验证Sign in and complete multi-factor authentication

通过登录匿名浏览器,将检测到风险,但通过完成 MFA 进行修正。By signing in to the anonymous browser, a risk is detected, but it is remediated by completing MFA.

  1. 打开浏览器并  portal.azure.com   输入站点地址。Open the browser and enter portal.azure.com for the site address.
  2. 使用 MyTestUser1 帐户的凭据登录到门户   并完成 MFA 过程。Sign in to the portal using the credentials for the MyTestUser1 account and complete the MFA process.

列出风险检测List risk detections

因为 MFA 已完成。Because MFA was completed. 现在,当您列出风险检测时 ,riskState 将事件显示为 remediatedNow, when you list risk detections the riskState shows the event as remediated.

请求Request

GET https://graph.microsoft.com/v1.0/identityProtection/riskDetections?$filter=userDisplayName eq 'MyTestUser1'

响应Response

{
  "id": "ba9d45f16d8f87f6ae974efda7336b2120962a398cb362dfd9e5bdc8e9d149d0",
  "requestId": "156c01fb-31cf-4a10-b9a9-beee93e6a400",
  "correlationId": "a8aaac45-fe22-46df-babf-10a8dba85d62",
  "riskType": "anonymizedIPAddress",
  "riskEventType": "anonymizedIPAddress",
  "riskState": "remediated",
  "riskLevel": "medium",
  "riskDetail": "userPassedMFADrivenByRiskBasedPolicy",
  "source": "IdentityProtection",
  "detectionTimingType": "realtime",
  "activity": "signin",
  "tokenIssuerType": "AzureAD",
  "ipAddress": "185.220.101.213",
  "activityDateTime": "2020-11-12T23:45:22.4092789Z",
  "detectedDateTime": "2020-11-12T23:45:22.4092789Z",
  "lastUpdatedDateTime": "2020-11-12T23:47:57.7831423Z",
  "userId": "4b608561-9258-44ba-8cdb-3286dcbf0e3b",
  "userDisplayName": "MyTestUser1",
  "userPrincipalName": "MyTestUser1@contoso.com",
    "additionalInfo": "[{\"Key\":\"userAgent\",\"Value\":\"Mozilla/5.0 (Windows NT 10.0; rv:78.0) Gecko/20100101 Firefox/78.0\"}]",
  "location": {
    "city": "Schoenwalde-Glien",
    "state": "Brandenburg",
    "countryOrRegion": "DE",
    "geoCoordinates": {
      "latitude": 52.61983,
      "longitude": 13.12743
    }
  }
}

步骤 4 (可选) 阻止用户登录Step 4 (Optional) Block the user from signing in

你可以阻止用户登录,而不是让用户自行修正。Instead of providing the opportunity for the user to self-remediate, you can block the user from signing in. 在此步骤中,您将创建一个新的条件访问策略,在出现中等或高风险检测时阻止用户登录。In this step, you create a new conditional access policy that blocks the user from signing in if a medium or high risk detection occurs. 策略中的区别在于 builtInControls 设置为 blockThe difference in policies is that the builtInControls is set to block.

请求Request

POST https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies
Content-type: application/json

{
  "displayName": "Policy for risky sign-in block access",
  "state": "enabled",
  "conditions": {
    "signInRiskLevels": [
      "high",
      "medium"
    ],
    "applications": {
      "includeApplications": ["All"]
    },
    "users": {
      "includeUsers": [
        "4628e7df-dff3-407c-a08f-75f08c0806dc"
      ]
    }
  },
  "grantControls": {
    "operator": "OR",
    "builtInControls": [
      "block"
    ]
  }
}

响应Response

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identity/conditionalAccess/policies/$entity",
  "id": "9ad78153-b1f8-4714-adc1-1445727678a8",
  "displayName": "Policy for risky sign-in block access",
  "createdDateTime": "2020-11-03T20:56:38.6210843Z",
  "modifiedDateTime": null,
  "state": "enabled",
  "sessionControls": null,
  "conditions": {
    "signInRiskLevels": [
      "high",
      "medium"
    ],
    "clientAppTypes": [ 
      "all" 
    ],
    "platforms": null,
    "locations": null,
    "applications": {
      "includeApplications": [
        "All"
      ],
      "excludeApplications": [],
      "includeUserActions": []
    },
    "users": {
      "includeUsers": [
        "4628e7df-dff3-407c-a08f-75f08c0806dc"
      ],
      "excludeUsers": [],
      "includeGroups": [],
      "excludeGroups": [],
      "includeRoles": [],
      "excludeRoles": []
    }
  },
  "grantControls": {
    "operator": "OR",
    "builtInControls": [
      "block"
    ],
    "customAuthenticationFactors": [],
    "termsOfUse": []
  }
}

在设置此条件访问策略后 ,MyTestUser1 帐户现在被阻止登录,因为登录风险级别是 mediumhighWith this conditional access policy in place, the MyTestUser1 account is now blocked from signing in because the sign-in risk level is medium or high.

阻止登录

步骤 5:消除有风险的用户Step 5: Dismiss risky users

如果您认为用户没有风险,并且不希望强制实施条件访问策略,您可以手动消除存在风险的用户。If you believe the user is not at risk, and you don’t want to enforce a conditional access policy, you can manually dismiss the risky user.

消除有风险的用户Dismiss the risky user

请求Request

POST https://graph.microsoft.com/v1.0/identityProtection/riskyUsers/dismiss
Content-Type: application/json

{
  "userIds": [
    "4628e7df-dff3-407c-a08f-75f08c0806dc"
  ]
}

响应Response

HTTP/1.1 204 No Content

列出有风险的用户List risky users

消除风险用户后,可以在列出风险用户时看到响应中 MyTestUser1 用户帐户现在具有风险级别和 none dismissed riskState。After dismissing the risk user, you can see in the response when listing risky users that the MyTestUser1 user account now has a risk level of none and a riskState of dismissed.

请求Request

GET https://graph.microsoft.com/v1.0/identityProtection/riskyUsers?$filter=userDisplayName eq 'MyTestUser1'

响应Response

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#riskyUsers",
  "value": [
    {
      "id": "4628e7df-dff3-407c-a08f-75f08c0806dc",
      "isDeleted": false,
      "isProcessing": false,
      "riskLevel": "none",
      "riskState": "dismissed",
      "riskDetail": "adminDismissedAllRiskForUser",
      "riskLastUpdatedDateTime": "2020-11-03T21:48:53.4298425Z",
      "userDisplayName": "MyTestUser1",
      "userPrincipalName": "MyTestUser1@contoso.com"
    }
  ]
}

步骤 6:清理资源Step 6: Clean up resources

在此步骤中,将删除创建的资源。In this step, you remove the resources that you created.

删除用户帐户Delete the user account

删除 MyTestUser1 用户帐户。Delete the MyTestUser1 user account.

请求Request

DELETE https://graph.microsoft.com/v1.0/users/4628e7df-dff3-407c-a08f-75f08c0806dc

响应Response

No Content - 204

删除条件访问策略Delete the conditional access policy

删除创建的条件访问策略。Delete the conditional access policy that you created.

请求Request

DELETE https://graph.microsoft.com/v1.0/groups/9ad78153-b1f8-4714-adc1-1445727678a8

响应Response

No Content - 204

另请参阅See also

在本教程中,你使用了许多 API 来完成任务。In this tutorial, you used many APIs to accomplish tasks. 浏览这些 API 的 API 参考,详细了解 API 可以执行哪些操作。Explore the API reference for these APIs to learn more about what the APIs can do.