From 289b828ca11fdf206db5c9dab74241b6518fbda1 Mon Sep 17 00:00:00 2001 From: jcaparas Date: Tue, 14 Mar 2017 16:57:40 -0700 Subject: [PATCH 1/6] SEO updates --- ...om-ti-api-windows-defender-advanced-threat-protection.md | 2 +- ...custom-ti-windows-defender-advanced-threat-protection.md | 6 +++--- ...-concepts-windows-defender-advanced-threat-protection.md | 2 +- ...custom-ti-windows-defender-advanced-threat-protection.md | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md index 8c54c753a6..a305a2dc41 100644 --- a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md @@ -1,5 +1,5 @@ --- -title: Create custom threat intelligence using REST API in Windows Defender ATP +title: Create threat intelligence using REST API in Windows Defender ATP description: Create your custom alert definitions and indicators of compromise in Windows Defender ATP using the available APIs in Windows Enterprise, Education, and Pro editions. keywords: alert definitions, indicators of compromise, threat intelligence, custom threat intelligence, rest api, api search.product: eADQiWindows 10XVcnh diff --git a/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md b/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md index e62a85a083..47189ede43 100644 --- a/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/enable-custom-ti-windows-defender-advanced-threat-protection.md @@ -1,6 +1,6 @@ --- -title: Enable the custom threat intelligence application in Windows Defender ATP -description: Enable the custom threat intelligence application in Windows Defender ATP so that you can create custom threat intelligence using REST API. +title: Enable the custom threat intelligence API in Windows Defender ATP +description: Learn how to setup the custom threat intelligence application in Windows Defender ATP to create custom threat intelligence (TI). keywords: enable custom threat intelligence application, custom ti application, application name, client id, authorization url, resource, client secret, access tokens search.product: eADQiWindows 10XVcnh ms.prod: w10 @@ -11,7 +11,7 @@ author: mjcaparas localizationpriority: high --- -# Enable the custom threat intelligence application +# Enable the custom threat intelligence API in Windows Defender ATP **Applies to:** diff --git a/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md b/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md index be6cfe9d8e..07cf221238 100644 --- a/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/threat-indicator-concepts-windows-defender-advanced-threat-protection.md @@ -1,6 +1,6 @@ --- title: Understand threat intelligence concepts in Windows Defender ATP -description: Understand the concepts around threat intelligence in Windows Defender Advanced Threat Protection so that you can effectively create custom intelligence for your organization. +description: Create custom threat alerts for your organization and learn the concepts around threat intelligence in Windows Defender Advanced Threat Protection. keywords: threat intelligence, alert definitions, indicators of compromise, ioc search.product: eADQiWindows 10XVcnh ms.prod: w10 diff --git a/windows/keep-secure/use-custom-ti-windows-defender-advanced-threat-protection.md b/windows/keep-secure/use-custom-ti-windows-defender-advanced-threat-protection.md index 0757a26702..cf9af66f72 100644 --- a/windows/keep-secure/use-custom-ti-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/use-custom-ti-windows-defender-advanced-threat-protection.md @@ -1,6 +1,6 @@ --- -title: Use the threat intelligence API in Windows Defender Advanced Threat Protection to create custom alerts -description: Use the custom threat intelligence API to create custom alerts for your organization. +title: Use the custom threat intelligence API to create custom alerts for your organization +description: Use the threat intelligence API in Windows Defender Advanced Threat Protection to create custom alerts keywords: threat intelligence, alert definitions, indicators of compromise search.product: eADQiWindows 10XVcnh ms.prod: w10 From ae49a5f6e718ea20432fcad578c507d565feaebc Mon Sep 17 00:00:00 2001 From: jcaparas Date: Tue, 14 Mar 2017 17:52:35 -0700 Subject: [PATCH 2/6] add request access token from issuing endpoint --- ...ows-defender-advanced-threat-protection.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md index a305a2dc41..8fc3cfeabe 100644 --- a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md @@ -28,6 +28,41 @@ You can define custom alert definitions and indicators of compromise (IOC) using ## Before you begin Before creating custom alerts, you'll need to enable the threat intelligence application in Azure Active Directory and generate access tokens. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). +## Request an access token from the token issuing endpoint +The custom TI feature uses the OAuth 2.0 protocol to enable you to access alerts in Windows Defender ATP. In the context of Windows Defender ATP, the alerts from the portal are a protected resource. To issue tokens for ad-hoc, non-automatic operations you can use the **Preferences settings** page and click the **Generate Token** button. However, if you’d like to create an automated client, you need to use the “Client Credentials Grant” flow. For more information, see the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749#section-4.4). + +For more information about the authorization flow, see [OAuth 2.0 authorization flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code#oauth-20-authorization-flow). + +Make an HTTP POST request to the token issuing endpoint with the following parameters, replacing ``, ``, and `` with your app's client ID, client secret, and application key, respectively. + +>[!NOTE] +> The ``, ``, and the `` are all provided to you when enabling the custom threat intelligence application. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). + + +``` +POST HTTP/1.1 +Content-Type: application/x-www-form-urlencoded + +grant_type=client_credentials +&client_id= +&client_secret= +&resource=https://graph.microsoft.com +``` +The response will include an access token and expiry information. + +```json +{ + "token_type": "Bearer", + "expires_in": "3599", + "ext_expires_in": "0", + "expires_on": "1449685363", + "not_before": "1449681463", + "resource": "https://graph.microsoft.com", + "access_token": "" +} + +``` + ### Use the threat intelligence REST API to create custom threat intelligence alerts You can call and specify the resource URLs using one of the following operations to access and manipulate a threat intelligence resource, you call and specify the resource URLs using one of the following operations: From 96740938fe54b23d69969ca2dde183c9ed65dc5a Mon Sep 17 00:00:00 2001 From: jcaparas Date: Tue, 14 Mar 2017 18:20:24 -0700 Subject: [PATCH 3/6] add authentication server URL --- ...custom-ti-api-windows-defender-advanced-threat-protection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md index 8fc3cfeabe..0dc7c29878 100644 --- a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md @@ -33,7 +33,7 @@ The custom TI feature uses the OAuth 2.0 protocol to enable you to access alerts For more information about the authorization flow, see [OAuth 2.0 authorization flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code#oauth-20-authorization-flow). -Make an HTTP POST request to the token issuing endpoint with the following parameters, replacing ``, ``, and `` with your app's client ID, client secret, and application key, respectively. +Make an HTTP POST request to the token issuing endpoint with the following parameters, replacing ``, ``, and `` with your app's client ID, client secret, authentication server URL, and application key. >[!NOTE] > The ``, ``, and the `` are all provided to you when enabling the custom threat intelligence application. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). From 929f52ace8a223d668130b0fccd0bba0113389af Mon Sep 17 00:00:00 2001 From: AssafKr Date: Wed, 15 Mar 2017 09:57:26 +0200 Subject: [PATCH 4/6] Update custom-ti-api-windows-defender-advanced-threat-protection.md Made some small correction and added a new note --- ...ows-defender-advanced-threat-protection.md | 73 ++++++++++--------- 1 file changed, 38 insertions(+), 35 deletions(-) diff --git a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md index 0dc7c29878..413a363fdd 100644 --- a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md @@ -28,41 +28,6 @@ You can define custom alert definitions and indicators of compromise (IOC) using ## Before you begin Before creating custom alerts, you'll need to enable the threat intelligence application in Azure Active Directory and generate access tokens. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). -## Request an access token from the token issuing endpoint -The custom TI feature uses the OAuth 2.0 protocol to enable you to access alerts in Windows Defender ATP. In the context of Windows Defender ATP, the alerts from the portal are a protected resource. To issue tokens for ad-hoc, non-automatic operations you can use the **Preferences settings** page and click the **Generate Token** button. However, if you’d like to create an automated client, you need to use the “Client Credentials Grant” flow. For more information, see the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749#section-4.4). - -For more information about the authorization flow, see [OAuth 2.0 authorization flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code#oauth-20-authorization-flow). - -Make an HTTP POST request to the token issuing endpoint with the following parameters, replacing ``, ``, and `` with your app's client ID, client secret, authentication server URL, and application key. - ->[!NOTE] -> The ``, ``, and the `` are all provided to you when enabling the custom threat intelligence application. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). - - -``` -POST HTTP/1.1 -Content-Type: application/x-www-form-urlencoded - -grant_type=client_credentials -&client_id= -&client_secret= -&resource=https://graph.microsoft.com -``` -The response will include an access token and expiry information. - -```json -{ - "token_type": "Bearer", - "expires_in": "3599", - "ext_expires_in": "0", - "expires_on": "1449685363", - "not_before": "1449681463", - "resource": "https://graph.microsoft.com", - "access_token": "" -} - -``` - ### Use the threat intelligence REST API to create custom threat intelligence alerts You can call and specify the resource URLs using one of the following operations to access and manipulate a threat intelligence resource, you call and specify the resource URLs using one of the following operations: @@ -89,6 +54,44 @@ For this URL: **Quotas**
Each tenant has a defined quota that limits the number of possible alert definitions, IOCs and another quota for IOCs of Action different than “equals” in the system. If you upload data beyond this quota, you'll encounter an HTTP error status code 507 (Insufficient Storage). +## Request an access token from the token issuing endpoint +The custom TI feature uses the OAuth 2.0 protocol to enable you to access alerts in Windows Defender ATP. In the context of Windows Defender ATP, the alerts from the portal are a protected resource. To issue tokens for ad-hoc, non-automatic operations you can use the **Preferences settings** page and click the **Generate Token** button. However, if you’d like to create an automated client, you need to use the “Client Credentials Grant” flow. For more information, see the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749#section-4.4). + +For more information about the authorization flow, see [OAuth 2.0 authorization flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code#oauth-20-authorization-flow). + +Make an HTTP POST request to the token issuing endpoint with the following parameters, replacing ``, ``, and `` with your app's client ID, client secret and authorization server URL. + +>[!NOTE] +> The authorization server URL is `https://login.windows.net//oauth2/token`. Replace `` with your Azure Active Directory tenant ID. + +>[!NOTE] +> The ``, ``, and the `` are all provided to you when enabling the custom threat intelligence application. For more information, see [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md). + + +``` +POST HTTP/1.1 +Content-Type: application/x-www-form-urlencoded + +grant_type=client_credentials +&client_id= +&client_secret= +&resource=https://graph.microsoft.com +``` +The response will include an access token and expiry information. + +```json +{ + "token_type": "Bearer", + "expires_in": "3599", + "ext_expires_in": "0", + "expires_on": "1449685363", + "not_before": "1449681463", + "resource": "https://graph.microsoft.com", + "access_token": "" +} + +``` + ## Threat intelligence API metadata The metadata document ($metadata) is published at the service root. From d77091912f978f9a1b18af57f746f0b80aa74e4b Mon Sep 17 00:00:00 2001 From: Joey Caparas Date: Wed, 15 Mar 2017 13:22:49 -0700 Subject: [PATCH 5/6] updates from michael p. --- ...custom-ti-api-windows-defender-advanced-threat-protection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md index 413a363fdd..e8032882a1 100644 --- a/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/custom-ti-api-windows-defender-advanced-threat-protection.md @@ -55,7 +55,7 @@ For this URL: Each tenant has a defined quota that limits the number of possible alert definitions, IOCs and another quota for IOCs of Action different than “equals” in the system. If you upload data beyond this quota, you'll encounter an HTTP error status code 507 (Insufficient Storage). ## Request an access token from the token issuing endpoint -The custom TI feature uses the OAuth 2.0 protocol to enable you to access alerts in Windows Defender ATP. In the context of Windows Defender ATP, the alerts from the portal are a protected resource. To issue tokens for ad-hoc, non-automatic operations you can use the **Preferences settings** page and click the **Generate Token** button. However, if you’d like to create an automated client, you need to use the “Client Credentials Grant” flow. For more information, see the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749#section-4.4). +Windows Defender ATP Threat Intelligence API uses OAuth 2.0. In the context of Windows Defender ATP, the alert definitions are a protected resource. To issue tokens for ad-hoc, non-automatic operations you can use the **Preferences settings** page and click the **Generate Token** button. However, if you’d like to create an automated client, you need to use the “Client Credentials Grant” flow. For more information, see the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749#section-4.4). For more information about the authorization flow, see [OAuth 2.0 authorization flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code#oauth-20-authorization-flow). From 55fefbb0999d97d74239cf57957a6dbc41b78ed2 Mon Sep 17 00:00:00 2001 From: Joey Caparas Date: Wed, 15 Mar 2017 13:26:41 -0700 Subject: [PATCH 6/6] add application name in troubleshooting --- ...oot-custom-ti-windows-defender-advanced-threat-protection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md b/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md index d63bd1bf4c..04fdd96eb0 100644 --- a/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md +++ b/windows/keep-secure/troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md @@ -37,7 +37,7 @@ If your client secret expires or if you've misplaced the copy provided when you 3. Select your tenant. -4. Click **Application**, then select your custom threat intelligence application. +4. Click **Application**, then select your custom threat intelligence application. The application name is **WindowsDefenderATPThreatIntelAPI** (formerly known as **WindowsDefenderATPCustomerTiConnector**). 5. Select **Keys** section, then provide a key description and specify the key validity duration.