Add general doc for delegated Vs application permissions

windows/security/threat-protection/windows-defender-atp/TOC.md

@@ -97,13 +97,16 @@
 #### [Experiment with custom threat intelligence alerts](experiment-custom-ti-windows-defender-advanced-threat-protection.md)
 #### [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md)
 
-### [**Beta!** Use Windows Defender ATP APIs](exposed-apis-windows-defender-advanced-threat-protection-new.md)
+### [**Beta!** Windows Defender ATP APIs](exposed-apis-intro.md)
-#### [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection-new.md)
+#### Create your app
-##### [Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection.md)
+##### [Get access on behalf of a user](exposed-apis-create-app-nativeapp.md)
+##### [Get access without a user](exposed-apis-create-app-webapp.md)
+#### [Supported Windows Defender ATP APIs](exposed-apis-list.md)
+##### [Advanced Hunting](run-advanced-query-api.md)
 #### How to use APIs - Samples
-##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md)
+##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md)
-##### [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md)
+##### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
-##### [Advanced Hunting using Python](run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md)
+##### [Advanced Hunting using Python](run-advanced-query-sample-python.md)
 
 
 ### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md)

windows/security/threat-protection/windows-defender-atp/advanced-hunting-windows-defender-advanced-threat-protection.md

@@ -161,6 +161,6 @@ Check out the [Advanced Hunting repository](https://github.com/Microsoft/Windows
 ## Related topic
 - [Advanced hunting reference](advanced-hunting-reference-windows-defender-advanced-threat-protection.md)
 - [Advanced hunting query language best practices](advanced-hunting-best-practices-windows-defender-advanced-threat-protection.md)
-- [Programmatic Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection.md)
+- [Programmatic Advanced Hunting](run-advanced-query-api.md)
 
 

windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-nativeapp.md

@@ -26,6 +26,12 @@ ms.date: 30/07/2018
 
 >Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
 
+This pages describes how to create an application to get programmatical access to Windows Defender ATP on behalf of a user.
+
+If you need programmatical access Windows Defender ATP without a user, please refer to [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md)
+
+If you are not sure which access you need, you'd better read the [Introduction page](exposed-apis-intro.md)
+
 Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
 
 In general, you’ll need to take the following steps to use the APIs:
@@ -146,11 +152,11 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
 
 ### Using PowerShell 
 
-Refer to [Get token using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md#get-token)
+Refer to [Get token using PowerShell](run-advanced-query-sample-powershell.md#get-token)
 
 ### Using Python
 
-Refer to [Get token using Python](run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md#get-token)
+Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token)
 
 ### Using Curl
 
@@ -181,4 +187,6 @@ You will get an answer of the form:
 ![Image of token validation](images/webapp-validate-token.png)
 
 ## Related topics
-- [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection-new.md)
+- [Windows Defender ATP APIs](exposed-apis-intro.md)
+- [Supported Windows Defender ATP APIs](exposed-apis-list.md)
+- [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md)

windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-webapp.md

@@ -0,0 +1,192 @@
+---
+title: Use Windows Defender Advanced Threat Protection APIs  
+description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
+keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+ms.date: 30/07/2018
+---
+
+# Create an app to access Windows Defender ATP without a user
+
+**Applies to:**
+
+- Windows 10 Enterprise
+- Windows 10 Education
+- Windows 10 Pro
+- Windows 10 Pro Education
+- Windows Defender Advanced Threat Protection (Windows Defender ATP)
+
+
+>Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+
+This pages describes how to create an application to get programmatical access to Windows Defender ATP without a user.
+
+If you need programmatical access Windows Defender ATP on behalf of a user, please refer to [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md)
+
+If you are not sure which access you need, you'd better read the [Introduction page](exposed-apis-intro.md)
+
+Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
+
+In general, you’ll need to take the following steps to use the APIs:
+- Create an app
+- Get an access token
+- Use the token to access Windows Defender ATP API
+
+This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission.
+
+## Create an app
+
+1.	Log on to [Azure](https://portal.azure.com).
+
+2.	Navigate to **Azure Active Directory** > **App registrations** > **New application registration**. 
+
+    ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app.png)
+
+3.	In the Create window, enter the following information then click **Create**.
+
+    ![Image of Create application window](images/webapp-create.png)
+
+    - **Name:** WdatpEcosystemPartner
+    - **Application type:** Web app / API
+    - **Redirect URI:** `https://WdatpEcosystemPartner.com` (The URL where user can sign in and use your app. You can change this URL later.)
+
+
+4.	Click **Settings** > **Required permissions** > **Add**.
+
+    ![Image of new app in Azure](images/webapp-add-permission.png)
+
+5.	Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
+	
+	**Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
+
+    ![Image of API access and API selection](images/webapp-add-permission-2.png)
+
+6. Click **Select permissions** > **Run advanced queries** > **Select**.
+	
+	**Important note**: You need to select the relevant permission. 'Run advanced queries' is only an example!
+
+    ![Image of select permissions](images/webapp-select-permission.png)
+
+	- In order to send telemetry events to WDATP, check 'Write timeline events' permission
+	- In order to send TI events to WDATP, check 'Read and write IOCs belonging to the app' permission
+	- In order to run advanced queries in WDATP, check 'Run advanced queries' permission
+
+7. Click **Done**
+
+    ![Image of add permissions completion](images/webapp-add-permission-end.png)
+
+8. Click **Keys** and type a key name and click **Save**.
+
+	**Important**: After you save, **copy the key value**. You won't be able to retrieve after you leave!
+
+    ![Image of create app key](images/webapp-create-key.png)
+
+9. Write down your application ID.
+    
+	![Image of app ID](images/webapp-get-appid.png)
+
+9. Set your application to be multi-tenanted
+	
+	This is **required** for 3rd party apps (i.e., if you create an application that is intended to run in multiple customers tenant).
+
+	This is **not required** if you create a service that you want to run in your tenant only (i.e., if you create an application for your own usage that will only interact with your own data)​
+
+	Click **Properties** > **Yes** > **Save**.
+
+	![Image of multi tenant](images/webapp-edit-multitenant.png)
+
+
+## Application consent
+
+You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer.
+
+You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory.
+
+Consent link is of the form: 
+
+```
+https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true​
+```
+
+where 00000000-0000-0000-0000-000000000000​ should be replaced with your Azure application ID
+
+
+## Get an access token
+
+For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
+
+### Using C#
+
+>The below code was tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8
+
+- Create a new Console Application
+- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/)
+- Add the below using
+
+	```
+	using Microsoft.IdentityModel.Clients.ActiveDirectory;
+	```
+
+- Copy/Paste the below code in your application (do not forget to update the 3 variables: ```tenantId, appId, appSecret```)
+
+	```
+	string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
+	string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
+	string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here
+
+	const string aadUri = "https://login.windows.net";
+	const string wdatpResourceId = "https://securitycenter.onmicrosoft.com/windowsatpservice";
+
+	AuthenticationContext auth = new AuthenticationContext($"{aadUri}/{tenantId}/");
+	ClientCredential clientCredential = new ClientCredential(appId, appSecret);
+	AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
+	string token = authenticationResult.AccessToken;
+	```
+
+### Using PowerShell 
+
+Refer to [Get token using PowerShell](run-advanced-query-sample-powershell.md#get-token)
+
+### Using Python
+
+Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token)
+
+### Using Curl
+
+> [!NOTE]
+> The below procedure supposed Curl for Windows is already installed on your computer
+
+- Open a command window
+- ​Set CLIENT_ID to your Azure application ID
+- Set CLIENT_SECRET to your Azure application secret
+- Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access WDATP application
+- Run the below command:
+
+```
+curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice​/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID​%/oauth2/v2.0/token" -k​
+```
+
+You will get an answer of the form:
+
+```
+{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
+```
+
+## Validate the token
+
+- Copy/paste into [JWT](https://jwt.io/) the token you get in the previous step 
+- Validate you get a 'roles' claim with the desired permission, as shown in the below screenshot
+
+![Image of token validation](images/webapp-validate-token.png)
+
+## Related topics
+- [Windows Defender ATP APIs](exposed-apis-intro.md)
+- [Supported Windows Defender ATP APIs](exposed-apis-list.md)
+- [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md)

windows/security/threat-protection/windows-defender-atp/exposed-apis-intro.md

@@ -0,0 +1,58 @@
+---
+title: Use Windows Defender Advanced Threat Protection APIs  
+description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
+keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+ms.date: 30/07/2018
+---
+
+# Use Windows Defender ATP APIs 
+
+**Applies to:**
+
+- Windows 10 Enterprise
+- Windows 10 Education
+- Windows 10 Pro
+- Windows 10 Pro Education
+- Windows Defender Advanced Threat Protection (Windows Defender ATP)
+
+
+>Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+
+Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
+
+In general, you’ll need to take the following steps to use the APIs:
+- Create an app
+- Get an access token
+- Use the token to access Windows Defender ATP API
+
+
+As a developer, you decide which permissions for Windows Defender ATP your app requests. When a user signs in to your app he (or, in some cases, an administrator) is given a chance to consent to these permissions. If the user consents, your app is given access to the resources and APIs that it has requested. For apps that don't take a signed-in user, permissions can be pre-consented to by an administrator when the app is installed or during sign-up.
+
+##Delegated permissions, Application permissions, and effective permissions
+
+Windows Defender ATP has two types of permissions: delegated permissions and application permissions.
+
+- Delegated permissions are used by apps that have a signed-in user present. For these apps either the user or an administrator consents to the permissions that the app requests and the app is delegated permission to act as the signed-in user when making calls to Windows Defender ATP. Some delegated permissions can be consented to by non-administrative users, but some higher-privileged permissions require administrator consent.
+- Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. Application permissions can only be consented by an administrator.
+
+Effective permissions are the permissions that your app will have when making requests to Windows Defender ATP. It is important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to Windows Defender ATP.
+
+- For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. Your app can never have more privileges than the signed-in user. Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. For more information about administrator roles, see [Assigning administrator roles in Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/active-directory-assign-admin-roles).
+
+	For example, assume your app has been granted the Machine.CollectForensics delegated permission. This permission nominally grants your app permission to collect investigation package from a machine. If the signed-in user has 'Alerts Investigation' permission, your app will be able to collect investigation package from a machine, if the machine belongs to a group the user is exposed to. However, if the signed-in user doesn't have 'Alerts Investigation' permission, your app won't be able to collect investigation package from any machine.
+
+- For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. For example, an app that has the Machine.CollectForensics application permission can collect investigation package from any machine in the organization.
+
+
+## Related topics
+- [Supported Windows Defender ATP APIs](exposed-apis-list.md)
+- [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md)
+- [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md)

windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md

@@ -41,4 +41,4 @@ Machines | Run API calls such as find machine information by IP, get machines, g
 User | Run API calls such as get alert related user information, user information, user related alerts, and user related machines.
 
 ## Related topic
-- [Use Windows Defender ATP APIs](exposed-apis-windows-defender-advanced-threat-protection-new.md)
+- [Windows Defender ATP APIs](exposed-apis-intro.md)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-api.md

@@ -31,7 +31,7 @@ This API is a beta version only and is currently restricted
 3. The nu​mber of executions is limited​ (up to 15 minutes every hour and 4 hours a day)
 
 ## Permissions
-One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
+One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-intro.md#create-an-app)
 
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
@@ -127,12 +127,12 @@ Content-Type: application/json​
 - (403) Forbidden.
 	
 	If you get this error when calling WDATP API, your token probably does not include the necessary permission,
-	[Check the permissions](exposed-apis-windows-defender-advanced-threat-protection-new.md#validate-the-token) included in your token.
+	[Check the permissions](exposed-apis-intro.md#validate-the-token) included in your token.
-	If the 'roles' section in the token does not include the necessary permission, either you did not add the necessary permission to your app (refer to step 6 in [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)) or you did not authorized your app in the tenant (refer to [Application consent](exposed-apis-windows-defender-advanced-threat-protection-new.md#application-consent))
+	If the 'roles' section in the token does not include the necessary permission, either you did not add the necessary permission to your app (refer to step 6 in [Create your app](exposed-apis-intro.md#create-an-app)) or you did not authorized your app in the tenant (refer to [Application consent](exposed-apis-intro.md#application-consent))
 
 
 ## Related topic
+- [Windows Defender ATP APIs](exposed-apis-intro.md)
 - [Advanced Hunting from Portal](advanced-hunting-windows-defender-advanced-threat-protection.md)
-- [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md)
+- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
-- [Schedule Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md)
+- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)
-- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md

@@ -21,7 +21,7 @@ ms.date: 30/07/2018
 
 Schedule advanced query.
 
->**Prerequisite**: You first need to [create an app](exposed-apis-windows-defender-advanced-threat-protection-new.md).
+>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
 
 ## Use case
 
@@ -81,6 +81,6 @@ You can find below the full definition
 ![Image of E2E flow](images/ms-flow-e2e.png)
 
 ## Related topic
-- [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md)
+- [Windows Defender ATP APIs](exposed-apis-intro.md)
-- [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md)
+- [Advanced Hunting API](run-advanced-query-api.md)
-- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)
+- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-powershell.md

@@ -15,11 +15,11 @@ ms.date: 30/07/2018
 
 # Advanced Hunting using PowerShell
 
-Run advanced queries using PowerShell. Please read about [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) before.
+Run advanced queries using PowerShell. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
 
 In this section we share PowerShell samples to retrieve a token and use it to run a query.
 
->**Prerequisite**: You first need to [create an app](exposed-apis-windows-defender-advanced-threat-protection-new.md).
+>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
 
 ## Preparation Instructions
 
@@ -107,7 +107,7 @@ $results | ConvertTo-Json | Set-Content file1.json
 
 
 ## Related topic
-- [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md)
+- [Windows Defender ATP APIs](exposed-apis-intro.md)
-- [Advanced Hunting using Python](run-advanced-query-windows-defender-advanced-threat-protection-sample-python.md)
+- [Advanced Hunting API](run-advanced-query-api.md)
-- [Schedule Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md)
+- [Advanced Hunting using Python](run-advanced-query-sample-python.md)
-- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)
+- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-python.md

@@ -15,11 +15,11 @@ ms.date: 30/07/2018
 
 # Advanced Hunting using Python
 
-Run advanced queries using Python. Please read about [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) before.
+Run advanced queries using Python. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
 
 In this section we share Python samples to retrieve a token and use it to run a query.
 
->**Prerequisite**: You first need to [create an app](exposed-apis-windows-defender-advanced-threat-protection-new.md).
+>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
 
 ## Get token
 
@@ -136,7 +136,7 @@ outputFile.close()
 
 
 ## Related topic
-- [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md)
+- [Windows Defender ATP APIs](exposed-apis-intro.md)
-- [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md)
+- [Advanced Hunting API](run-advanced-query-api.md)
-- [Schedule Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md)
+- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
-- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)
+- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)