diff --git a/content-repo/extra-docs/articles/microsoft-auth-guide.md b/content-repo/extra-docs/articles/microsoft-auth-guide.md index acca3f1b9..253f8100c 100644 --- a/content-repo/extra-docs/articles/microsoft-auth-guide.md +++ b/content-repo/extra-docs/articles/microsoft-auth-guide.md @@ -3,27 +3,31 @@ title: Microsoft Integrations - Authentication description: Authentication method for Microsoft Graph and Azure integrations in Cortex XSOAR. --- -:::info Security Awareness: Device Code Authorization -It is recommended to use the client credentials and user authorization flows for integrations when possible. The device code authorization flow has limited protections against sophisticated phishing campaigns. - -In no scenario emails or other forms of communication will be sent to the customer asking to enter a security code or follow a link. All generated links and codes will be shown in the War Room, by running the official integration commands. +This document includes the following sections to help you understand, set up, and use the integration effectively: -More info at: [Device Code flow - Evolved phishing](https://www.microsoft.com/security/blog/2022/01/26/evolved-phishing-device-registration-trick-adds-to-phishers-toolbox-for-victims-without-mfa/) +- [Cortex XSOAR Application](#cortex-xsoar-application) +- [Self Deployed Application](#self-deployed-application) +- [Using National Cloud](#using-national-cloud) +- [Authentication Flows](#authentication-flows) +- [Azure Managed Identities Authentication](#azure-managed-identities-authentication) +- [How to find Azure Integrations Parameters](#how-to-find-azure-integrations-parameters) +- [Troubleshooting](#troubleshooting) -::: +Microsoft integrations (Graph and Azure) in Cortex XSOAR/XSIAM use Azure Active Directory (Azure AD) applications to securely authenticate with Microsoft APIs. These applications act as the bridge between XSOAR/XSIAM and Microsoft services, defining which API requests can be performed and what level of access is granted. The permissions and roles configured in the Azure application determine what data and actions the integration is authorized to access within your tenant. -Microsoft's integrations (Graph and Azure) in Cortex XSOAR use Azure Active Directory applications to authenticate with Microsoft APIs. These integrations use OAuth 2.0 and OpenID Connect standard-compliant authentication services, which use an **Application** to sign-in or delegate authentication. -For more information, see the [Microsoft identity platform overview](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-overview). +Usually, you need to create your own application via Azure Portal and to set the API permissions, this is a self-deployed application. Alternatively, XSOAR/XSIAM suggests another solution where you can use the application XSOAR/XSIAM builds for you, this is the Cortex XSOAR application. In addition, for environments running within Azure, you can authenticate using Azure Managed Identities, which allow XSOAR/XSIAM to access Azure resources securely without managing credentials manually. -There are three application authentication methods available: +Therefore, three application authentication methods are available: 1. [Cortex XSOAR Application](#cortex-xsoar-application) 2. [Self Deployed Application](#self-deployed-application) 3. [Azure Managed Identities](#azure-managed-identities-authentication) -## Cortex XSOAR Application +You must use one of these authentication methods. + +# Cortex XSOAR Application In this method, you grant consent for the Cortex XSOAR multi-tenant application to access your data. The application is maintained by Cortex XSOAR. -Depending on the integration, this requires either admin consent to [get access without a user](https://docs.microsoft.com/en-us/graph/auth-v2-service) or user consent to [get access on behalf of a user](https://docs.microsoft.com/en-us/graph/auth-v2-user). +Depending on the integration, this requires either admin consent to [access data without a user](https://docs.microsoft.com/en-us/graph/auth-v2-service) or user consent to [access data on behalf of a user](https://docs.microsoft.com/en-us/graph/auth-v2-user). **Note**: This method requires that you give consent to all permissions requested by the application. @@ -36,93 +40,228 @@ To start the authentication process, go to the integration's detailed instructio -5. In the XSOAR Web Page that appears, click the **Start Authorization Process** button to initiate the authorization flow. - You will receive your ID, token, and key. You need to enter this information, when you configure the integration instance in Cortex XSOAR. +5. In the XSOAR Web Page that appears, click **Start Authorization Process** to initiate the authorization flow. + You will receive your ID, token, and key. Go back to the instance configuration and copy: ID -> App/client ID, token -> Tenant ID, key -> Client Secret. + Click "Test". The instance should be configured successfully. + +# Self Deployed Application +To use a self-configured Azure application, add a new Azure App Registration in the Azure Portal. +For instructions on adding the registration, see the [Microsoft documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) -## Self Deployed Application +The application must have the required permissions and roles for the relevant APIs, as documented in the integration documentation. For example, see [Microsoft Defender Advanced Threat Protection required permissions](https://xsoar.pan.dev/docs/reference/integrations/microsoft-defender-advanced-threat-protection#required-permissions). -To use a self-configured Azure application, you need to add a new Azure App Registration in the Azure Portal. +The authentication flow you choose depends on the integration’s purpose and the target it acts on: -The application must have the required permissions for the relevant APIs, which are documented in the integration documentation, for example see [Microsoft Defender Advanced Threat Protection required permissions](https://xsoar.pan.dev/docs/reference/integrations/microsoft-defender-advanced-threat-protection#required-permissions). +- **Client Credentials Flow:** Used on behalf of the application. The integration authenticates as the application itself, not a user, allowing it to perform API requests at the tenant or organization level. +- **Authoriztion Code Flow:** Used on behalf of a signed-in user through an interactive login. +This flow grants access based on the user’s permissions and is ideal for integrations that require user consent or need to act under a specific user’s identity. +- **Device Code Flow:** When configured using this flow, the integration operates under the user’s context, similar to the authorization code flow, but it is designed for devices or environments where a browser-based login is not available. -To add the registration, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) +#### Permission Types and Flows +- **Delegated permissions** are used when the integration acts on behalf of a signed-in user. These permissions require either the **Authorization Code Flow** or **Device Code Flow**. +- **Application permissions** are used when the integration acts as the application itself, without a user. These permissions require the **Client Credentials Flow**. + + + +You can read more about each flow in the relevant sections below. + +**Note:** When adding a new permission to the application, you must run the `!-auth-reset` command for the permission to take effect. If you are using the device code flow or authorization code flow, you must also reconnect and create a new authorization code. The new token used in the integration, will the include the new permission. ### Using National Cloud - To see which integrations support natively National Clouds,See the [table below.](https://xsoar.pan.dev/docs/reference/articles/microsoft-integrations---authentication#supported-authentication-flows-for-microsoft-integrations) - For Microsoft Azure integrations, select the appropriate cloud using the *Azure Cloud* parameter. - For Microsoft Defender, select the appropriate cloud using the *Endpoint Type* parameter. - - For using the self-deployment option, select the *Custom* option and follow the instructions below. + - To use the self-deployment option, select *Custom* and follow the instructions below. + +- Some Cortex XSOAR/XSIAM Microsoft integrations support the deployment of national clouds through the self-deployed + authorization flow. For more information about Microsoft National Clouds, see the [Microsoft documentation](https://docs.microsoft.com/en-us/graph/deployments). + To use a national cloud, change the *Server URL* parameter to the corresponding address of the national cloud you are using. + +# Authentication Flows + +:::info Security Awareness: Device Code Authorization +It is recommended to use the Client Credentials or User Authorization flows for integrations whenever possible. The Device Code Authorization flow provides limited protection against sophisticated phishing campaigns. + +Under no circumstances will emails or other forms of communication be sent to the customer asking them to enter a security code or follow a link. All generated links and codes are displayed in the War Room by running the official integration commands. + +For more information, see [Device Code flow - Evolved phishing](https://www.microsoft.com/security/blog/2022/01/26/evolved-phishing-device-registration-trick-adds-to-phishers-toolbox-for-victims-without-mfa/) + +::: + +## Client Credentials Flow +Some Cortex XSOAR/XSIAM Microsoft integrations use the [Client Credentials Flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow). +When configured using this flow, the integration operates at the organization (tenant) level, allowing actions to be performed across the entire tenant. This flow typically uses application permissions, which must be defined in the Azure application configuration within the Azure Portal. These permissions determine that all XSOAR/XSIAM commands executed through this authentication method act within the organization or tenant scope. + +For this flow, the Tenant ID, Client ID, and Client Secret are required for the integration. You can get those values from the Azure Portal under the application information. +Follow these steps: + +1. Sign in to the Azure Portal. +2. Search for you application using your application name or ID. You can find it under the "App registrations" or use the search bar. +3. When you locate the application, click it and go to the Overview section. +4. Copy the "Application (client) ID" and paste it in the App/Client ID parameter field in the XSOAR/XSIAM instance configuration. +5. Copy the "Directory (tenant) ID" and paste it in the Token/Tenant ID parameter field in the XSOAR/XSIAM instance configuration. +6. In the application configuration, go to "Certificates & secrets", click "New client secret", then click "Add". Copy the secret **value** and paste it into the Client Secret parameter field in the XSOAR/XSIAM instance configuration. +7. In the instance configuration, select the ***Use a self-deployed Azure Application*** checkbox. +8. Test and Save the instance. -- Some Cortex XSOAR-Microsoft integrations support the deployment of national clouds through the self-deployed - authorization flow. For more information about Microsoft National Clouds, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/graph/deployments). - In order to use a national cloud, change the *Server URL* parameter to the corresponding address of the national cloud you are using. +**Note:** Make sure the necessary permissions and roles are applied to the application. -### Client Credentials Flow -Some Cortex XSOAR-Microsoft integrations use the [client credentials flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow). -The Tenant ID, Client ID, and Client secret are required for the integration. +### Certificate Thumbprint and Private Key +Alternatively, instead of providing the *Client Secret*, you can authenticate using certificate credentials by providing: + +- **Certificate Thumbprint** - The thumbprint of the certificate as it appears when registering the certificate to the application. +- **Private Key** - The private key of the registered certificate + +For more information, see [Microsoft Documentations](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-certificate-credentials). Follow the steps below for Mac/Linux operating systems: + 1. Run the following commands: + + ``` + openssl genrsa -out MyXSOARApp.key 2048 + openssl req -new -x509 -key MyXSOARApp.key -out MyXSOARApp.crt -days 365 -subj "/CN=MyXSOARApp" + openssl x509 -in MyXSOARApp.crt -noout -fingerprint -sha1 + ``` + +2. You receive results similar to the following: + + ``` + sha1 Fingerprint=E4:64:9A:AD:13:A4:F4:E0:74:11 + ``` + +3. Remove the colons, this is your certificate thumbprint. For example: + + ``` + E4649AAD13A4F4E07411 + ``` + +4. Next, run the following command: -To configure a Microsoft integration that uses this authorization flow with a self-deployed Azure application: + ``` + cat MyXSOARApp.key + ``` + + You receive results similar to the following: + + ``` + -----BEGIN PRIVATE KEY----- + ff12gg4kilo2gftvy54..... + -----END PRIVATE KEY----- + ``` + + This is your private key, include the headers. -1. Enter your client ID in the *ID* parameter field. -2. Enter your client secret in the *Key* parameter field. -3. Enter your tenant ID in the *Token* parameter field. -4. Select the ***Use a self-deployed Azure Application*** checkbox in the integration instance configuration. -5. Test and Save the instance. +5. Go to Azure Portal → App registrations → select your app → Certificates & secrets → Certificates. Click “Upload certificate”. -Alternatively, instead of providing the *Client Secret*, you can authenticate using [certificate credentials](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-certificate-credentials) by providing: - * Certificate Thumbprint - The certificate thumbprint as appears when registering the certificate to the App - * Private Key - The private key of the registered certificate +6. Select your public certificate file named **MyXSOARApp.crt** (do not select the .key file) and click "Add". + +7. Paste the private key and the certificate thumbprint into the instance configuration in XSOAR/XSIAM, then click "Test". -### Authorization Code flow -Some Cortex XSOAR-Microsoft integrations (e.g., Microsoft Graph Mail Single User) require authorization on behalf of a user (not admin consent). For more information about this authorization flow, refer to the [authorization code flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow). +## Authorization Code flow +Some Cortex XSOAR/XSIAM Microsoft integrations (e.g., Microsoft Graph Mail Single User) require authorization on behalf of a user (not admin consent). For more information about this flow, see the [authorization code flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow). +When configured using this flow, the integration operates under the user’s context, allowing actions based on the signed-in user’s permissions. This flow uses delegated permissions, which are defined in the Azure application configuration in the Azure Portal. +The user who authenticates must have the same roles and permissions as those granted to the application. These permissions determine which actions the user can perform through XSOAR/XSIAM commands according to their privileges within the organization or tenant. -To configure a Microsoft integration that uses this authorization flow with a self-deployed Azure application: +For this flow, the Tenant ID, Client ID, Client secret and Redirect URI are required for the integration. You can get those values from the Azure Portal under the application information. +Follow these steps: -1. Make sure the needed permissions are granted for the app registration, e.g., for Microsoft Graph User: API/Permission name `Directory.AccessAsUser.All` of type `Delegated`. -2. In your app. click **Authentication** > **Platform configurations** > **Add a platform.** Choose **Web** and add [Redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-a-redirect-uri). -The Redirect URI can direct any web application that you wish to receive responses from Azure AD. If you are not sure what to set, you can use `https://localhost`. -3. Enter your client ID in the *ID* parameter field. -4. Enter your client secret in the *Key* parameter field. -5. Enter your tenant ID in the *Token* parameter field. -6. Enter your redirect URI in the *Redirect URI* parameter field. -7. Select the ***Use a self-deployed Azure Application*** checkbox in the integration instance configuration. -8. Save the instance. -9. Run the `!-generate-login-url` command in the War Room and follow the instructions: - >1. Click on the [login URL]() to sign in and grant Cortex XSOAR permissions for your Azure Service Management. +1. In your app, click **Authentication** > **Platform configurations** > **Add a platform.** Choose **Web** and add a [Redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-a-redirect-uri). +The Redirect URI is the address where Azure AD sends the login response. If you are not sure what to set, you can use `https://localhost`. +2. Enter your redirect URI in the *Redirect URI* parameter field in the instance configuration in XSOAR/XSIAM. +3. Go to "Overview" section. Copy the "Application (client) ID" and paste it in the App/Client ID parameter field in the instance configuration in XSOAR/XSIAM. +4. Copy the "Directory (tenant) ID" and paste it in the Token/Tenant ID parameter field in the instance configuration in XSOAR/XSIAM. +5. In the application configuration go to "Certificates & secrets", click "New client secret", then "Add". Copy the secret **value** and paste it under the Client Secret parameter field in the XSOAR/XSIAM instance configuration. +6. Select the ***Use a self-deployed Azure Application*** checkbox in the integration instance configuration. +7. Save the instance. +8. Run the `!-generate-login-url` command in the War Room and follow these instructions: + >1. Click the [login URL]() to sign in and grant Cortex XSOAR permissions to access your Azure Service Management. You will be automatically redirected to a link with the following structure: ```REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE``` - >2. Copy the `AUTH_CODE` (without the `code=` prefix, and the `session_state` parameter) + >2. Copy the `AUTH_CODE` (between the `code=` prefix and the `session_state` prefix) and paste it in your instance configuration under the *Authorization code* parameter. >3. For any issues, see [Authorization Code flow Troubleshooting](#authorization-code-flow-troubleshooting). -10. Save the instance. -11. Run the `!-auth-test` command. A 'Success' message should be printed to the War Room. +9. Save the instance. +10. Run the `!-auth-test` command. The War Room prints a 'Success' message if the integration is configured correctly. + +**Note:** Make sure the neccessary permissions and roles are applied to the application and the user. + +### Example: configuring the [Microsoft Graph User integration](https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-user) using a self-deployed and authorization code flow -### Device Code Flow +1. In Microsoft Azure portal, create a new app registration: + + a. Select **App registrations** -> **New registration**. + + + + b. In the **Redirect URI (optional)** field select **Web** and type a name (you can enter an arbitrary name). In this example we use *https://xsoar.* + + + + c. Click **Register**. + + You can see the Essential information here: + + + + d. Copy the following information that apear under the "Overview" section, and save it for later: + - Application (client) ID + - Directory (tenant) ID + +2. Go to **API permissions** -> Add a permission -> Microsoft Graph -> Delegated permission. Search for `Directory.AccessAsUser.All`. +3. Click Add permissions. + + +4. Repeat step 3 for the following permissions: + - Directory.Read.All - Delegated + - User.ReadWrite.All - Application + - User.Read - Delegated +5. Next, create a new instance for the integration. +6. Enter your redirect URI in the *Redirect URI* parameter field in the instance configuration in XSOAR/XSIAM. +7. Paste the "Application (client) ID" under the App/Client ID parameter field in the instance configuration in XSOAR/XSIAM. +8. Paste "Directory (tenant) ID" under the Token/Tenant ID parameter field in the instance configuration in XSOAR/XSIAM. +9. In the application cofiguration go to "Certificates & secrets" and click on "New client secret", click on "Add" and copy the secret **value**. Paste it under the Client Secret parameter field in the instance configuration in XSOAR/XSIAM. +10. Click the **Use a self-deployed Azure application** checkbox. +11. Click on Save and Exit. +12. Get the authorization code by following the next steps: + + a. Run the msgraph-user-generate-login-url command in order to generate the url and follow the instructions. + b. Copy the `AUTH_CODE` (between the `code=` prefix and the `session_state` prefix). This value need to be used in instance configuration under the **Authorization Code** field. + +13. Under the **Authorization code (for Self Deployed - Authorization Code Flow)**, field in the instance configuration, paste the code from the previous step. +14. Save the instance and test the setup by running the *!msgraph-user-test* command from the Cortex XSOAR/XSIAM CLI. + + +## Device Code Flow Some Cortex XSOAR-Microsoft integrations use the [device code flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code). +When configured using this flow, the integration operates under the user’s context, similar to the Authorization Code Flow, but it is designed for devices or environments where a browser-based login is not available. This flow also uses delegated permissions, which must be defined in the Azure application configuration in the Azure Portal. +The user authenticating via the device code must have the same roles and permissions as those granted to the application. These permissions determine which actions the user can perform through XSOAR/XSIAM commands within the organization or tenant scope. -To configure a Microsoft integration that uses this authorization flow with a self-deployed Azure application: +During authentication, the user is provided with a code and a URL. They must enter the code at the URL using a browser on any device to complete the sign-in process. -1. Make sure the needed permissions are granted for the app registration. -2. The Redirect URI can direct any web application that you wish to receive responses from Azure AD. If you are not sure what to set, you can use `https://localhost`. -3. In **Supported account types**, *Accounts in any organizational directory (Any Azure AD directory - Multi-tenant)* should be selected. -4. In the app registration, navigate to **Authentication** > **Advanced Settings**, and enable the mobile and desktop flows. +For this flow, the Redirect URI is required for the integration. You can get those values from the Azure Portal under the application information. +Follow these steps: + +1. In your app, click **Authentication** > **Platform configurations** > **Add a platform.** Choose **Web** and add [Redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-a-redirect-uri). +The Redirect URI is the address where Azure AD sends the login response. If you are not sure what to set, you can use `https://localhost`. +2. In the app registration, navigate to **Authentication**. Under **Supported account types**, select *Accounts in any organizational directory (Any Azure AD directory - Multi-tenant)*. On the same page, under the **Advanced Settings** section, enable the mobile and desktop flows. -5. Enter your application ID in the ***Application ID*** parameter field. -6. Run the `!-auth-start` command - you will be prompted to open the page https://microsoft.com/devicelogin and enter the generated code. -7. Run the `!-auth-complete` command. -8. Run the `!-auth-test` command to ensure connectivity to Microsoft. +3. Next, click **Overview**, copy the "Application (client) ID" and paste it under the App/Client ID parameter field in the instance configuration in XSOAR/XSIAM. +4. Click "Save and Exit". +5. Run the `!-auth-start` command - you will be prompted to open the page https://microsoft.com/devicelogin and enter the generated code. +6. Run the `!-auth-complete` command. +7. Run the `!-auth-test` command to ensure connectivity to Microsoft. + +**Note:** Make sure the neccessary permissions and roles are applied to the application and the user. -## Azure Managed Identities Authentication -#### Note: This option is relevant only if the integration is running on Azure VM. +# Azure Managed Identities Authentication +#### Note: This option applies only when the integration runs on an Azure VM. -Some of the Cortex XSOAR-Microsoft integrations use the [Azure Managed Identities Authentication](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview). +Some Cortex XSOAR-Microsoft integrations use [Azure Managed Identities Authentication](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview). Follow one of these steps for authentication based on Azure Managed Identities: @@ -134,12 +273,12 @@ Follow one of these steps for authentication based on Azure Managed Identities: 2. Select your User Assigned Managed Identity -> copy the Client ID -> paste it in the **Azure Managed Identities Client ID** field in the instance settings. 3. Select **Azure Managed Identities** from the **Authentication Type** drop down or select the **Use Azure Managed Identities** checkbox. -## Revoke Consent +# Revoke Consent In order to revoke consent to a Cortex XSOAR Microsoft application, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant#revoking-consent). -## Azure Integrations Parameters -In order to use the Cortex XSOAR Azure application, you need to fill in your subscription ID and resource group name, which you can find in the Azure Portal. +# How to find Azure Integrations Parameters +To use the Cortex XSOAR/XSIAM Azure application, provide your Subscription ID and Resource Group Name, which can be found in the Azure Portal. 1. Log in to the [Azure Portal Home Page](https://portal.azure.com/#home) using your Azure credentials. @@ -156,71 +295,7 @@ After you a redirected to the next page, in the **Overview** tab you will find y ![Overview](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/subscription_id_resourse_group.png) -## Self Deployed Application - Example for [Microsoft Graph User integration](https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-user) - -1. In Microsoft Azure portal, create a new app registration. - 1. Select Azure Active Directory> App registrations> New registration. - - ![app](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/app-reg.png) - 2. In the **Redirect URI (optional)** field select **Web** and type a name (you can enter an arbitrary name). In this example we use *https://xsoar.* - - ![reg-app](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/reg-app.png) - 3. Click **Register**. - - You can see the Essential information here: - - ![essentials](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/essentials.png) - 4. Copy the following information: - - - Application (client) ID - - Directory (tenant) ID - -2. Get the client secret, which is used for the **key** in the integration settings. - 1. Click **Certificate and secrets** -> **New client secret**. - - Copy the client secret. -3. Ensure the needed permissions are granted for the app registration. - 1. Go to API permissions>Add a permission>Microsoft Graph>Delegated permissions and search for - `Directory.AccessAsUser.All` of type `Delegated`. - 2. Click Add permissions. - - ![app-api](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/app-api.png) - - NOTE: Ensure that you have the following permissions: - - Directory.Read.All - Delegated - - User.ReadWrite.All - Application - - User.Read - Delegated -4. Get the authorization code. - - 1. Type the following in a browser: `https://login.microsoftonline.com//oauth2/v2.0/authorize?response_type=code&scope=offline_access%20directory.accessasuser.all&client_id=**&redirect_uri=https%3A%2F%2Fxsoar` - - Replace `tenant_id` and `client-id` with the tenant ID that was generated in step 1.iv. - - The URI is the *https://xsoar*. - - This prompts the admin user to sign in and grant the app the appropriate permissions: - - ![app-perm](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/app-perm.png) - - Once completed you are redirected to the redirect URI and will receive an authorization code in the query parameters of the URI. - - **NOTE:** If there are multiple query parameters returned you should just copy the code value. - - ![app-connect](../../../docs/doc_imgs/tutorials/tut-microsoft-auth-guide/app-connect.png) - - 2. Copy the ***AUTH_CODE*** (without the "code=" prefix). This value must be used in the MS Graph User in Cortex XSOAR integration in the **Authorization Code** field. -5. Add the information to the instance in Cortex XSOAR by going to Settings>Integrations>Microsoft Graph User>Add Instance. - - 1. In the **ID** parameter field, type the client ID. - 2. in the **Token** parameter field, type the tenant ID. - 3. In the **Key** parameter field, type your client secret. - 4. Click the **Use a self-deployed Azure application** checkbox. - 5. In the **Redirect URI** field, type the redirect URI we are entering at the Azure portal. - 6. In the **Authorization code for self-deployed mode - received from the authorization step**, type the code that was generated in 4.2. - 7. Save the integration settings and test the setup by running the *!msgraph-user-test* command from the Cortex XSOAR CLI. - - -## Supported Authentication Flows for Microsoft integrations +# Supported Authentication Flows for Microsoft integrations | Integration Name | XSOAR Application | Client Credentials | Device Code | Auth code (redirect URI) | Azure Managed Identities | Supports National Clouds | |-------------------------------------------------------|-------------------|--------------------|-------------|--------------------------|--------------------------|--------------------------| @@ -263,8 +338,11 @@ After you a redirected to the next page, in the **Overview** tab you will find y | Microsoft Teams Management | yes | yes | yes | no | yes | no | +# Troubleshooting +1. If you encounter any issues while configuring your self-deployed application, please ensure that the 'self-deploy' checkbox is selected. +2. If you have added permissions to your self-deployed application but still encounter a permission error, make sure to run the `!-auth-reset` command. If you are using device code flow or authorization code flow, you must also reconnect and generate a new authorization code. After this, the new token used by the integration will include the updated permissions. +3. If you expect command results at the organization or tenant level but are receiving results at the user level, ensure that your permissions are set as application permissions and that you are using the client credentials flow. -## Troubleshooting #### Reset authentication In case of errors in the authentication process, such as a token revoked/expired or in case you generate new credentials, you can use the `!-auth-reset` command in the War Room in order to rerun the authentication process, @@ -283,3 +361,5 @@ For example, when using the "self-deployed Azure app" for Microsoft Graph Mail S If you encounter issues with the User consent, such as a "Missing scope permissions on the request. API requires one of..." error after generating a new authorization code using the generate-login-url command, even though you have provided all the mentioned permissions, it may indicate that you need to trigger the consent process again. To do this, copy the login URL, add `&prompt=consent` to the end of the URL, and then log in. For details, see Microsoft's documentation on [Request an authorization code](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-authorization-code). + + diff --git a/docs/doc_imgs/tutorials/tut-microsoft-auth-guide/delegated_vs_application_permissions.png b/docs/doc_imgs/tutorials/tut-microsoft-auth-guide/delegated_vs_application_permissions.png new file mode 100644 index 000000000..78785cebf Binary files /dev/null and b/docs/doc_imgs/tutorials/tut-microsoft-auth-guide/delegated_vs_application_permissions.png differ