+1. Open the `TrustFrameworksExtension.xml` and define a new **ContentDefinition** to customize the [self-asserted technical profile](./self-asserted-technical-profile.md).

+A **claims provider** is an interface to communicate with different types of parties via its [technical profiles](./technicalprofiles.md).

+- `deduce_insight_api` technical profile sends data to the Deduce RESTful service in an input claims collection and receives data back in an output claims collection. For more information, see [integrate REST API claims exchanges in your Azure AD B2C custom policy](./api-connectors-overview.md?pivots=b2c-custom-policy)

+- [Get started with custom policies in Azure AD B2C](./tutorial-create-user-flows.md?pivots=b2c-custom-policy&tabs=applications)

+ Title: Active Directory authentication non domain joined Linux Virtual Machines

+description: Active Directory authentication non domain joined Linux Virtual Machines.

+# Active Directory authentication non domain joined Linux Virtual Machines

+Currently Linux distribution can work as member of Active Directory domains, which gives them access to the AD authentication system. To take advantage of AD authentication in some cases, we can avoid the AD join. To let users sign in on Azure Linux VM with Active Directory account you have different choices. One possibility is to Join in Active Directory the VM. Another possibility is to base the authentication flow through LDAP to your Active Directory without Join the VM on AD. This article shows you how to authenticate with AD credential on your Linux system (CentosOS) based on LDAP.

+## Prerequisites

+To complete the authentication flow we assume, you already have:

+* An Active Directory Domain Services already configured.

+* A Linux VM (for the test we use CentosOS based machine).

+* A network infrastructure that allows communication between Active Directory and the Linux VM.

+* A dedicated User Account for read AD objects.

+* The Linux VM need to have these packages installed:

+ - sssd

+ - sssd-tools

+ - sssd-ldap

+ - openldap-clients

+* An LDAPS Certificate correctly configured on the Linux VM.

+* A CA Certificate correctly imported into Certificate Store of the Linux VM (the path varies depending on the Linux distro).

+## Active Directory User Configuration

+To read Users in your Active Directory Domain Services create a ReadOnlyUser in AD. For create a new user follow the steps below:

+1. Connect to your *Domain Controller*.

+2. Click *Start*, point to *Administrative Tools*, and then click *Active Directory Users and Computers* to start the Active Directory Users and Computers console.

+3. Click the domain name that you created, and then expand the contents.

+4. Right-click Users, point to *New*, and then click *User*.

+5. Type the first name, last name, and user logon name of the new user, and then click Next. In lab environment we used a user called *ReadOnlyUser*.

+6. Type a *new password*, confirm the password, and then click to select one of the following check boxes if needed:

+ - Users must change password at next logon (recommended for most user)

+ - User cannot change password

+ - Password never expires

+ - Account is disabled (If you disable the account the authentication will fail)

+7. Click *Next*.

+Review the information that you provided, and if everything is correct, click Finish.

+> [!NOTE]

+> The lab environment is based on:

+> - Windows Server 2016 Domain and Forest Functional Level.

+> - Linux client Centos 8.5.

+## Linux Virtual Machines Configuration

+> [!NOTE]

+> You must run these command with sudo permission

+On your Linux VM, install the following packages: *sssd sssd-tools sssd-ldap openldap-client*:

+```console

+yum install -y sssd sssd-tools sssd-ldap openldap-clients

+```

+After the installation check if LDAP search works. In order to check it try an LDAP search following the example below:

+```console

+ldapsearch -H ldaps://contoso.com -x \

+ -D CN=ReadOnlyUser,CN=Users,DC=contoso,DC=com -w Read0nlyuserpassword \

+ -b CN=Users,DC=contoso,DC=com

+```

+If the LDAP query works fine, you will obtain an output with some information like follow:

+```console

+extended LDIF

+LDAPv3

+base <CN=Users,DC=contoso,DC=com> with scope subtree

+filter: (objectclass=*)

+requesting: ALL

+Users, contoso.com

+dn: CN=Users,DC=contoso,DC=com

+objectClass: top

+objectClass: container

+cn: Users

+description: Default container for upgraded user accounts

+distinguishedName: CN=Users,DC=contoso,DC=com

+instanceType: 4

+whenCreated: 20220913115340.0Z

+whenChanged: 20220913115340.0Z

+uSNCreated: 5660

+uSNChanged: 5660

+showInAdvancedViewOnly: FALSE

+name: Users

+objectGUID:: i9MABLytKUurB2uTe/dOzg==

+systemFlags: -1946157056

+objectCategory: CN=Container,CN=Schema,CN=Configuration,DC=contoso,DC=com

+isCriticalSystemObject: TRUE

+dSCorePropagationData: 20220930113600.0Z

+dSCorePropagationData: 20220930113600.0Z

+dSCorePropagationData: 20220930113600.0Z

+dSCorePropagationData: 20220930113600.0Z

+dSCorePropagationData: 16010101000000.0Z

+```

+> [!NOTE]

+> If your get and error run the following command:

+>

+> ldapsearch -H ldaps://contoso.com -x \

+> -D CN=ReadOnlyUser,CN=Users,DC=contoso,DC=com -w Read0nlyuserpassword \

+> -b CN=Users,DC=contoso,DC=com -d 3

+>

+> Troubleshoot according to the output.

+## Create sssd.conf file

+Create */etc/sssd/sssd.conf* with a content like the following. Remember to update the *ldap_uri*, *ldap_search_base* and *ldap_default_bind_dn*.

+Command for file creation:

+```console

+vi /etc/sssd/sssd.conf

+```

+Example sssd.conf:

+```bash

+[sssd]

+config_file_version = 2

+domains = default

+services = nss, pam

+full_name_format = %1$s

+[nss]

+[pam]

+[domain/default]

+id_provider = ldap

+cache_credentials = True

+ldap_uri = ldaps://contoso.com

+ldap_search_base = CN=Users,DC=contoso,DC=com

+ldap_schema = AD

+ldap_default_bind_dn = CN=ReadOnlyUser,CN=Users,DC=contoso,DC=com

+ldap_default_authtok_type = obfuscated_password

+ldap_default_authtok = generated_password

+# Obtain the CA root certificate for your LDAPS connection.

+ldap_tls_cacert = /etc/pki/tls/cacerts.pem

+# This setting disables cert verification.

+#ldap_tls_reqcert = allow

+# Only if the LDAP directory doesn't provide uidNumber and gidNumber attributes

+ldap_id_mapping = True

+# Consider setting enumerate=False for very large directories

+enumerate = True

+# Only needed if LDAP doesn't provide homeDirectory and loginShell attributes

+fallback_homedir = /home/%u

+default_shell = /bin/bash

+access_provider = permit

+sudo_provider = ldap

+auth_provider = ldap

+autofs_provider = ldap

+resolver_provider = ldap

+```

+Save the file with *ESC + wq!* command.

+> [!NOTE]

+> If you don't have a valid TLS certificate under */etc/pki/tls/* called *cacerts.pem* the bind doesn't work

+## Change permission for sssd.conf and create the obfuscated password

+Set the permission to sssd.conf to 600 with the following command:

+```console

+chmod 600 /etc/sssd/sssd.conf

+```

+After that create an obfuscated password for the Bind DN account. You must insert the Domain password for ReadOnlyUser:

+```console

+sss_obfuscate --domain default

+```

+The password will be placed automatically in the configuration file.

+## Configure the sssd service

+Start the sssd service:

+```console

+service sssd start

+```

+Now configure the service with the *authconfig* tool:

+```console

+authconfig --enablesssd --enablesssdauth --enablemkhomedir --updateall

+```

+At this point restart the service:

+```console

+systemctl restart sssd

+```

+## Test the configuration

+The final step is to check that the flow works properly. To check this, try logging in with one of your AD users in Active Directory. We tried with a user called *ADUser*. If the configuration is correct, you will get the following result:

+```console

+[centosuser@centos8 ~]su - ADUser@contoso.com

+Last login: Wed Oct 12 15:13:39 UTC 2022 on pts/0

+[ADUser@Centos8 ~]$ exit

+```

+Now you are ready to use AD authentication on your Linux VM.

+<!-- INTERNAL LINKS -->

+[create-azure-ad-tenant]: ../active-directory/fundamentals/sign-up-organization.md

+[associate-azure-ad-tenant]: ../active-directory/fundamentals/active-directory-how-subscriptions-associated-directory.md

+[create-azure-ad-ds-instance]: tutorial-create-instance.md

+You can configure metric alerts for Azure AD DS to be notified of possible problems. Metric alerts are one type of alert for Azure Monitor. For more information about other types of alerts, see [What are Azure Monitor Alerts?](../azure-monitor/alerts/alerts-overview.md).

+To view and manage Azure Monitor alert, a user needs to be assigned [Azure Monitor roles](../azure-monitor/roles-permissions-security.md).

+- [Check the health of an Azure Active Directory Domain Services managed domain](check-health.md)

+1. To deploy the Microsoft.SCIM.WebHostSample app to Azure App Services, [create a new App Services](../../app-service/tutorial-dotnetcore-sqldb-app.md#2create-the-app-service).

+- **Authentication loop** - when the user is required to use Microsoft Authenticator (Phone Sign-in) but the user is not registered for this method, they will be given instructions on how to set up the Microsoft Authenticator, that does not include how to enable Passwordless sign-in. As a result, the user can get into an authentication loop. To avoid this issue, make sure the user is registered for the method before the Conditional Access policy is enforced. Phone Sign-in can be registered using the steps outlined here: [Add your work or school account to the Microsoft Authenticator app](https://support.microsoft.com/en-us/account-billing/add-your-work-or-school-account-to-the-microsoft-authenticator-app-43a73ab5-b4e8-446d-9e54-2a4cb8e4e93c)

+| Secure |- On-premises passwords don't need to be stored in the cloud in any form.<br>- Protects your user accounts by working seamlessly with Azure AD Conditional Access policies, including Phishing-Resistant [multifactor authentication](concept-mfa-howitworks.md) (MFA requires [licensed edition](concept-mfa-licensing.md)) and blocking legacy authentication.<br>- Strong authentication support where users can define authentication policies through the certificate fields, such as issuer or policy OID (object identifiers), to determine which certificates qualify as single-factor versus multifactor.<br>- The feature works seamlessly with [Conditional Access features](../conditional-access/overview.md) and authentication strength capability to enforce MFA to help secure your users. |

+For LDAP deployments that canΓÇÖt be upgraded or moved to RADIUS, [determine if Azure Active Directory Domain Services can be used](../fundamentals/auth-ldap.md). In most cases, LDAP was deployed to support in-line password changes for end users. Once migrated, end users can manage their passwords by using [self-service password reset in Azure AD](tutorial-enable-sspr.md).

+If you enabled the [MFA Server Authentication provider in AD FS 2.0](./howto-mfaserver-adfs-windows-server.md#secure-windows-server-ad-fs-with-azure-multi-factor-authentication-server) on any relying party trusts except for the Office 365 relying party trust, youΓÇÖll need to upgrade to [AD FS 3.0](/windows-server/identity/ad-fs/deployment/upgrading-to-ad-fs-in-windows-server) or federate those relying parties directly to Azure AD if they support modern authentication methods. Determine the best plan of action for each of the dependencies.

+# Enable mobile app authentication with Azure AD Multi-Factor Authentication Server

+The Microsoft Authenticator app offers an extra out-of-band verification option. Instead of placing an automated phone call or SMS to the user during login, Azure AD Multi-Factor Authentication pushes a notification to the Authenticator app on the user's smartphone or tablet. The user simply taps **Verify** (or enters a PIN and taps "Authenticate") in the app to complete their sign-in.

+> In September 2022, Microsoft announced deprecation of Azure AD Multi-Factor Authentication Server. Beginning September 30, 2024, Azure AD Multi-Factor Authentication Server deployments will no longer service multifactor authentication (MFA) requests, which could cause authentications to fail for your organization. To ensure uninterrupted authentication services and to remain in a supported state, organizations should [migrate their usersΓÇÖ authentication data](how-to-migrate-mfa-server-to-azure-mfa-user-authentication.md) to the cloud-based Azure MFA service by using the latest Migration Utility included in the most recent [Azure MFA Server update](https://www.microsoft.com/download/details.aspx?id=55849). For more information, see [Azure MFA Server Migration](how-to-migrate-mfa-server-to-azure-mfa.md).

+> If you have installed Azure AD Multi-Factor Authentication Server v8.x or higher, most of the steps below are not required. Mobile app authentication can be set up by following the steps under [Configure the mobile app](#configure-the-mobile-app-settings-in-mfa-server).

+To use the Authenticator app, you must be running Azure AD Multi-Factor Authentication Server v8.x or higher

+- [Advanced scenarios with Azure AD Multi-Factor Authentication Server and third-party VPNs](howto-mfaserver-nps-vpn.md).

+ Title: Upgrade PhoneFactor to Azure AD Multi-Factor Authentication Server - Azure Active Directory

+description: Get started with Azure AD Multi-Factor Authentication Server when you upgrade from the older phonefactor agent.

+# Upgrade the PhoneFactor Agent to Azure AD Multi-Factor Authentication Server

+To upgrade the PhoneFactor Agent v5.x or older to Azure AD Multi-Factor Authentication Server, uninstall the PhoneFactor Agent and affiliated components first. Then the Multi-Factor Authentication Server and its affiliated components can be installed.

+> In September 2022, Microsoft announced deprecation of Azure AD Multi-Factor Authentication Server. Beginning September 30, 2024, Azure AD Multi-Factor Authentication Server deployments will no longer service multifactor authentication (MFA) requests, which could cause authentications to fail for your organization. To ensure uninterrupted authentication services and to remain in a supported state, organizations should [migrate their usersΓÇÖ authentication data](how-to-migrate-mfa-server-to-azure-mfa-user-authentication.md) to the cloud-based Azure MFA service by using the latest Migration Utility included in the most recent [Azure MFA Server update](https://www.microsoft.com/download/details.aspx?id=55849). For more information, see [Azure MFA Server Migration](how-to-migrate-mfa-server-to-azure-mfa.md).

+2. If the User portal is installed:

+ 3. Uninstall the User portal either through the PhoneFactor Agent (only available if installed on the same server as the PhoneFactor Agent) or through Windows Programs and Features.

+ The default virtual directory name is now **MultiFactorAuthWebServiceSdk** instead of **PhoneFactorWebServiceSdk**. If you want to use the previous name, you must change the name of the virtual directory during installation. Otherwise, if you allow the install to use the new default name, you have to change the URL in any applications that reference the Web Service SDK (like the User portal and Mobile App Web Service) to point at the correct location.

+3. If the User portal was previously installed on the PhoneFactor Agent Server, install the new Multi-Factor Authentication User portal through the Multi-Factor Authentication Server User Interface.

+ The default virtual directory name is now **MultiFactorAuth** instead of **PhoneFactor**. If you want to use the previous name, you must change the name of the virtual directory during installation. Otherwise, if you allow the install to use the new default name, you should click the User portal icon in the Multi-Factor Authentication Server and update the User portal URL on the Settings tab.

+4. If the User portal and/or Mobile App Web Service was previously installed on a different server from the PhoneFactor Agent:

+ 1. Go to the install location (for example, C:\Program Files\PhoneFactor) and copy one or more installers to the other server. There are 32-bit and 64-bit installers for both the User portal and Mobile App Web Service. They're called MultiFactorAuthenticationUserPortalSetupXX.msi and MultiFactorAuthenticationMobileAppWebServiceSetupXX.msi.

+ 2. To install the User portal on the web server, open a command prompt as an administrator and run MultiFactorAuthenticationUserPortalSetupXX.msi.

+ The default virtual directory name is now **MultiFactorAuth** instead of **PhoneFactor**. If you want to use the previous name, you must change the name of the virtual directory during installation. Otherwise, if you allow the install to use the new default name, you should click the User portal icon in the Multi-Factor Authentication Server and update the User portal URL on the Settings tab. Existing users need to be informed of the new URL.

+ 3. Go to the User portal install location (for example, C:\inetpub\wwwroot\MultiFactorAuth) and edit the web.config file. Copy the values in the appSettings and applicationSettings sections from your original web.config file that was backed up before the upgrade into the new web.config file. If the new default virtual directory name was kept when installing the Web Service SDK, change the URL in the applicationSettings section to point to the correct location. If any other defaults were changed in the previous web.config file, apply those same changes to the new web.config file.

+- [Install the users portal](howto-mfaserver-deploy-userportal.md) for the Azure AD Multi-Factor Authentication Server.

+# User portal for the Azure AD Multi-Factor Authentication Server

+The user portal is an IIS web site that allows users to enroll in Azure AD Multi-Factor Authentication (MFA) and maintain their accounts. A user may change their phone number, change their PIN, or choose to bypass two-step verification during their next sign-on.

+Depending on your environment, you may want to deploy the user portal on the same server as Azure AD Multi-Factor Authentication Server or on another internet-facing server.

+> In September 2022, Microsoft announced deprecation of Azure AD Multi-Factor Authentication Server. Beginning September 30, 2024, Azure AD Multi-Factor Authentication Server deployments will no longer service multifactor authentication (MFA) requests, which could cause authentications to fail for your organization. To ensure uninterrupted authentication services and to remain in a supported state, organizations should [migrate their usersΓÇÖ authentication data](how-to-migrate-mfa-server-to-azure-mfa-user-authentication.md) to the cloud-based Azure MFA service by using the latest Migration Utility included in the most recent [Azure MFA Server update](https://www.microsoft.com/download/details.aspx?id=55849). For more information, see [Azure MFA Server Migration](how-to-migrate-mfa-server-to-azure-mfa.md).

+

+In either scenario, if the Azure AD Multi-Factor Authentication Web Service SDK is **not** already installed on the Azure AD Multi-Factor Authentication (MFA) Server, complete the steps that follow.

+## Deploy the user portal on the same server as the Azure AD Multi-Factor Authentication Server

+The following pre-requisites are required to install the user portal on the **same server** as the Azure AD Multi-Factor Authentication Server:

+* Secure the Azure AD Multi-Factor Authentication Web Service SDK with a TLS/SSL certificate.

+1. Open the Azure AD Multi-Factor Authentication Server console, click the **User Portal** icon in the left menu, then click **Install User Portal**.

+If the server where Azure AD Multi-Factor Authentication Server is running isn't internet-facing, you should install the user portal on a **separate, internet-facing server**.

+* Use v6.0 or higher of the Azure AD Multi-Factor Authentication Server.

+* Secure the Azure AD Multi-Factor Authentication Web Service SDK with a TLS/SSL certificate.

+* Ensure that the user portal can connect to the Azure AD Multi-Factor Authentication Web Service SDK over TLS/SSL.

+* Ensure that the user portal can authenticate to the Azure AD Multi-Factor Authentication Web Service SDK using the credentials of a service account in the "PhoneFactor Admins" security group. This service account and group should exist in Active Directory if the Azure AD Multi-Factor Authentication Server is running on a domain-joined server. This service account and group exist locally on the Azure AD Multi-Factor Authentication Server if it isn't joined to a domain.

+Installing the user portal on a server other than the Azure AD Multi-Factor Authentication Server requires the following steps:

+1. **On the MFA Server**, browse to the installation path (Example: C:\Program Files\Multi-Factor Authentication Server), and copy the file **MultiFactorAuthenticationUserPortalSetup64** to a location accessible to the internet-facing server where you'll install it.

+## Configure user portal settings in the Azure AD Multi-Factor Authentication Server

+Now that the user portal is installed, you need to configure the Azure AD Multi-Factor Authentication Server to work with the portal.

+1. In the Azure AD Multi-Factor Authentication Server console, click the **User Portal** icon. On the Settings tab, enter the URL to the user portal in the **User Portal URL** textbox. If email functionality has been enabled, this URL is included in the emails that are sent to users when they're imported into the Azure AD Multi-Factor Authentication Server.

+Azure AD Multi-Factor Authentication server provides several options for the user portal. The following table provides a list of these options and an explanation of what they're used for.

+| Allow users to log in | Allow users to enter a username and password on the sign-in page for the User portal. If this option isn't selected, the boxes are grayed out. |

+| Allow users to initiate One-Time Bypass | Allow users to initiate a one-time bypass. If a user sets up this option, it will take effect the next time the user signs in. Prompt for bypass seconds provides the user with a box so they can change the default of 300 seconds. Otherwise, the one-time bypass is only good for 300 seconds. |

+| Use OATH token for fallback | Allow for the use of an OATH token in case two-step verification isn't successful. You can also specify the session timeout in minutes. |

+The user can see these settings after they sign in to the user portal.

+For example, when a user signs in to the user portal for the first time, they're then taken to the Azure AD Multi-Factor Authentication User Setup page. Depending on how you have configured Azure AD Multi-Factor Authentication, the user may be able to select their authentication method.

+If the user is required to use a PIN when they authenticate, the page prompts them to create a PIN. After entering their phone number(s) and PIN (if applicable), the user clicks the **Call Me Now to Authenticate** button. Azure AD Multi-Factor Authentication performs a phone call verification to the user's primary phone number. The user must answer the phone call and enter their PIN (if applicable) and press # to move on to the next step of the self-enrollment process.

+If the user selects the Text Message verification method or has been pre-configured to use that method, the page prompts the user for their mobile phone number. If the user is required to use a PIN when they authenticate, the page also prompts them to enter a PIN. After entering their phone number and PIN (if applicable), the user clicks the **Text Me Now to Authenticate** button. Azure AD Multi-Factor Authentication performs an SMS verification to the user's mobile phone. The user receives the text message with a one-time-passcode (OTP), then replies to the message with that OTP plus their PIN (if applicable).

+After the activation is complete, the user clicks the **Authenticate Me Now** button. Azure AD Multi-Factor Authentication performs a verification to the user's mobile app. The user must enter their PIN (if applicable) and press the Authenticate button in their mobile app to move on to the next step of the self-enrollment process.

+If the administrators have configured the Azure AD Multi-Factor Authentication Server to collect security questions and answers, the user is then taken to the Security Questions page. The user must select four security questions and provide answers to their selected questions.

+- [Deploy the Azure AD Multi-Factor Authentication Server Mobile App Web Service](howto-mfaserver-deploy-mobileapp.md)

+In the following steps, you'll implement a common policy scenario that imposes new rules for token lifetime. It's possible to specify the lifetime of an access, SAML, or ID token issued by the Microsoft identity platform. This can be set for all apps in your organization or for a specific service principal. They can also be set for multi-organizations (multi-tenant application).

+For more information, see [configurable token lifetimes](active-directory-configurable-token-lifetimes.md).

+Next, run the `Connect-AzureAD` command to sign in to your Azure Active Directory (Azure AD) admin account. Run this command each time you start a new session.

+In the following steps, you'll create a policy that requires users to authenticate more frequently in your web app. This policy sets the lifetime of the access/ID tokens to the service principal of your web app.

+To see which apps and service principals are linked to a specific policy that you identified, run the following [`Get-AzureADPolicyAppliedObject`](/powershell/module/azuread/get-azureadpolicyappliedobject?view=azureadps-2.0-preview&preserve-view=true) cmdlet by replacing `1a37dad8-5da7-4cc8-87c7-efbc0326cf20` with any of your policy IDs. Then you can decide whether to configure Conditional Access sign-in frequency or remain with the Azure AD defaults.

+Some users have reported a `Get-AzureADPolicy : The term 'Get-AzureADPolicy' is not recognized` error after running the `Get-AzureADPolicy` cmdlet. As a workaround, run the following to uninstall/re-install the AzureAD module, and then install the AzureADPreview module:

+Azure Active Directory (Azure AD) supports two types of authentication for service principals: **password-based authentication** (app secret) and **certificate-based authentication**. While app secrets can easily be created in the Azure portal, they're long-lived, and not as secure as certificates. It's therefore recommended that your application uses a certificate rather than a secret.

+For testing, you can use a self-signed public certificate instead of a Certificate Authority (CA)-signed certificate. In this how-to, you'll use Windows PowerShell to create and export a self-signed certificate.

+While creating the certificate using PowerShell, you can specify parameters like cryptographic and hash algorithms, certificate validity period, and domain name. The certificate can then be exported with or without its private key depending on your application needs.

+The application that initiates the authentication session requires the private key while the application that confirms the authentication requires the public key. So, if you're authenticating from your PowerShell desktop app to Azure AD, you only export the public key (*.cer* file) and upload it to the Azure portal. The PowerShell app uses the private key from your local certificate store to initiate authentication and obtain access tokens for Microsoft Graph.

+Your application may also be running from another machine, such as Azure Automation. In this scenario, you export the public and private key pair from your local certificate store, upload the public key to the Azure portal, and the private key (a *.pfx* file) to Azure Automation. Your application running in Azure Automation will use the private key to initiate authentication and obtain access tokens for Microsoft Graph.

+To customize the start and expiry date and other properties of the certificate, refer to [New-SelfSignedCertificate](/powershell/module/pki/new-selfsignedcertificate?view=windowsserver2019-ps&preserve-view=true).

+## Create and export your public certificate

+The `$cert` variable in the previous command stores your certificate in the current session and allows you to export it. The command below exports the certificate in *.cer* format. You can also export it in other formats supported on the Azure portal including *.pem* and *.crt*.

+## (Optional): Export your public certificate with its private key

+If your application will be running from another machine or cloud, such as Azure Automation, you'll also need a private key.

+Following on from the previous commands, create a password for your certificate private key and save it in a variable. Replace `{myPassword}` with the password that you wish to use to protect your certificate private key.

+Using the password you stored in the `$mypwd` variable, secure and export your private key using the command;

+Your certificate (*.cer* file) is now ready to upload to the Azure portal. The private key (*.pfx* file) is encrypted and can't be read by other parties. Once uploaded, retrieve the certificate thumbprint, which you can use to authenticate your application.

+You can delete the key pair from your personal store by running the following command to retrieve the certificate thumbprint.

+The Microsoft identity platform helps you build applications your users and customers can sign in to using their Microsoft identities or social accounts. It authorizes access to your own APIs or Microsoft APIs like Microsoft Graph.

+ - Personal Microsoft accounts (Skype, Xbox, Outlook.com)

+- **Open-source libraries**: Microsoft Authentication Library (MSAL) and support for other standards-compliant libraries.

+> [!VIDEO https://www.youtube.com/embed/uDU1QTSw7Ps]

+For developers, the Microsoft identity platform offers integration of modern innovations in the identity and security space like passwordless authentication, step-up authentication, and Conditional Access. You don't need to implement such functionality yourself. Applications integrated with the Microsoft identity platform natively take advantage of such innovations.

+With the Microsoft identity platform, you can write code once and reach any user. You can build an app once and have it work across many platforms, or build an app that functions as both a client and a resource application (API).

+Choose your preferred [application scenario](authentication-flows-app-scenarios.md). Each of these scenario paths has an overview and links to a quickstart to help you get started:

+[Azure Active Directory for developers (v1.0)](../azuread-dev/v1-overview.md) - Exclusively for developers with existing apps that use the older v1.0 endpoint. **Do not** use v1.0 for new projects.

+If you have an Azure account, then you have access to an Azure Active Directory tenant. However, most Microsoft identity platform developers need their own Azure AD tenant for use while developing applications, known as a *dev tenant*.

+> [!div class="nextstepaction"]

+> [Quickstart: Set up an Azure AD tenant](quickstart-create-new-tenant.md)

+It is possible to use a deny [Azure Policy](../../governance/policy/overview.md) as in the following ARM template example:

+| 409 | Conflict | Concurrent write request to federated identity credential resources under the same user-assigned identity has been denied.

+- If you're unfamiliar with managed identities for Azure resources, check out the [overview section](../managed-identities-azure-resources/overview.md). Be sure to review the [difference between a system-assigned and user-assigned managed identity](../managed-identities-azure-resources/overview.md#managed-identity-types).

+- To create a user-assigned managed identity and configure a federated identity credential, your account needs the [Managed Identity Contributor](../../role-based-access-control/built-in-roles.md#managed-identity-contributor) role assignment.

+- [Create a user-assigned manged identity](../managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md?pivots=identity-mi-methods-azp#create-a-user-assigned-managed-identity)

+- If you're unfamiliar with managed identities for Azure resources, check out the [overview section](../managed-identities-azure-resources/overview.md). Be sure to review the [difference between a system-assigned and user-assigned managed identity](../managed-identities-azure-resources/overview.md#managed-identity-types).

+- To create a user-assigned managed identity and configure a federated identity credential, your account needs the [Managed Identity Contributor](../../role-based-access-control/built-in-roles.md#managed-identity-contributor) role assignment.

+- [Create a user-assigned manged identity](../managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md?pivots=identity-mi-methods-azcli#create-a-user-assigned-managed-identity-1)

+- If you're unfamiliar with managed identities for Azure resources, check out the [overview section](../managed-identities-azure-resources/overview.md). Be sure to review the [difference between a system-assigned and user-assigned managed identity](../managed-identities-azure-resources/overview.md#managed-identity-types).

+- To create a user-assigned managed identity and configure a federated identity credential, your account needs the [Managed Identity Contributor](../../role-based-access-control/built-in-roles.md#managed-identity-contributor) role assignment.

+- [Create a user-assigned manged identity](../managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md?pivots=identity-mi-methods-arm#create-a-user-assigned-managed-identity-3)

+Federated identity credential and parent user assigned identity can be created or updated be means of template below. You can [deploy ARM templates](../../azure-resource-manager/templates/quickstart-create-templates-use-the-portal.md) from the [Azure portal](https://portal.azure.com).

+- If you're unfamiliar with managed identities for Azure resources, check out the [overview section](../managed-identities-azure-resources/overview.md). Be sure to review the [difference between a system-assigned and user-assigned managed identity](../managed-identities-azure-resources/overview.md#managed-identity-types).

+- To create a user-assigned managed identity and configure a federated identity credential, your account needs the [Managed Identity Contributor](../../role-based-access-control/built-in-roles.md#managed-identity-contributor) role assignment.

+- [Create a user-assigned manged identity](../managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md?pivots=identity-mi-methods-rest#create-a-user-assigned-managed-identity-4)

+- For information about the required format of JWTs created by external identity providers, read about the [assertion format](active-directory-certificate-credentials.md#assertion-format).

+- Workloads running on Kubernetes. Establish a trust relationship between your app or user-assigned managed identity in Azure AD and a Kubernetes workload (described in the [workload identity overview](../../aks/workload-identity-overview.md)).

+- For information about the required format of JWTs created by external identity providers, read about the [assertion format](active-directory-certificate-credentials.md#assertion-format).

+> For the [Azure AD Government](../../azure-government/index.yml), the sender address is invites@azuread.us.

+- [Add B2B collaboration users without an invitation](add-user-without-invite.md)

+You can create custom attributes in the Azure portal and use them in your [self-service sign-up user flows](self-service-sign-up-user-flow.md). You can also read and write these attributes by using the [Microsoft Graph API](../../active-directory-b2c/microsoft-graph-operations.md). Microsoft Graph API supports creating and updating a user with extension attributes. Extension attributes in the Graph API are named by using the convention `extension_<extensions-app-id>_attributename`. For example:

+The `<extensions-app-id>` is specific to your tenant. To find this identifier, navigate to **Azure Active Directory** > **App registrations** > **All applications**. Search for the app that starts with "aad-extensions-app" and select it. On the app's Overview page, note the Application (client) ID.

+ :::image type="content" source="media/user-flow-add-custom-attributes/user-attributes.png" alt-text="Screenshot of selecting custom user attributes for sign-up." lightbox="media/user-flow-add-custom-attributes/user-attributes-large-image.png":::

+ - **Name** - Provide a name for the custom attribute (for example, "Shoe size").

+ - **Description** - Optionally, enter a description of the custom attribute for internal use. This description isn't visible to the user.

+ :::image type="content" source="media/user-flow-add-custom-attributes/add-an-attribute.png" alt-text="Screenshot of adding a custom attribute.":::

+The custom attribute is now available in the list of user attributes and for use in your user flows. A custom attribute is only created the first time it's used in any user flow, and not when you add it to the list of user attributes.

+Once you've created a new user using a user flow that uses the newly created custom attribute, the object can be queried in [Microsoft Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). You should now see **ShoeSize** in the list of attributes collected during the sign-up journey on the user object. You can call the Graph API from your application to get the data from this attribute after it's added to the user object.

+[Add a self-service sign-up user flow to an app](self-service-sign-up-user-flow.md)

+ Title: Manage Azure AD user roles - Azure Active Directory | Microsoft Docs

+description: Instructions about how to assign and update user roles with Azure Active Directory.

+# Assign user roles with Azure Active Directory

+The ability to manage Azure resources is granted by assigning roles that provide the required permissions. Roles can be assigned to individual users or groups. To align with the [Zero Trust guiding principles](/azure/security/fundamentals/zero-trust), use Just-In-Time and Just-Enough-Access policies when assigning roles.

+Before assigning roles to users, review the following Microsoft Learn articles:

+- [Learn about Azure AD roles](../roles/concept-understand-roles.md)

+- [Learn about role based access control](../../role-based-access-control/rbac-and-directory-admin-roles.md)

+- [Explore the Azure built-in roles](../roles/permissions-reference.md)

+There are two main steps to the role assignment process. First you'll select the role to assign. Then you'll adjust the role settings and duration.

+### Select the role to assign

+1. Sign in to the [Azure portal](https://portal.azure.com/) using the Privileged Role Administrator role for the directory.

+1. Go to **Azure Active Directory** > **Users**.

+1. Search for and select the user getting the role assignment.

+ 

+1. Select **Assigned roles** from the side menu, then select **Add assignments**.

+ 

+1. Select a role to assign from the dropdown list and select the **Next** button.

+### Adjust the role settings

+You can assign roles as either _eligible_ or _active_. Eligible roles are assigned to a user but must be elevated Just-In-Time by the user through Privileged Identity Management (PIM). For more information about how to use PIM, see [Privileged Identity Management](../privileged-identity-management/index.yml).

+

+1. From the Setting section of the **Add assignments** page, select an **Assignment type** option.

+1. Leave the **Permanently eligible** option selected if the role should always be available to elevate for the user.

+ If you uncheck this option, you can specify a date range for the role eligibility.

+1. Select the **Assign** button.

+ Assigned roles appear in the associated section for the user, so eligible and active roles are listed separately.

+ 

+## Update roles

+You can change the settings of a role assignment, for example to change an active role to eligible.

+1. Go to **Azure Active Directory** > **Users**.

+1. Search for and select the user getting their role updated.

+1. Go to the **Assigned roles** page and select the **Update** link for the role that needs to be changed.

+1. Change the settings as needed and select the **Save** button.

+ 

+## Remove roles

+You can remove role assignments from the **Administrative roles** page for a selected user.

+1. Go to **Azure Active Directory** > **Users**.

+1. Search for and select the user getting the role assignment removed.

+1. Go to the **Assigned roles** page and select the **Remove** link for the role that needs to be removed. Confirm the change in the pop-up message.

+- [Explore other user management tasks](../enterprise-users/index.yml)

+description: Instructions about how to manage a user's profile and settings in Azure Active Directory.

+# Add or update a user's profile information and settings

+A user's profile information and settings can be managed on an individual basis and for all users in your directory. When you look at these settings together, you can see how permissions, restrictions, and other connections work together.

+This article covers how to add user profile information, such as a profile picture and job-specific information. You can also choose to allow users to connect their LinkedIn accounts or restrict access to the Azure AD administration portal. Some settings may be managed in more than one area of Azure AD. For more information about adding new users, see [How to add or delete users in Azure Active Directory](add-users-azure-active-directory.md).

+## Add or change profile information

+When new users are created, only some details are added to their user profile. If your organization needs more details, they can be added after the user is created.

+1. Go to **Azure Active Directory** > **Users** and select a user.

+

+1. There are two ways to edit user profile details. Either select **Edit properties** from the top of the page or select **Properties**.

+ 

+1. After making any changes, select the **Save** button.

+If you selected the **Edit properties option**:

+ - The full list of properties appears in edit mode on the **All** category.

+ - To edit properties based on the category, select a category from the top of the page.

+ - Select the **Save** button at the bottom of the page to save any changes.

+

+ 

+

+If you selected the **Properties tab option**:

+ - The full list of properties appears for you to review.

+ - To edit a property, select the pencil icon next to the category heading.

+ - Select the **Save** button at the bottom of the page to save any changes.

+

+ 

+### Profile categories

+There are six categories of profile details you may be able to edit.

+- **Identity:** Add or update other identity values for the user, such as a married last name. You can set this name independently from the values of First name and Last name. For example, you could use it to include initials, a company name, or to change the sequence of names shown. If you have two users with the same name, such as ΓÇÿChris Green,ΓÇÖ you could use the Identity string to set their names to 'Chris B. Green' and 'Chris R. Green.'

+- **Job information:** Add any job-related information, such as the user's job title, department, or manager.

+- **Contact info:** Add any relevant contact information for the user.

+- **Parental controls:** For organizations like K-12 school districts, the user's age group may need to be provided. *Minors* are 12 and under, *Not adult* are 13-18 years old, and *Adults* are 18 and over. The combination of age group and consent provided by parent options determine the Legal age group classification. The Legal age group classification may limit the user's access and authority.

+- **Settings:** Decide whether the user can sign in to the Azure Active Directory tenant. You can also specify the user's global location.

+- **On-premises:** Accounts synced from Windows Server Active Directory include additional values not applicable to Azure AD accounts.

+### Add or edit the profile picture

+On the user's overview page, select the camera icon in the lower-right corner of the user's thumbnail. If no image has been added, the user's initials appear here. This picture appears in Azure Active Directory and on the user's personal pages, such as the myapps.microsoft.com page.

+All your changes are saved for the user.

+>[!Note]

+> If you're having issues updating a user's profile picture, please ensure that your Office 365 Exchange Online Enterprise App is Enabled for users to sign in.

+## Manage settings for all users

+In the **User settings** area of Azure AD, you can adjust several settings that affect all users, such as restricting access to the Azure AD administration portal, how external collaboration is managed, and providing users the option to connect their LinkedIn account. Some settings are managed in a separate area of Azure AD and linked from this page.

+Go to **Azure AD** > **User settings**.

+## Next steps

+- [View Azure AD enterprise user management documentation](../enterprise-users/index.yml).

+Add new users or delete existing users from your Azure Active Directory (Azure AD) tenant. To add or delete users, you must be a User Administrator or Global Administrator.

+You can create a new user for your organization or invite an external user from the same starting point.

+1. Sign in to the [Azure portal](https://portal.azure.com/) in the User Administrator role.

+1. Navigate to **Azure Active Directory** > **Users**.

+1. Select either **Create new user** or **Invite external user** from the menu. You can change this setting on the next screen.

+ 

+1. On the **New User** page, provide the new user's information:

+ - **Identity:** Add a user name and display name for the user. **User name** and **Name** are required and can't contain accent characters. You can also add a first and last name.

+ The domain part of the user name must use either the initial default domain name, *\<yourdomainname>.onmicrosoft.com*, or a custom domain name, such as *contoso.com*. For more information about how to create a custom domain name, see [Add your custom domain name using the Azure Active Directory portal](add-custom-domain.md).

+ - **Groups and roles:** Optional. Add the user to one or more existing groups. Group membership can be set at any time. For more information about adding users to groups, see the [manage groups article](how-to-manage-groups.md).

+ - **Settings:** Optional. Toggle the option to block sign-in for the user or set the user's default location.

+ - **Job info**: Optional. Add the user's job title, department, company name, and manager. These details can be updated at any time. For more information about adding other user info, see [How to manage user profile information](active-directory-users-profile-azure-portal.md).

+You can also invite new guest user to collaborate with your organization by selecting **Invite user** from the **New user** page. If your organization's external collaboration settings are configured to allow guests, the user will be emailed an invitation they must accept in order to begin collaborating. For more information about inviting B2B collaboration users, see [Invite B2B users to Azure Active Directory](../external-identities/add-users-administrator.md).

+The process for inviting a guest is the same as [adding a new user](add-users-azure-active-directory.md#add-a-new-user), with two exceptions. The email address won't follow the same domain rules as users from your organization. You can also include a personal message.

+## Add other users

+There might be scenarios in which you want to manually create consumer accounts in your Azure Active Directory B2C (Azure AD B2C) directory. For more information about creating consumer accounts, see [Create and delete consumer users in Azure AD B2C](../../active-directory-b2c/manage-users-portal.md).

+- You must have a Global Administrator, Privileged Authentication Administrator or User Administrator role assignment to delete users in your organization.

+- Global Admins and Privileged Authentication Admins can delete any users including other admins.

+- User Administrators can delete any non-admin users, Helpdesk Administrators and other User Administrators.

+- For more information, see [Administrator role permissions in Azure AD](../roles/permissions-reference.md).

+1. Sign in to the [Azure portal](https://portal.azure.com/) using one of the appropriate roles listed above.

+1. Go to **Azure Active Directory** > **Users**.

+1. Search for and select the user you want to delete from your Azure AD tenant.

+ 

+- [Add guest users from another directory](../external-identities/what-is-b2b.md)

+- [Add your organization's privacy info on Azure AD](./active-directory-properties-area.md)

+- [Learn more about Conditional Access](../conditional-access/overview.md)

+The following are additional operational considerations for Azure AD, specific to multiple isolated environments. Check the [Azure Cloud Adoption Framework](/azure/cloud-adoption-framework/manage/), the [Microsoft cloud security benchmark](/security/benchmark/azure/) and [Azure AD Operations guide](./active-directory-ops-guide-ops.md) for detailed guidance to operate individual environments.

+**Configuration separation** - In some cases, resources such as applications have dependencies on tenant-wide configurations like authentication methods or [named locations](../conditional-access/location-condition.md#named-locations). You should consider these dependencies when isolating resources. Global administrators can configure the resource settings and tenant-wide settings that affect resources.

+* [Best practices](secure-with-azure-ad-best-practices.md)

+- [Azure Government](../../azure-government/documentation-government-welcome.md)

+- [Create an Automation account using the Azure portal](../../automation/quickstarts/create-azure-automation-account-portal.md)

+Lifecycle Workflows allow you to create workflows that can be triggered based on joiner, mover, or leaver scenarios. While Lifecycle Workflows provide several built-in tasks to automate common scenarios throughout the lifecycle of users, eventually you may reach the limits of these built-in tasks. With the extensibility feature, you'll be able to utilize the concept of custom task extensions to call-out to external systems as part of a workflow. By calling out to the external systems, you're able to accomplish things, which can extend the purpose of your workflows. When a user joins your organization you can have a workflow with a custom task extension that assigns a Teams number, or have a separate workflow that grants access to an email account for a manager when a user leaves. With the extensibility feature, Lifecycle Workflows currently support creating custom tasks extensions to call-out to [Azure Logic Apps](../../logic-apps/logic-apps-overview.md).

+> The **Logic App Operator** role alone will not make an Azure Logic App compatible with the custom task extension. For more information on the required **Logic App contributor** role, see: [Logic App Contributor](../../role-based-access-control/built-in-roles.md#logic-app-contributor).

+- [Configure a Logic App for Lifecycle Workflow use (Preview)](configure-logic-app-lifecycle-workflows.md)

+For more comprehensive instructions on how to complete these prerequisite steps, you may refer to the [Preparing user accounts for Lifecycle workflows tutorial](tutorial-prepare-azure-ad-user-accounts.md). The [TAP policy](../authentication/howto-authentication-temporary-access-pass.md#enable-the-temporary-access-pass-policy) must also be enabled to run this tutorial.

+- [Automate employee onboarding tasks before their first day of work with Azure portal (preview)](tutorial-onboard-custom-workflow-portal.md)

+For more comprehensive instructions on how to complete these prerequisite steps, you may refer to the [Preparing user accounts for Lifecycle workflows tutorial](tutorial-prepare-azure-ad-user-accounts.md). The [TAP policy](../authentication/howto-authentication-temporary-access-pass.md#enable-the-temporary-access-pass-policy) must also be enabled to run this tutorial.

+- [Automate employee onboarding tasks before their first day of work with Microsoft Graph (preview)](tutorial-onboard-custom-workflow-graph.md)

+For more information about updating manager information for a user in Graph API, see [assign manager](/graph/api/user-post-manager?view=graph-rest-1.0&tabs=http&preserve-view=true) documentation. You can also set this attribute in the Azure Admin center. For more information, see [add or change profile information](../fundamentals/active-directory-users-profile-azure-portal.md?context=azure%2factive-directory%2fusers-groups-roles%2fcontext%2fugr-context).

+- [Tutorial: Off-boarding users from your organization using Lifecycle workflows with Microsoft Graph (preview)](tutorial-offboard-custom-workflow-graph.md)

+Lifecycle Workflows is a new Identity Governance service that enables organizations to manage Azure AD users by automating these three basic lifecycle processes:

+> If you received an email asking you to renew your certificate for Office, see [Managing changes to token signing certificates](#managecerts) to check if you need to take any action. Microsoft is aware of a possible issue that can lead to notifications for certificate renewal being sent, even when no action is required.

+* If it can successfully poll the federation metadata and retrieve the new certificates, no email notification is issued to the user.

+* If it cannot retrieve the new token signing certificates, either because the federation metadata is not reachable or automatic certificate rollover is not enabled, Azure AD issues an email.

+- Cloud [distribution list groups](/exchange/recipients-in-exchange-online/manage-distribution-groups/manage-distribution-groups) created in Exchange Online cannot be written back to AD, only Microsoft 365 and Azure AD security groups are supported.

+- [Disable Azure AD Connect group writeback](how-to-connect-group-writeback-disable.md)

+>To learn more about Cloud Sync please read [this article](../cloud-sync/what-is-cloud-sync.md), or watch this [short video](https://www.microsoft.com/videoplayer/embed/RWJ8l5).

+* [Integrating your on-premises identities with Azure Active Directory](whatis-hybrid-identity.md)

+If you have made configuration changes to the active server, you need to make sure that the same changes are applied to the new staging server. To help with this move, you can use the feature for [exporting and importing synchronization settings](./how-to-connect-import-export-config.md). With this feature you can deploy a new staging server in a few steps, with the exact same settings as another Azure AD Connect server in your network.

+Learn more about [integrating your on-premises identities with Azure Active Directory](whatis-hybrid-identity.md).

+>In case of verified domain change, Azure AD also recalculates the UserPrincipalName attribute. For more information, see [Troubleshoot: Audit data on verified domain change](../reports-monitoring/troubleshoot-audit-data-verified-domain.md)

+- [Custom installation of Azure AD Connect](how-to-connect-install-custom.md)

+Since data in transit can take place in different scenarios, is also relevant to know that Microsoft Azure uses [virtual networking](../../virtual-network/index.yml) to isolate tenantsΓÇÖ traffic from one another, employing measures such as host- and guest-level firewalls, IP packet filtering, port blocking, and HTTPS endpoints. However, most of AzureΓÇÖs internal communications, including infrastructure-to-infrastructure and infrastructure-to-customer (on-premises), are also encrypted. Another important scenario is the communications within Azure datacenters; Microsoft manages networks to assure that no VM can impersonate or eavesdrop on the IP address of another. TLS/SSL is used when accessing Azure Storage or SQL Databases, or when connecting to Cloud Services. In this case, the customer administrator is responsible for obtaining a TLS/SSL certificate and deploying it to their tenant infrastructure. Data traffic moving between Virtual Machines in the same deployment or between tenants in a single deployment via Microsoft Azure Virtual Network can be protected through encrypted communication protocols such as HTTPS, SSL/TLS, or others.

+[Design considerations overview](plan-hybrid-identity-design-considerations-overview.md)

+With [Microsoft Graph](/graph/overview) and [Microsoft Graph PowerShell](/powershell/microsoftgraph/get-started?view=graph-powershell-1.0&preserve-view=true), you can view and manage app consent policies.

+* [Manage app consent policies using Microsoft Graph](/graph/api/resources/permissiongrantpolicy)

+Learn how to use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets.

+Learn how to use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets.

+Learn how to use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets.

+Learn how to use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets.

+* Use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets

+* Use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets

+ Title: 'Tutorial: Azure AD SSO integration with Employee Advocacy by Sprout Social'

+description: Learn how to configure single sign-on between Azure Active Directory and Employee Advocacy by Sprout Social.

+# Tutorial: Azure AD SSO integration with Employee Advocacy by Sprout Social

+In this tutorial, you'll learn how to integrate Employee Advocacy by Sprout Social with Azure Active Directory (Azure AD). When you integrate Employee Advocacy by Sprout Social with Azure AD, you can:

+* Control in Azure AD who has access to Employee Advocacy by Sprout Social.

+* Enable your users to be automatically signed-in to Employee Advocacy by Sprout Social with their Azure AD accounts.

+* Employee Advocacy by Sprout Social single sign-on (SSO) enabled subscription.

+* Employee Advocacy by Sprout Social supports **SP** and **IDP** initiated SSO.

+* Employee Advocacy by Sprout Social supports **Just In Time** user provisioning.

+## Add Employee Advocacy by Sprout Social from the gallery

+To configure the integration of Employee Advocacy by Sprout Social into Azure AD, you need to add Employee Advocacy by Sprout Social from the gallery to your list of managed SaaS apps.

+1. In the **Add from the gallery** section, type **Employee Advocacy by Sprout Social** in the search box.

+1. Select **Employee Advocacy by Sprout Social** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

+## Configure and test Azure AD SSO for Employee Advocacy by Sprout Social

+Configure and test Azure AD SSO with Employee Advocacy by Sprout Social using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in Employee Advocacy by Sprout Social.

+To configure and test Azure AD SSO with Employee Advocacy by Sprout Social, perform the following steps:

+1. **[Configure Employee Advocacy by Sprout Social SSO](#configure-employee-advocacy-by-sprout-social-sso)** - to configure the single sign-on settings on application side.

+ 1. **[Create Employee Advocacy by Sprout Social test user](#create-employee-advocacy-by-sprout-social-test-user)** - to have a counterpart of B.Simon in Employee Advocacy by Sprout Social that is linked to the Azure AD representation of user.

+1. In the Azure portal, on the **Employee Advocacy by Sprout Social** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Basic SAML Configuration** section, the user does not have to perform any step as the app is already pre-integrated with Azure.

+1. Click **Set additional URLs** and perform the following step if you wish to configure the application in **SP** initiated mode:

+ In the **Sign-on URL** text box, type a URL using one of the following patterns:

+ | **Sign-on URL** |

+ |--|

+ | `https://advocacy.sproutsocial.com` |

+ | `https://<SUBDOMAIN>.advocacy.sproutsocial.com` |

+ > [!Note]

+ > This value is not the real. Update this value with the actual Sign-on URL. Contact [Employee Advocacy by Sprout Social Client support team](mailto:support@getbambu.com) to get the value. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+1. Employee Advocacy by Sprout Social application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes.

+ 

+1. In addition to above, Employee Advocacy by Sprout Social application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements.

+ | Name | Source Attribute|

+ | | |

+ | firstName | user.givenname |

+ | lastName | user.surname |

+ | email | user.mail |

+1. On the **Set up Single Sign-On with SAML** page, in the **SAML Signing Certificate** section, click **Download** to download the **Federation Metadata XML** from the given options as per your requirement and save it on your computer.

+1. On the **Set up Employee Advocacy by Sprout Social** section, copy the appropriate URL(s) as per your requirement.

+In this section, you'll enable B.Simon to use Azure single sign-on by granting access to Employee Advocacy by Sprout Social.

+1. In the applications list, select **Employee Advocacy by Sprout Social**.

+## Configure Employee Advocacy by Sprout Social SSO

+To configure single sign-on on **Employee Advocacy by Sprout Social** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [Employee Advocacy by Sprout Social support team](mailto:support@getbambu.com). They set this setting to have the SAML SSO connection set properly on both sides.

+### Create Employee Advocacy by Sprout Social test user

+In this section, a user called Britta Simon is created in Employee Advocacy by Sprout Social. Employee Advocacy by Sprout Social supports just-in-time user provisioning, which is enabled by default. There is no action item for you in this section. If a user doesn't already exist in Employee Advocacy by Sprout Social, a new one is created after authentication.

+In this section, you test your Azure AD single sign-on configuration with following options.

+#### SP initiated:

+* Click on **Test this application** in Azure portal. This will redirect to Employee Advocacy by Sprout Social Sign-on URL where you can initiate the login flow.

+* Go to Employee Advocacy by Sprout Social Sign-on URL directly and initiate the login flow from there.

+#### IDP initiated:

+* Click on **Test this application** in Azure portal and you should be automatically signed in to the Employee Advocacy by Sprout Social for which you set up the SSO.

+You can also use Microsoft My Apps to test the application in any mode. When you click the Employee Advocacy by Sprout Social tile in the My Apps, if configured in SP mode you would be redirected to the application sign-on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the Employee Advocacy by Sprout Social for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+Once you configure Employee Advocacy by Sprout Social you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Defender for Cloud Apps](/cloud-app-security/proxy-deployment-aad).

+For guidance on managing your Azure environment, we recommend you review the [Microsoft cloud security benchmark](/security/benchmark/azure/) and [Securing Azure environments with Azure Active Directory](https://aka.ms/AzureADSecuredAzure). These guides provide best practices for managing the underlying Azure resources, including Azure Key Vault, Azure Storage, websites, and other Azure-related services and capabilities.

+ Title: Azure Kubernetes Service support and help options

+description: How to obtain help and support for questions or problems when you create solutions using Azure Kubernetes Service.

+# Support and troubleshooting for Azure Kubernetes Service (AKS)

+Here are suggestions for where you can get help when developing your Azure Kubernetes Service (AKS) solutions.

+## Self help troubleshooting

+Various articles explain how to determine, diagnose, and fix issues that you might encounter when using Azure Kubernetes Service. Use these articles to troubleshoot deployment failures, security-related problems, connection issues and more.

+For a full list of self help troubleshooting content, see [Azure Kubernetes Service troubleshooting documentation](/troubleshoot/azure/azure-kubernetes/welcome-azure-kubernetes)

+## Post a question on Microsoft Q&A

+For quick and reliable answers on your technical product questions from Microsoft Engineers, Azure Most Valuable Professionals (MVPs), or our expert community, engage with us on [Microsoft Q&A](/answers/products/azure), Azure's preferred destination for community support.

+If you can't find an answer to your problem using search, submit a new question to Microsoft Q&A. Use one of the following tags when asking your question:

+| Area | Tag |

+|-|-|

+| [Azure Kubernetes Service](intro-kubernetes.md) | [azure-kubernetes-service](/answers/topics/azure-kubernetes-service.html)|

+| [Azure Container Registry](../container-registry/container-registry-intro.md) | [azure-container-registry](/answers/topics/azure-container-registry.html)|

+| [Azure storage accounts](../storage/common/storage-account-overview.md) | [azure-storage-accounts](/answers/topics/azure-storage-accounts.html)|

+| [Azure Managed Identities](../active-directory/managed-identities-azure-resources/overview.md) | [azure-managed-identity](/answers/topics/azure-managed-identity.html) |

+| [Azure RBAC](../role-based-access-control/overview.md) | [azure-rbac](/answers/topics/azure-rbac.html)|

+| [Azure Active Directory](../active-directory/fundamentals/active-directory-whatis.md) | [azure-active-directory](/answers/topics/azure-active-directory.html)|

+| [Azure Policy](../governance/policy/overview.md) | [azure-policy](/answers/topics/azure-policy.html)|

+| [Azure Virtual Machine Scale Sets](../virtual-machine-scale-sets/overview.md) | [virtual-machine-scale-sets](/answers/topics/azure-virtual-machine-scale-sets.html)|

+| [Azure Virtual Network](../virtual-network/network-overview.md) | [azure-virtual-network](/answers/topics/azure-virtual-network.html)|

+| [Azure Application Gateway](../application-gateway/overview.md) | [azure-application-gateway](/answers/topics/azure-application-gateway.html)|

+| [Azure Virtual Machines](../virtual-machines/linux/overview.md) | [azure-virtual-machines](/answers/topics/azure-virtual-machines.html) |

+## Create an Azure support request

+Explore the range of [Azure support options and choose the plan](https://azure.microsoft.com/support/plans) that best fits, whether you're a developer just starting your cloud journey or a large organization deploying business-critical, strategic applications. Azure customers can create and manage support requests in the Azure portal.

+- If you already have an Azure Support Plan, [open a support request here](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/newsupportrequest).

+- To sign up for a new Azure Support Plan, [compare support plans](https://azure.microsoft.com/support/plans/) and select the plan that works for you.

+## Create a GitHub issue

+If you need help with the language and tools used to develop and manage Azure Kubernetes Service, open an issue in its repository on GitHub.

+| Library | GitHub issues URL|

+| | |

+| Azure PowerShell | https://github.com/Azure/azure-powershell/issues |

+| Azure CLI | https://github.com/Azure/azure-cli/issues |

+| Azure REST API | https://github.com/Azure/azure-rest-api-specs/issues |

+| Azure SDK for Java | https://github.com/Azure/azure-sdk-for-java/issues |

+| Azure SDK for Python | https://github.com/Azure/azure-sdk-for-python/issues |

+| Azure SDK for .NET | https://github.com/Azure/azure-sdk-for-net/issues |

+| Azure SDK for JavaScript | https://github.com/Azure/azure-sdk-for-js/issues |

+| Terraform | https://github.com/Azure/terraform/issues |

+## Stay informed of updates and new releases

+Learn about important product updates, roadmap, and announcements in [Azure Updates](https://azure.microsoft.com/updates/?category=compute).

+News and information about Azure Virtual Machines is shared at the [Azure blog](https://azure.microsoft.com/blog/topics/virtual-machines/).

+## Next steps

+Learn more about [Azure Kubernetes Service](./index.yml)

+> Deployment Center for Azure Kubernetes Service will be retired on March 31, 2023. [Learn more](#retirement)

+Deployment Center for Azure Kubernetes will be retired on March 31, 2023 in favor of [Automated deployments](./automated-deployments.md). We encourage you to switch for enjoy similar capabilities.

+There is no migration required as AKS Deployment center experience does not store any information itself, it just helps users with their Day 0 getting started experience on Azure. Moving forward, the recommended way for users to get started on CI/CD for AKS will be using [Automated deployments](./automated-deployments.md) feature.

+You can use Automated deployments available in the AKS blade in Azure portal.

+ 1. You can provide the TLS/SSL certificate presented by the Azure Application Gateway. Leave the values at the default to cause the offer to generate a self-signed certificate. Do not go to production using a self-certificate. For more information about self-signed certificates, see [Create a self-signed public certificate to authenticate your application](../active-directory/develop/howto-create-self-signed-certificate.md).

+* [Open Liberty Server Configuration](https://openliberty.io/docs/ref/config/)

+| 1.25 | Aug 2022 | Oct 2022 | Dec 2022 | 1.28 GA

+The same principle applies to Managed Identities used for any other pod/node pool when accessing other Azure resources. Any access provided via Managed Identity needs to be updated to reflect the new node pool. To view update and sign-in activities, see [How to view Managed Identity activity](../active-directory/managed-identities-azure-resources/how-to-view-managed-identity-activity.md).

+- A DNS solution, such as [Azure DNS](../dns/dns-getstarted-portal.md).

+If you want the add-on to automatically manage creating hostnames via Azure DNS, you need to [create an Azure DNS zone](../dns/dns-getstarted-cli.md) if you don't have one already.

+> To enable the add-on to reload certificates from Azure Key Vault when they change, you should to enable the [secret autorotation feature](./csi-secrets-store-driver.md#enable-and-disable-autorotation) of the Secret Store CSI driver with the `--enable-secret-rotation` argument. When the autorotation is enabled, the driver updates the pod mount and the Kubernetes secret by polling for changes periodically, based on the rotation poll interval you can define. The default rotation poll interval is 2 minutes.

+> To enable the add-on to reload certificates from Azure Key Vault when they change, you should to enable the [secret autorotation feature](./csi-secrets-store-driver.md#enable-and-disable-autorotation) of the Secret Store CSI driver with the `--enable-secret-rotation` argument. When the autorotation is enabled, the driver updates the pod mount and the Kubernetes secret by polling for changes periodically, based on the rotation poll interval you can define. The default rotation poll interval is 2 minutes.

+[ingress-resource]: https://kubernetes.io/docs/concepts/services-networking/ingress/#the-ingress-resource

+ * [Create a container](../storage/blobs/storage-quickstart-blobs-portal.md#create-a-container) in the storage account to hold the backup data.

+[azure-storage-ip-firewall]: ../storage/common/storage-network-security.md#grant-access-from-an-internet-ip-range

+* [Azure Resource Manager](../../azure-resource-manager/management/overview.md)

+* [Bicep](../../azure-resource-manager/bicep/overview.md)

+[17]: ../azure-resource-manager/templates/deployment-tutorial-pipeline.md

+Your Node.js app needs to listen to the right port to receive incoming requests.

+Use [Azure Pipelines](/azure/devops/pipelines/) to automatically deploy your web app to [Azure App Service](./overview.md) on every successful build. Azure Pipelines lets you build, test, and deploy with continuous integration (CI) and continuous delivery (CD) using [Azure DevOps](/azure/devops/).

+](./configure-common.md) for more details.

+For most language stacks, [app settings](./configure-common.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json#configure-app-settings) and [connection strings](./configure-common.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json#configure-connection-strings) can be set as environment variables at runtime.

+App settings can also be resolved from Key Vault using [Key Vault references](./app-service-key-vault-references.md).

+- Customize your [Azure DevOps pipeline](/azure/devops/pipelines/customize-pipeline).

+- [Azure DevOps Pipelines](/azure/devops/pipelines/targets/webapp?view=azure-devops)

+- [Azure CLI](./deploy-zip.md?tabs=cli)

+- [VS Code](./deploy-zip.md?tabs=cli)

+- [Local Git Repository](./deploy-local-git.md?tabs=cli)

+> [Deploy from local Git repo](deploy-local-git.md)

+ See [Disable cache for auth workflow](../static-web-apps/front-door-manual.md#disable-cache-for-auth-workflow) to learn more on how to configure rules in Azure Front Door to disable caching for authentication and authorization-related pages.

+- [Getting Azure App Service authentication working with .NET Core (3rd party)](https://github.com/kirkone/KK.AspNetCore.EasyAuthAuthentication)

+Besides App Service, Azure offers other services that can be used for hosting websites and web applications. For most scenarios, App Service is the best choice. For microservice architecture, consider [Azure Spring Apps](../spring-apps/index.yml) or [Service Fabric](../service-fabric/index.yml). If you need more control over the VMs on which your code runs, consider [Azure Virtual Machines](../virtual-machines/index.yml). For more information about how to choose between these Azure services, see [Azure App Service, Virtual Machines, Service Fabric, and Cloud Services comparison](/azure/architecture/guide/technology-choices/compute-decision-tree).

+> [Custom container (Windows or Linux)](tutorial-custom-container.md)

+[WordPress](https://www.wordpress.org) is an open source content management system (CMS) used by over 40% of the web to create websites, blogs, and other applications. WordPress can be run on a few different Azure

+In this quickstart, you'll learn how to create and deploy your first [WordPress](https://www.wordpress.org/) site to [Azure App Service on Linux](overview.md#app-service-on-linux) with [Azure Database for MySQL - Flexible Server](../mysql/flexible-server/index.yml) using the [WordPress Azure Marketplace item by App Service](https://azuremarketplace.microsoft.com/marketplace/apps/WordPress.WordPress?tab=Overview). This quickstart uses the **Basic** tier for your app and a **Burstable, B1ms** tier for your database, and incurs a cost for your Azure Subscription. For pricing, visit [App Service pricing](https://azure.microsoft.com/pricing/details/app-service/linux/) and [Azure Database for MySQL pricing](https://azure.microsoft.com/pricing/details/mysql/flexible-server/).

+- The MySQL Flexible Server is created behind a private [Virtual Network](../virtual-network/virtual-networks-overview.md) and can't be accessed directly. To access or manage the database, use phpMyAdmin that's deployed with the WordPress site. You can access phpMyAdmin by following these steps:

+- To change the MySQL database password, see [Reset admin password](../mysql/flexible-server/how-to-manage-server-portal.md#reset-admin-password). Whenever the MySQL database credentials are changed, the [Application Settings](reference-app-settings.md#wordpress) need to be updated. The [Application Settings for MySQL database](reference-app-settings.md#wordpress) begin with the **`DATABASE_`** prefix. For more information on updating MySQL passwords, see [WordPress on App Service](https://github.com/Azure/wordpress-linux-appservice/blob/main/WordPress/changing_mysql_database_password.md).

+> [Configure PHP app](configure-language-php.md)

+ Title: Prevent subdomain takeovers

+description: Describes options for dangling subdomain prevention on Azure App Service.

+# What is a subdomain takeover?

+Subdomain takeovers are a common threat for organizations that regularly create and delete many resources. A subdomain takeover can occur when you have a DNS record that points to a deprovisioned Azure resource. Such DNS records are also known as "dangling DNS" entries. Subdomain takeovers enable malicious actors to redirect traffic intended for an organizationΓÇÖs domain to a site performing malicious activity.

+The risks of subdomain takeover include:

+- Loss of control over the content of the subdomain

+- Cookie harvesting from unsuspecting visitors

+- Phishing campaigns

+- Further risks of classic attacks such as XSS, CSRF, CORS bypass

+Learn more about Subdomain Takeover at [Dangling DNS and subdomain takeover](../security/fundamentals/subdomain-takeover.md).

+Azure App Service provides [Name Reservation](#how-name-reservation-service-works) Service and [domain verification tokens](#domain-verification-token) to prevent subdomain takeovers.

+## How Name Reservation Service works

+Upon deletion of an App Service app, the corresponding DNS is reserved. During the reservation period, re-use of the DNS will be forbidden except for subscriptions belonging to tenant of the subscription originally owning the DNS.

+After the reservation expires, the DNS is free to be claimed by any subscription. By Name Reservation Service, the customer is afforded some time to either clean up any associations/pointers to said DNS or re-claim the DNS in Azure. The DNS name being reserved can be derived by appending 'azurewebsites.net'. Name Reservation Service is enabled by default on Azure App Service and doesn't require additional configuration.

+#### Example scenario

+Subscription 'A' and subscription 'B' are the only subscriptions belonging to tenant 'AB'. Subscription 'A' contains an App Service app 'test' with DNS name 'test'.azurewebsites.net'. Upon deletion of the app, a reservation is taken on DNS name 'test.azurewebsites.net'.

+During the reservation period, only subscription 'A' or subscription 'B' will be able to claim the DNS name 'test.azurewebsites.net' by creating a web app named 'test'. No other subscriptions will be allowed to claim it. After the reservation period is complete, any subscription in Azure can now claim 'test.azurewebsites.net'.

+## Domain verification token

+When creating DNS entries for Azure App Service, create an asuid.{subdomain} TXT record with the Domain Verification ID. When such a TXT record exists, no other Azure Subscription can validate the Custom Domain or take it over unless they add their token verification ID to the DNS entries.

+These records prevent the creation of another App Service app using the same name from your CNAME entry. Without the ability to prove ownership of the domain name, threat actors can't receive traffic or control the content.

+DNS records should be updated before the site deletion to ensure bad actors can't take over the domain between the period of deletion and re-creation. Be aware that the DNS records take time to propagate.

+To get a domain verification ID, see the [Map a custom domain tutorial](app-service-web-tutorial-custom-domain.md#2-get-a-domain-verification-id)

+[Azure App Service](overview.md) provides a highly scalable, self-patching web hosting service in Azure. It also provides a [managed identity](overview-managed-identity.md) for your app, which is a turn-key solution for securing access to [Azure Database for PostgreSQL](../postgresql/index.yml) and other Azure services. Managed identities in App Service make your app more secure by eliminating secrets from your app, such as credentials in the environment variables. In this tutorial, you will learn how to:

+> [Java in App Service Linux dev guide](configure-language-java.md?pivots=platform-linux)

+* [Azure Load Balancer](../load-balancer/index.yml)

+* [Azure Traffic Manager](../traffic-manager/index.yml)

+* Use a [token credential from azure-identity](#use-an-azure-active-directory-azure-ad-token-credential) to authenticate with [Azure Active Directory](../../active-directory/fundamentals/active-directory-whatis.md).

+> Regional endpoints do not support AAD authentication. Create a [custom subdomain](../../cognitive-services/authentication.md?tabs=powershell#create-a-resource-with-a-custom-subdomain) for your resource in order to use this type of authentication.

+1. [Register an Azure AD application and create a new service principal](../../cognitive-services/authentication.md?tabs=powershell#assign-a-role-to-a-service-principal).

+1. [Register an Azure AD application and create a new service principal](../../cognitive-services/authentication.md?tabs=powershell#assign-a-role-to-a-service-principal).

+1. [Register an Azure AD application and create a new service principal](../../cognitive-services/authentication.md?tabs=powershell#assign-a-role-to-a-service-principal).

+1. [Register an Azure AD application and create a new service principal](../../cognitive-services/authentication.md?tabs=powershell#assign-a-role-to-a-service-principal).

+> [**Explore the Form Recognizer REST API v3.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)

+ * [**Azure Functions Core Tools**](../../azure-functions/functions-run-local.md?tabs=v3%2cwindows%2ccsharp%2cportal%2cbash) version 3.x (Version 4.x isn't supported for this project).

+* Learn more about the [layout model](concept-layout.md)

+- An Azure Automation account. For instructions, see [Create an Azure Automation account](./quickstarts/create-azure-automation-account-portal.md).

+- Availability zone support for Automation accounts supports only [Process Automation](./overview.md#process-automation) feature to provide an improved resiliency for runbook automation.

+- [Azure portal](./automation-create-standalone-account.md?tabs=azureportal)

+- [Azure Resource Manager (ARM) template](./quickstart-create-automation-account-template.md)

+You'll still be able to create a Run As account through a [PowerShell script](./create-run-as-account.md#create-account-using-powershell) until support ends. You can [use this script](https://github.com/azureautomation/runbooks/blob/master/Utility/AzRunAs/RunAsAccountAssessAndRenew.ps1) to renew the certificate after *January 30, 2023*, until *September 30, 2023*. This script will assess the Automation account that has configured Run As accounts and renew the certificate if you choose to do so. On confirmation, the script will renew the key credentials of the Azure Active Directory (Azure AD) app and upload new a self-signed certificate to the Azure AD app.

+For more information about managed identities in Azure AD, see [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md).

+Azure Automation supports [system-assigned managed identities](./automation-security-overview.md#managed-identities) for both cloud and hybrid jobs. Currently, Azure Automation [user-assigned managed identities](./automation-security-overview.md) can be used for cloud jobs only and can't be used for jobs that run on a hybrid worker.

+Yes, but only in a scenario where managed identities aren't supported for specific on-premises resources. We'll allow the creation of a Run As account through a [PowerShell script](./create-run-as-account.md#create-account-using-powershell).

+Follow the steps in [Migrate an existing Run As account to a managed identity](./migrate-run-as-accounts-managed-identity.md).

+- [Azure Automation](/answers/topics/azure-automation.html)

+> Azure Automation Run As Account will retire on September 30, 2023 and will be replaced with Managed Identities. Before that date, you'll need to start migrating your runbooks to use [managed identities](automation-security-overview.md#managed-identities). For more information, see [migrating from an existing Run As accounts to managed identity](migrate-run-as-accounts-managed-identity.md?tabs=run-as-account#sample-scripts) to start migrating the runbooks from Run As account to managed identities before 30 September 2023.

+The platform components of Azure Automation Service are actively secured and hardened. The service goes through robust security and compliance checks. the [Microsoft cloud security benchmark](/security/benchmark/azure/overview) details the best practices and recommendations to help improve the security of workloads, data, and services on Azure. Also see [Azure security baseline for Azure Automation](/security/benchmark/azure/baselines/automation-security-baseline?toc=/azure/automation/TOC.json).

+An Azure Automation account is different from your Microsoft account or accounts created in your Azure subscription. For an introduction to creating an Automation account, see [Create an Automation account](./quickstarts/create-azure-automation-account-portal.md).

+* For a list of Azure services that support the managed identities for Azure resources feature, see [Services that support managed identities for Azure resources](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md).

+- An Azure Automation account. For instructions, see [Create an Azure Automation account](./quickstarts/create-azure-automation-account-portal.md).

+To complete the steps in this article, you need an account in Azure Automation. See [Create an Azure Automation account](./quickstarts/create-azure-automation-account-portal.md).

+ - If you're using Az modules, update to the latest version by following the steps in the [Update Azure PowerShell modules](./automation-update-azure-modules.md?branch=main#update-az-modules) article.

+ try

+try

+> [Create an Automation account](./quickstarts/create-azure-automation-account-portal.md)

+- An Azure Automation account. For instructions, see [Create an Automation account](./create-azure-automation-account-portal.md).

+> [Tutorial: Create Automation PowerShell runbook using managed identity](../learn/powershell-runbook-managed-identity.md)

+- Currently, you can only authenticate with replica endpoints with [Azure Active Directory (Azure AD)](../app-service/overview-managed-identity.md).

+> [Resiliency and Disaster Recovery](./concept-disaster-recovery.md)

+ Secret Manager stores the secret outside of your project tree, which helps prevent the accidental sharing of secrets within source code. It's used only to test the web app locally. When the app is deployed to Azure like [App Service](../app-service/overview.md), use the *Connection strings*, *Application settings* or environment variables to store the connection string. Alternatively, to avoid connection strings all together, you can [connect to App Configuration using managed identities](./howto-integrate-azure-managed-service-identity.md) or your other [Azure AD identities](./concept-enable-rbac.md).

+> [Enable dynamic configuration](./enable-dynamic-configuration-aspnet-core.md)

+[Azure Private Link](../../private-link/private-link-overview.md) allows you to securely link Azure services to your virtual network using private endpoints. This means you can connect your on-premises Kubernetes clusters with Azure Arc and send all traffic over an Azure ExpressRoute or site-to-site VPN connection instead of using public networks. In Azure Arc, you can use a Private Link Scope model to allow multiple Kubernetes clusters to communicate with their Azure Arc resources using a single private endpoint.

+For more information, see [Key benefits of Azure Private Link](../../private-link/private-link-overview.md#key-benefits).

+Connectivity to the other Azure resources from an Arc-enabled Kubernetes cluster listed earlier requires configuring Private Link for each service. For an example, see [Private Link for Azure Monitor](../../azure-monitor/logs/private-link-security.md).

+* All on-premises Kubernetes clusters need to use the same private endpoint by resolving the correct private endpoint information (FQDN record name and private IP address) using the same DNS forwarder. For more information, see [Azure Private Endpoint DNS configuration](../../private-link/private-endpoint-dns.md). The Azure Arc-enabled Kubernetes cluster, Azure Arc Private Link Scope, and virtual network must be in the same Azure region. The Private Endpoint and the virtual network must also be in the same Azure region, but this region can be different from that of your Azure Arc Private Link Scope and Arc-enabled Kubernetes cluster.

+* [Azure Monitor](../../azure-monitor/logs/private-link-security.md)

+1. Establish a connection between your on-premises network and an Azure virtual network using a [site-to-site VPN](../../vpn-gateway/tutorial-site-to-site-portal.md) or [ExpressRoute](../../expressroute/expressroute-howto-linkvnet-arm.md) circuit.

+* If your network is configured to route all internet-bound traffic through the Azure VPN or ExpressRoute circuit, you can configure the network security group (NSG) associated with your subnet in Azure to allow outbound TCP 443 (HTTPS) access to Azure AD, Azure Resource Manager, Azure Front Door and Microsoft Container Registry using [service tags](../../virtual-network/service-tags-overview.md). The NSG rules should look like the following:

+ > If you choose **No** and prefer to manage DNS records manually, first complete setting up your Private Link, including this private endpoint and the Private Scope configuration. Next, configure your DNS according to the instructions in [Azure Private Endpoint DNS configuration](../../private-link/private-endpoint-dns.md). Make sure not to create empty records as preparation for your Private Link setup. The DNS records you create can override existing settings and impact your connectivity with Arc-enabled Kubernetes clusters.

+The private endpoint documentation provides guidance for configuring [on-premises workloads using a DNS forwarder](../../private-link/private-endpoint-dns.md#on-premises-workloads-using-a-dns-forwarder).

+* Learn more about [Azure Private Endpoint](../../private-link/private-link-overview.md).

+* Learn how to [troubleshoot Azure Private Endpoint connectivity problems](../../private-link/troubleshoot-private-endpoint-connectivity.md).

+* Learn how to [configure Private Link for Azure Monitor](../../azure-monitor/logs/private-link-security.md).

+ Title: Automatic extension upgrade for Azure Arc-enabled servers

+description: Learn how to enable automatic extension upgrades for your Azure Arc-enabled servers.

+# Automatic extension upgrade for Azure Arc-enabled servers

+Automatic extension upgrade is available for Azure Arc-enabled servers that have supported VM extensions installed. Automatic extension upgrades reduce the amount of operational overhead for you by scheduling the installation of new extension versions when they become available. The Azure Connected Machine agent takes care of upgrading the extension (preserving its settings along the way) and automatically rolling back to the previous version if something goes wrong during the upgrade process.

+Automatic extension upgrade has the following features:

+- You can opt in and out of automatic upgrades at any time. By default, all extensions are opted into automatic extension upgrades.

+- Supported in all Azure Arc regions.

+If you continue to have trouble upgrading an extension, you can [disable automatic extension upgrade](#manage-automatic-extension-upgrade) to prevent the system from trying again while you troubleshoot the issue. You can [enable automatic extension upgrade](#manage-automatic-extension-upgrade) again when you're ready.

+## Manage automatic extension upgrade

+Automatic extension upgrade is enabled by default when you install extensions on Azure Arc-enabled servers. To enable automatic upgrades for an existing extension, you can use Azure CLI or Azure PowerShell to set the `enableAutomaticUpgrade` property on the extension to `true`. You'll need to repeat this process for every extension where you'd like to enable or disable automatic upgrades.

+### [Azure portal](#tab/azure-portal)

+Use the following steps to configure automatic extension upgrades in using the Azure portal:

+1. Navigate to the [Azure portal](https://portal.azure.com) and type **Servers - Azure Arc** into the search bar.

+ :::image type="content" source="media/manage-automatic-vm-extension-upgrade/portal-search-arc-server.png" alt-text="Screenshot of Azure portal showing user typing in Servers - Azure Arc." border="true":::

+1. Select **Servers - Azure Arc** under the Services category, then select the individual server you wish to manage.

+1. In the navigation pane, select the **Extensions** tab to see a list of all extensions installed on the server.

+ :::image type="content" source="media/manage-automatic-vm-extension-upgrade/portal-navigation-extensions.png" alt-text="Screenshot of an Azure Arc-enabled server in the Azure portal showing where to navigate to extensions." border="true":::

+1. The **Automatic upgrade** column in the table shows whether upgrades are enabled, disabled, or not supported for each extension. Select the checkbox next to the extensions for which you want automatic upgrades enabled, then select **Enable automatic upgrade** to turn on the feature. Select **Disable automatic upgrade** to turn off the feature.

+ :::image type="content" source="media/manage-automatic-vm-extension-upgrade/portal-enable-auto-upgrade.png" alt-text="Screenshot of Azure portal showing how to select extensions and enable automatic upgrades." border="true":::

+### [Azure CLI](#tab/azure-cli)

+To check the status of automatic extension upgrade for all extensions on an Arc-enabled server, run the following command:

+```azurecli

+az connectedmachine extension list --resource-group resourceGroupName --machine-name machineName --query "[].{Name:name, AutoUpgrade:properties.enableAutoUpgrade}" --output table

+```

+Use the [az connectedmachine extension update](/cli/azure/connectedmachine/extension) command to enable automatic upgrades on an extension:

+ --name extensionName \

+To disable automatic upgrades, set the `--enable-auto-upgrade` parameter to `false`, as shown below:

+az connectedmachine extension update \

+ --resource-group resourceGroupName \

+ --machine-name machineName \

+ --name extensionName \

+ --enable-auto-upgrade false

+### [Azure PowerShell](#tab/azure-powershell)

+To enable automatic upgrades for an extension using Azure PowerShell, use the [Update-AzConnectedMachineExtension](/powershell/module/az.connectedmachine/update-azconnectedmachineextension) cmdlet:

+```azurepowershell

+Update-AzConnectedMachineExtension -ResourceGroup resourceGroupName -MachineName machineName -Name extensionName -EnableAutomaticUpgrade

+```

+To disable automatic upgrades, set `-EnableAutomaticUpgrade:$false` as shown in the example below:

+```azurepowershell

+Update-AzConnectedMachineExtension -ResourceGroup resourceGroupName -MachineName machineName -Name extensionName -EnableAutomaticUpgrade:$false

+```

+> [!TIP]

+> The cmdlets above come from the [Az.ConnectedMachine](/powershell/module/az.connectedmachine) PowerShell module. You can install this PowerShell module with `Install-Module Az.ConnectedMachine` on your computer or in Azure Cloud Shell.

+## Extension upgrades with multiple extensions

+A machine managed by Arc-enabled servers can have multiple extensions with automatic extension upgrade enabled. The same machine can also have other extensions without automatic extension upgrade enabled.

+If multiple extension upgrades are available for a machine, the upgrades may be batched together, but each extension upgrade is applied individually on a machine. A failure on one extension doesn't impact the other extension(s) to be upgraded. For example, if two extensions are scheduled for an upgrade, and the first extension upgrade fails, the second extension will still be upgraded.

+To view automatic extension upgrade history, search for the **Azure Activity Log** in the Azure portal. Select **Add filter** and choose the Operation filter. For the filter criteria, search for "Upgrade Extensions on Azure Arc machines" and select that option. You can optionally add a second filter for **Event initiated by** and set "Azure Regional Service Manager" as the filter criteria to only see automatic upgrade attempts and exclude upgrades manually initiated by users.

+This template is responsible for installing the Azure Arc [Connected Machine agent](./agent-overview.md) on hosts within the provided inventory. A successful run will have installed the agent on all machines.

+Learn more about [connecting machines using Ansible playbooks](onboard-ansible-playbooks.md).

+1. Download and unzip the folder **ArcEnabledServersGroupPolicy_v1.0.1** from [https://aka.ms/gp-onboard](https://aka.ms/gp-onboard). This folder contains the ArcGPO project structure with the scripts `EnableAzureArc.ps1`, `DeployGPO.ps1`, and `AzureArcDeployment.psm1`. These assets will be used for onboarding the machine to Azure Arc-enabled servers.

+1. Execute the deployment script `DeployGPO.ps1`, modifying the run parameters for the DomainFQDN, ReportServerFQDN, ArcRemoteShare, Service Principal secret, Service Principal Client Id, Subscription Id, Resource Group, Region, Tenant, and AgentProxy (if applicable):

+ .\DeployGPO.ps1 -DomainFQDN contoso.com -ReportServerFQDN Server.contoso.com -ArcRemoteShare AzureArcOnBoard -ServicePrincipalSecret $ServicePrincipalSecret -ServicePrincipalClientId $ServicePrincipalClientId -SubscriptionId $SubscriptionId --ResourceGroup $ResourceGroup -Location $Location -TenantId $TenantId [-AgentProxy $AgentProxy]

+| AZCM0041 | The credentials supplied are invalid | For device logins, verify that the user account specified has access to the tenant and subscription where the server resource will be created^{[1](#footnote3)}.<br> For service principal logins, check the client ID and secret for correctness, the expiration date of the secret^{[2](#footnote4)}, and that the service principal is from the same tenant where the server resource will be created^{[1](#footnote3)}.<br> <a name="footnote3"></a>¹See [How to find your Azure Active Directory tenant ID](../../active-directory/fundamentals/active-directory-how-to-find-tenant.md).<br> <a name="footnote4"></a>²In Azure portal, open Azure Active Directory and select the App registration blade. Select the application to be used and the Certificates and secrets within it. Check whether the expiration data has passed. If it has, create new credentials with sufficient roles and try again. See [Connected Machine agent prerequisites-required permissions](prerequisites.md#required-permissions). |

+* File an Azure support incident. Go to the [Azure support site](https://azure.microsoft.com/support/options/), and select **Get Support**.

+>[!Note]

+>If VMM server is running on Windows Server 2016 machine, ensure that [Open SSH package](https://github.com/PowerShell/Win32-OpenSSH/releases) is installed.

+> Geo-replication metrics are affected by monthly internal maintenance operations. The Azure Cache for Redis service periodically patches all caches with the latest platform features and improvements. During these updates, each cache node is taken offline, which temporarily disables the geo-replication link. If your geo replication link is unhealthy, check to see if it was caused by a patching event on either the geo-primary or geo-secondary cache by using **Diagnose and Solve Problems** from the Resource menu in the portal. Depending on the amount of data in the cache, the downtime from patching can take anywhere from a few minutes to an hour. If the geo-replication link is unhealthy for over an hour, [file a support request](../azure-portal/supportability/how-to-create-azure-support-request.md).

+ - If the geo-replication link is unhealthy for over an hour, [file a support request](../azure-portal/supportability/how-to-create-azure-support-request.md).

+- [`INFO`](https://redis.io/commands/info)

+- Upgrading a cache with a dependency on Cloud Services isn't supported. You should migrate your cache instance to virtual machine scale set before upgrading. For more information, see [Caches with a dependency on Cloud Services (classic)](./cache-faq.yml) for details on cloud services hosted caches.

+- To learn more about Azure Cache for Redis features: [Azure Cache for Redis Premium service tiers](cache-overview.md#service-tiers)

+By default, this article shows you how to create C# functions that run [in the same process as the Functions host](functions-dotnet-class-library.md). These _in-process_ C# functions are only supported on Long Term Support (LTS) versions of .NET, such as .NET 6. To create C# functions on .NET 6 that can also run on [other supported versions](functions-versions.md) for Azure functions [in an isolated process](dotnet-isolated-process-guide.md).

+## AzureFunctionsWebHost__hostid

+|AzureFunctionsWebHost__hostid|`myuniquefunctionappname123456789`|

+| [API Management policy samples](../api-management/policies/index.md) | Helpful collection of samples using API Management policies in key scenarios. |

+> [Expose serverless APIs from HTTP endpoints using Azure API Management](functions-openapi-definition.md)

+| C# class library | in-process | .cs | [Visual Studio](functions-develop-vs.md)<br/>[Visual Studio Code](functions-develop-vs-code.md)<br />[Core Tools](functions-run-local.md)| [In-process C# class library functions](functions-dotnet-class-library.md) |

+| C# class library (isolated process)| in an isolated process | .cs | [Visual Studio](functions-develop-vs.md)<br/>[Visual Studio Code](functions-develop-vs-code.md)<br />[Core Tools](functions-run-local.md) | [.NET isolated process functions](dotnet-isolated-process-guide.md) |

+| 4.x | GA | **_Recommended runtime version for functions in all languages._** Check out [Supported language versions](#languages). |

+| 3.x | GA | Supports all languages. Check out [Supported language versions](#languages).|

+For a set of security recommendations that follow the [Microsoft cloud security benchmark](/security/benchmark/azure/introduction), see [Azure Security Baseline for Azure Functions](/security/benchmark/azure/baselines/functions-security-baseline).

+You can explicitly set a specific host ID for your function app in the application settings by using the `AzureFunctionsWebHost__hostid` setting. For more information, see [AzureFunctionsWebHost__hostid](functions-app-settings.md#azurefunctionswebhost__hostid).

+The software implementation of a physical computer that runs an operating system. Multiple virtual machines can run simultaneously on the same hardware. In Azure, virtual machines are available in a variety of sizes. For more information, see [Virtual Machines documentation](./virtual-machines/index.yml)

+* [Azure in your datacenter](https://azure.microsoft.com/overview/business-apps-on-azure/)

+| [Microsoft Defender for Cloud](../../security-center/security-center-introduction.md) | Public preview | <ul><li>Azure Security Agent extension</li><li>SQL Advanced Threat Protection extension</li><li>SQL Vulnerability Assessment extension</li></ul> | [Auto-deployment of Azure Monitor Agent (Preview)](../../defender-for-cloud/auto-deploy-azure-monitoring-agent.md) |

+| [Microsoft Sentinel](../../sentinel/overview.md) | <ul><li>Windows Security Events: [Generally available](../../sentinel/connect-windows-security-events.md?tabs=AMA)</li><li>Windows Forwarding Event (WEF): [Public preview](../../sentinel/data-connectors-reference.md#windows-forwarded-events-preview)</li><li>Windows DNS logs: [Public preview](../../sentinel/connect-dns-ama.md)</li><li>Linux Syslog CEF: Preview</li></ul> | Sentinel DNS extension, if youΓÇÖre collecting DNS logs. For all other data types, you just need the Azure Monitor Agent extension. | <ul><li>[Sign-up link for Linux Syslog CEF](https://aka.ms/amadcr-privatepreviews)</li><li>No sign-up needed for Windows Forwarding Event (WEF), Windows Security Events and Windows DNS events</li></ul> |

+| | Windows Client OS | X | | |

+The following tables list the operating systems that Azure Monitor Agent and the legacy agents support. All operating systems are assumed to be x64. x86 isn't supported for any operating system.

+View [supported operating systems for Azure Arc Connected Machine agent](../../azure-arc/servers/prerequisites.md#supported-operating-systems), which is a prerequisite to run Azure Monitor agent on physical servers and virtual machines hosted outside of Azure (that is, on-premises) or in other clouds.

+| Operating system | Azure Monitor agent | Log Analytics agent (legacy) | Diagnostics extension |

+|:|::|::|::|

+² Using the Azure Monitor agent [client installer](./azure-monitor-agent-windows-client.md).<br>

+| Operating system | Azure Monitor agent ¹ | Log Analytics agent (legacy) ¹ | Diagnostics extension ²|

+|:|::|::|::|

+- [Create a data collection rule](data-collection-rule-azure-monitor-agent.md) to collect data from the agent and send it to Azure Monitor.

+To perform a one-time update of the agent, you must first uninstall the existing agent version, then install the new version as described.

+We recommend that you enable automatic update of the agent by enabling the [Automatic Extension Upgrade](../../azure-arc/servers/manage-automatic-vm-extension-upgrade.md#manage-automatic-extension-upgrade) feature by using the following PowerShell commands.

+To perform a one-time update of the agent, you must first uninstall the existing agent version, then install the new version as described.

+ We recommend that you enable automatic update of the agent by enabling the [Automatic Extension Upgrade](../../azure-arc/servers/manage-automatic-vm-extension-upgrade.md#manage-automatic-extension-upgrade) feature by using the following PowerShell commands.

+- Possible rare condition with using built-in user-assigned identity creation policy. [Learn more](../../active-directory/managed-identities-azure-resources/how-to-assign-managed-identity-via-azure-policy.md#known-issues).

+Azure Monitor Agent (AMA) replaces the Log Analytics Agent (MM) include enhanced security, cost-effectiveness, performance, manageability and reliability. This article explains how to use the AMA Migration Helper and DCR Config Generator tools to help automate and track the migration from Log Analytics Agent to Azure Monitor Agent.

+Review the [prerequisites](./azure-monitor-agent-manage.md#prerequisites) for use with Azure Monitor Agent. For non-Azure servers, [installing the Azure Arc agent](../../azure-arc/servers/agent-overview.md) is an important prerequisite that then helps to install the agent extension and other required extensions. Using Azure Arc for this purpose comes at no added cost. It's not mandatory to use Azure Arc for server management overall. You can continue using your existing non-Azure management solutions. After the Azure Arc agent is installed, you can follow the same guidance in this article across Azure and non-Azure for migration.

+- [Frequently asked questions for Azure Monitor Agent migration](/azure/azure-monitor/faq#azure-monitor-agent)

+### Permissions required

+Since MO is a tenant level resource, the scope of the permission would be higher than a subscription scope. Therefore, an Azure tenant admin may be needed to perform this step. [Follow these steps to elevate Azure AD Tenant Admin as Azure Tenant Admin](../../role-based-access-control/elevate-access-global-admin.md). It will give the Azure AD admin 'owner' permissions at the root scope. This is needed for all methods described below in this section.

+ | Global | The action groups service decides where to store the action group. The action group is persisted in at least two regions to ensure regional resiliency. Processing of actions may be done in any [geographic region](https://azure.microsoft.com/explore/global-infrastructure/geographies/#overview).<br></br>Voice, SMS and email actions performed as the result of [service health alerts](../../service-health/alerts-activity-log-service-notifications-portal.md) are resilient to Azure live-site-incidents. |

+ | Regional | The action group is stored within the selected region. The action group is [zone-redundant](../../availability-zones/az-region.md#highly-available-services). Processing of actions is performed within the region.</br></br>Use this option if you want to ensure that the processing of your action group is performed within a specific [geographic boundary](https://azure.microsoft.com/explore/global-infrastructure/geographies/#overview). |

+- Learn how to [configure alerts whenever a Service Health notification is posted](../../service-health/alerts-activity-log-service-notifications-portal.md).

+ > - If you currently store Application Insights data for longer than the default 90 days and want to retain this longer retention period after migration, adjust your [workspace retention settings](../logs/data-retention-archive.md?tabs=portal-1%2cportal-2#set-retention-and-archive-policy-by-table) from the default 90 days to the desired longer retention period.

+* [Write Log Analytics queries](../logs/log-query-overview.md)

+> * The Application Insights user can't have access to both workspaces. This can be done by setting the Log Analytics [Access control mode](../logs/log-analytics-workspace-overview.md#permissions) to **Requires workspace permissions** and ensuring through [Azure role-based access control (Azure RBAC)](./resources-roles-access-control.md) that the user only has access to the Log Analytics workspace the Application Insights resource is based on.

+[roles]: ./resources-roles-access-control.md

+- [Autoscale flapping](./autoscale-flapping.md)

+- [Create an Activity Log Alert to monitor all failed autoscale scale in/scale out operations on your subscription](https://github.com/Azure/azure-quickstart-templates/tree/master/demos/monitor-autoscale-failed-alert)

+* [Overview of common autoscale patterns](./autoscale-common-scale-patterns.md)

+* [Automatically scale a virtual machine scale](../../virtual-machine-scale-sets/tutorial-autoscale-powershell.md)

+* [Use autoscale actions to send email and webhook alert notifications](./autoscale-webhook-email.md)

+> [Availability sets](/archive/blogs/kaevans/autoscaling-azurevirtual-machines) are an older scaling feature for virtual machines with limited support. We recommend migrating to [virtual machine scale sets](../../virtual-machine-scale-sets/overview.md) for faster and more reliable autoscale support.

+Use your own custom metrics that your application generates. Configure your application to send metrics to [Application Insights](../app/app-insights-overview.md) so you can use those metrics decide when to scale.

+ * Start an [Azure Automation runbook](../../automation/overview.md).

+ * Call an [Azure Function](../../azure-functions/functions-overview.md).

+ * Trigger an [Azure Logic App](../../logic-apps/logic-apps-overview.md).

+User@aksuser:~$ kubectl get deployment ama-logs-rs -n=kube-system

+|AvailableStorage|No|(deprecated) Available Storage|Bytes|Total|"Available Storage" will be removed from Azure Monitor at the end of September 2023. Azure Cosmos DB collection storage size is now unlimited. The only restriction is that the storage size for each logical partition key is 20GB. You can enable PartitionKeyStatistics in Diagnostic Log to know the storage consumption for top partition keys. For more information, see [Azure Cosmos DB service quotas](../../cosmos-db/concepts-limits.md). After deprecation, the remaining alert rules still defined on the deprecated metric will be automatically disabled post the deprecation date.|CollectionName, DatabaseName, Region|

+- [Export metrics to storage, Event Hub, or Log Analytics](../essentials/platform-logs-overview.md)

+description: Learn how to configure a table for Basic Logs in Azure Monitor.

+Setting a table's [log data plan](log-analytics-workspace-overview.md#log-data-plans) to **Basic Logs** lets you save on the cost of storing high-volume verbose logs you use for debugging, troubleshooting, and auditing, but not for analytics and alerts. This article describes how to configure Basic Logs for a particular table in your Log Analytics workspace.

+> You can switch a table's plan once a week. The Basic Logs feature isn't available for workspaces in [legacy pricing tiers](cost-logs.md#legacy-pricing-tiers).

+By default, all tables in your Log Analytics workspace are Analytics tables, and they're available for query and alerts. You can currently configure the following tables for Basic Logs:

+- Custom tables: All custom tables created with or migrated to the [data collection rule (DCR)-based logs ingestion API.](logs-ingestion-api-overview.md)

+- [ContainerLogV2](/azure/azure-monitor/reference/tables/containerlogv2): Used in [Container insights](../containers/container-insights-overview.md) and includes verbose text-based log records.

+- [AppTraces](/azure/azure-monitor/reference/tables/apptraces): Freeform Application Insights traces.

+- [ContainerAppConsoleLogs](/azure/azure-monitor/reference/tables/ContainerAppConsoleLogs): Logs generated by Azure Container Apps, within a Container Apps environment.

+> Tables created with the [Data Collector API](data-collector-api.md) don't support Basic Logs.

+ The **Tables** screen lists all the tables in the workspace.

+ :::image type="content" source="media/basic-logs-configure/log-analytics-table-configuration.png" lightbox="media/basic-logs-configure/log-analytics-table-configuration.png" alt-text="Screenshot that shows the Manage table button for one of the tables in a workspace.":::

+ :::image type="content" source="media/basic-logs-configure/log-analytics-configure-table-plan.png" lightbox="media/basic-logs-configure/log-analytics-configure-table-plan.png" alt-text="Screenshot that shows the Table plan dropdown on the table configuration screen.":::

+> Use the bearer token for authentication. Learn more about [using bearer tokens](https://social.technet.microsoft.com/wiki/contents/articles/51140.azure-rest-management-api-the-quickest-way-to-get-your-bearer-token.aspx).

+|properties.plan | string | The table plan. Possible values are `Analytics` and `Basic`.|

+Container insights uses `ContainerLog` by default. To switch to using `ContainerLogV2` for Container insights, [enable the ContainerLogV2 schema](../containers/container-insights-logging-v2.md) before you convert the table to Basic Logs.

+This sample is the response for a table changed to Basic Logs:

+To check table configuration in the Azure portal, you can open the table configuration screen, as described in [Set table configuration](#set-table-configuration).

+Alternatively:

+1. From the **Azure Monitor** menu, select **Logs** and select your workspace for the [scope](scope.md). See the [Log Analytics tutorial](log-analytics-tutorial.md#view-table-information) for a walkthrough.

+1. Open the **Tables** tab, which lists all tables in the workspace.

+ Basic Logs tables have a unique icon:

+ :::image type="content" source="media/basic-logs-configure/table-icon.png" alt-text="Screenshot that shows the Basic Logs table icon in the table list." lightbox="media/basic-logs-configure/table-icon.png":::

+ :::image type="content" source="media/basic-logs-configure/table-info.png" alt-text="Screenshot that shows the Basic Logs table indicator in the table details." lightbox="media/basic-logs-configure/table-info.png":::

+**Response body**

+|properties.plan | string | The table plan. Either `Analytics` or `Basic`. |

+|properties.retentionInDays | integer | The table's data retention in days. In `Basic Logs`, the value is 8 days, fixed. In `Analytics Logs`, the value is between 7 and 730 days.|

+|properties.totalRetentionInDays | integer | The table's data retention that also includes the archive period.|

+|properties.lastPlanModifiedDate|String|Last time when the plan was set for this table. Null if no change was ever done from the default settings (read-only).

+**Sample request**

+**Sample response**

+## Retain and archive Basic Logs

+Basic Logs tables retain data for eight days. When you change an existing table's plan to Basic Logs, Azure archives data that's more than eight days old but still within the table's original retention period.

+- [Learn more about the different log plans](log-analytics-workspace-overview.md#log-data-plans)

+- [Query data in Basic Logs](basic-logs-query.md)

+The most significant charges for most Azure Monitor implementations will typically be ingestion and retention of data in your Log Analytics workspaces. Several features in Azure Monitor don't have a direct cost but add to the workspace data that's collected. This article describes how data charges are calculated for your Log Analytics workspaces and Application Insights resources and the different configuration options that affect your costs.

+The default pricing for Log Analytics is a pay-as-you-go model that's based on ingested data volume and data retention. Each Log Analytics workspace is charged as a separate service and contributes to the bill for your Azure subscription. [Pricing for Log Analytics](https://azure.microsoft.com/pricing/details/monitor/) is set regionally. The amount of data ingestion can be considerable, depending on:

+- The set of management solutions enabled and their configuration.

+- The number and type of monitored resources.

+- The types of data collected from each monitored resource.

+Data volume is measured as the size of the data that will be stored in GB (10^9 bytes). The data size of a single record is calculated from a string representation of the columns that are stored in the Log Analytics workspace for that record. It doesn't matter whether the data is sent from an agent or added during the ingestion process. This calculation includes any custom columns added by the [logs ingestion API](logs-ingestion-api-overview.md), [transformations](../essentials/data-collection-transformations.md) or [custom fields](custom-fields.md) that are added as data is collected and then stored in the workspace.

+>The billable data volume calculation is generally substantially smaller than the size of the entire incoming JSON-packaged event. On average, across all event types, the billed size is around 25 percent less than the incoming data size. It can be up to 50 percent for small events. The percentage includes the effect of the standard columns excluded from billing. It's essential to understand this calculation of billed data size when you estimate costs and compare other pricing models.

+The following [standard columns](log-standard-columns.md) are common to all tables and are excluded in the calculation of the record size. All other columns stored in Log Analytics are included in the calculation of the record size. The standard columns are:

+Some tables are free from data ingestion charges altogether, including [AzureActivity](/azure/azure-monitor/reference/tables/azureactivity), [Heartbeat](/azure/azure-monitor/reference/tables/heartbeat), [Usage](/azure/azure-monitor/reference/tables/usage), and [Operation](/azure/azure-monitor/reference/tables/operation). This information will always be indicated by the [_IsBillable](log-standard-columns.md#_isbillable) column, which indicates whether a record was excluded from billing for data ingestion.

+Some solutions have more specific policies about free data ingestion. For example, [Azure Migrate](https://azure.microsoft.com/pricing/details/azure-migrate/) makes dependency visualization data free for the first 180 days of a Server Assessment. Services such as [Microsoft Defender for Cloud](https://azure.microsoft.com/pricing/details/azure-defender/), [Microsoft Sentinel](https://azure.microsoft.com/pricing/details/azure-sentinel/), and [configuration management](https://azure.microsoft.com/pricing/details/automation/) have their own pricing models.

+## Commitment tiers

+In addition to the pay-as-you-go model, Log Analytics has *commitment tiers*, which can save you as much as 30 percent compared to the pay-as-you-go price. With commitment tier pricing, you can commit to buy data ingestion for a workspace, starting at 100 GB per day, at a lower price than pay-as-you-go pricing. Any usage above the commitment level (overage) is billed at that same price per GB as provided by the current commitment tier. The commitment tiers have a 31-day commitment period from the time a commitment tier is selected.

+- During the commitment period, you can change to a higher commitment tier, which restarts the 31-day commitment period. You can't move back to pay-as-you-go or to a lower commitment tier until after you finish the commitment period.

+- At the end of the commitment period, the workspace retains the selected commitment tier, and the workspace can be moved to pay-as-you-go or to a different commitment tier at any time.

+Billing for the commitment tiers is done per workspace on a daily basis. If the workspace is part of a [dedicated cluster](#dedicated-clusters), the billing is done for the cluster. See the following "Dedicated clusters" section. For a list of the commitment tiers and their prices, see [Azure Monitor pricing](https://azure.microsoft.com/pricing/details/monitor/).

+Azure Commitment Discounts, such as discounts received from [Microsoft Enterprise Agreements](https://www.microsoft.com/licensing/licensing-programs/enterprise), are applied to Azure Monitor Logs commitment-tier pricing just as they are to pay-as-you-go pricing. Discounts are applied whether the usage is being billed per workspace or per dedicated cluster.

+> The **Usage and estimated costs** menu item for each Log Analytics workspace shows an estimate of your monthly charges at each commitment level. Review this information periodically to determine if you can reduce your charges by moving to another tier. For information on this view, see [Usage and estimated costs](../usage-estimated-costs.md#usage-and-estimated-costs).

+An [Azure Monitor Logs dedicated cluster](logs-dedicated-clusters.md) is a collection of workspaces in a single managed Azure Data Explorer cluster. Dedicated clusters support advanced features, such as [customer-managed keys](customer-managed-keys.md), and use the same commitment-tier pricing model as workspaces, although they must have a commitment level of at least 500 GB per day. Any usage above the commitment level (overage) is billed at that same price per GB as provided by the current commitment tier. There's no pay-as-you-go option for clusters.

+The cluster commitment tier has a 31-day commitment period after the commitment level is increased. During the commitment period, the commitment tier level can't be reduced, but it can be increased at any time. When workspaces are associated to a cluster, the data ingestion billing for those workspaces is done at the cluster level by using the configured commitment tier level.

+There are two modes of billing for a cluster that you specify when you create the cluster:

+- **Cluster (default)**: Billing for ingested data is done at the cluster level. The ingested data quantities from each workspace associated to a cluster are aggregated to calculate the daily bill for the cluster. Per-node allocations from [Microsoft Defender for Cloud](../../security-center/index.yml) are applied at the workspace level prior to this aggregation of data across all workspaces in the cluster.

+- **Workspaces**: Commitment tier costs for your cluster are attributed proportionately to the workspaces in the cluster, by each workspace's data ingestion volume (after accounting for per-node allocations from [Microsoft Defender for Cloud](../../security-center/index.yml) for each workspace).<br><br>If the total data volume ingested into a cluster for a day is less than the commitment tier, each workspace is billed for its ingested data at the effective per-GB commitment tier rate by billing them a fraction of the commitment tier. The unused part of the commitment tier is then billed to the cluster resource.<br><br>If the total data volume ingested into a cluster for a day is more than the commitment tier, each workspace is billed for a fraction of the commitment tier, based on its fraction of the ingested data that day and each workspace for a fraction of the ingested data above the commitment tier. If the total data volume ingested into a workspace for a day is above the commitment tier, nothing is billed to the cluster resource.

+When you link workspaces to a cluster, the pricing tier is changed to cluster, and ingestion is billed based on the cluster's commitment tier. Workspaces associated to a cluster no longer have their own pricing tier. Workspaces can be unlinked from a cluster at any time, and the pricing tier can be changed to per GB.

+If your linked workspace is using the legacy Per Node pricing tier, it will be billed based on data ingested against the cluster's commitment tier, and no longer Per Node. Per-node data allocations from Microsoft Defender for Cloud will continue to be applied.

+For more information on how to create a dedicated cluster and specify its billing type, see [Create a dedicated cluster](logs-dedicated-clusters.md#create-a-dedicated-cluster).

+You can configure certain tables in a Log Analytics workspace to use [Basic Logs](basic-logs-configure.md). Data in these tables has a significantly reduced ingestion charge and a limited retention period. There's a charge to search against these tables. Basic Logs are intended for high-volume verbose logs you use for debugging, troubleshooting, and auditing, but not for analytics and alerts.

+The charge for searching against Basic Logs is based on the GB of data scanned in performing the search.

+For more information on Basic Logs, including how to configure them and query their data, see [Configure Basic Logs in Azure Monitor](basic-logs-configure.md).

+In addition to data ingestion, there's a charge for the retention of data in each Log Analytics workspace. You can set the retention period for the entire workspace or for each table. After this period, the data is either removed or archived. Archived logs have a reduced retention charge, and there's a charge to search against them. Use archived logs to reduce your costs for data that you must store for compliance or occasional investigation.

+For more information on data retention and archiving, including how to configure these settings and access archived data, see [Configure data retention and archive policies in Azure Monitor Logs](data-retention-archive.md).

+Searching against archived logs uses [search jobs](search-jobs.md). Search jobs are asynchronous queries that fetch records into a new search table within your workspace for further analytics. Search jobs are billed by the number of GB of data scanned on each day that's accessed to perform the search.

+For situations in which older or archived logs must be intensively queried with the full analytic query capabilities, the [data restore](restore.md) feature is a powerful tool. The restore operation makes a specific time range of data in a table available in the hot cache for high-performance queries. You can later dismiss the data when you're finished. Log data restore is billed by the amount of data restored, and by the time the restore is kept active. The minimal values billed for any data restore are 2 TB and 12 hours. Data restored of more than 2 TB and/or more than 12 hours in duration is billed on a pro-rated basis.

+[Data export](logs-data-export.md) in a Log Analytics workspace lets you continuously export data per selected tables in your workspace to an Azure Storage account or Azure Event Hubs as it arrives to an Azure Monitor pipeline. Charges for the use of data export are based on the amount of data exported. The size of data exported is the number of bytes in the exported JSON-formatted data.

+## Application Insights billing

+Because [workspace-based Application Insights resources](../app/create-workspace-resource.md) store their data in a Log Analytics workspace, the billing for data ingestion and retention is done by the workspace where the Application Insights data is located. For this reason, you can use all options of the Log Analytics pricing model, including [commitment tiers](#commitment-tiers), along with pay-as-you-go.

+Data ingestion and data retention for a [classic Application Insights resource](../app/create-new-resource.md) follow the same pay-as-you-go pricing as workspace-based resources, but they can't use commitment tiers.

+Telemetry from ping tests and multi-step tests is charged the same as data usage for other telemetry from your app. Use of web tests and enabling alerting on custom metric dimensions is still reported through Application Insights. There's no data volume charge for using [Live Metrics Stream](../app/live-stream.md).

+For more information about legacy tiers that are available to early adopters of Application Insights, see [Application Insights legacy enterprise (per node) pricing tier](../app/legacy-pricing.md).

+When Microsoft Sentinel is enabled in a Log Analytics workspace, all data collected in that workspace is subject to Microsoft Sentinel charges along with Log Analytics charges. For this reason, you'll often separate your security and operational data in different workspaces so that you don't incur [Microsoft Sentinel charges](../../sentinel/billing.md) for operational data.

+In some scenarios, combining this data can result in cost savings. Typically, this situation occurs when you aren't collecting enough security and operational data for each to reach a commitment tier on their own, but the combined data is enough to reach a commitment tier. For more information and a sample cost calculation, see the section "Combining your SOC and non-SOC data" in [Design your Microsoft Sentinel workspace architecture](../../sentinel/design-your-workspace-architecture.md#decision-tree).

+[Microsoft Defender for Servers (part of Defender for Cloud)](../../security-center/index.yml) [bills by the number of monitored services](https://azure.microsoft.com/pricing/details/azure-defender/). It provides 500 MB per server per day of data allocation that's applied to the following subset of [security data types](/azure/azure-monitor/reference/tables/tables-category#security):

+- [Update](/azure/azure-monitor/reference/tables/update) and [UpdateSummary](/azure/azure-monitor/reference/tables/updatesummary) when the Update Management solution isn't running in the workspace or solution targeting is enabled. See [What data types are included in the 500-MB data daily allowance?](../../defender-for-cloud/enhanced-security-features-overview.md#what-data-types-are-included-in-the-500-mb-data-daily-allowance).

+Subscriptions that contained a Log Analytics workspace or Application Insights resource on April 2, 2018, or are linked to an Enterprise Agreement that started before February 1, 2019, and is still active, will continue to have access to use the following legacy pricing tiers:

+- Per Node (Operations Management Suite [OMS])

+Access to the legacy Free Trial pricing tier was limited on July 1, 2022.

+Workspaces in the Free Trial pricing tier will have daily data ingestion limited to 500 MB (except for security data types collected by [Microsoft Defender for Cloud](../../security-center/index.yml)). The data retention is limited to seven days. The Free Trial pricing tier is intended only for evaluation purposes. No SLA is provided for the Free Trial tier.

+> Creating new workspaces in, or moving existing workspaces into, the legacy Free Trial pricing tier was possible only until July 1, 2022.

+Usage on the Standalone pricing tier is billed by the ingested data volume. It's reported in the **Log Analytics** service and the meter is named "Data Analyzed." Workspaces in the Standalone pricing tier have user-configurable retention from 30 to 730 days. Workspaces in the Standalone pricing tier don't support the use of [Basic Logs](basic-logs-configure.md).

+The Per Node pricing tier charges per monitored VM (node) on an hour granularity. For each monitored node, the workspace is allocated 500 MB of data per day that's not billed. This allocation is calculated with hourly granularity and is aggregated at the workspace level each day. Data ingested above the aggregate daily data allocation is billed per GB as data overage.

+On your bill, the service will be **Insight and Analytics** for Log Analytics usage if the workspace is in the Per Node pricing tier. Workspaces in the Per Node pricing tier have user-configurable retention from 30 to 730 days. Workspaces in the Per Node pricing tier don't support the use of [Basic Logs](basic-logs-configure.md). Usage is reported on three meters:

+- **Node**: The usage for the number of monitored nodes (VMs) in units of node months.

+- **Data Overage per Node**: The number of GB of data ingested in excess of the aggregated data allocation.

+- **Data Included per Node**: The amount of ingested data that was covered by the aggregated data allocation. This meter is also used when the workspace is in all pricing tiers to show the amount of data covered by Microsoft Defender for Cloud.

+> If your workspace has access to the **Per Node** pricing tier but you're wondering whether it would cost less in a pay-as-you-go tier, [use the following query](#evaluate-the-legacy-per-node-pricing-tier) for a recommendation.

+### Standard and Premium pricing tiers

+Workspaces created before April 2016 can continue to use the **Standard** and **Premium** pricing tiers that have fixed data retention of 30 days and 365 days, respectively. New workspaces can't be created in the **Standard** or **Premium** pricing tiers. If a workspace is moved out of these tiers, it can't be moved back. Workspaces in these pricing tiers don't support the use of [Basic Logs](basic-logs-configure.md). Data ingestion meters on your Azure bill for these legacy tiers are called "Data Analyzed."

+### Microsoft Defender for Cloud with legacy pricing tiers

+The following considerations pertain to legacy Log Analytics tiers and how usage is billed for [Microsoft Defender for Cloud](../../security-center/index.yml):

+- If the workspace is in the legacy Per Node tier, Microsoft Defender for Cloud is billed using the current [Microsoft Defender for Cloud node-based pricing model](https://azure.microsoft.com/pricing/details/security-center/).

+More information on pricing tier limitations is available at [Azure subscription and service limits, quotas, and constraints](../../azure-resource-manager/management/azure-subscription-service-limits.md#log-analytics-workspaces).

+None of the legacy pricing tiers have regional-based pricing.

+> To use the entitlements that come from purchasing OMS E1 Suite, OMS E2 Suite, or OMS Add-On for System Center, choose the Log Analytics Per Node pricing tier.

+It's often difficult to determine whether workspaces with access to the legacy Per Node pricing tier are better off in that tier or in a current pay-as-you-go or commitment tier. You need to understand the trade-off between the fixed cost per monitored node in the Per Node pricing tier and its included data allocation of 500 MB per node per day and the cost of paying for ingested data in the pay-as-you-go (per GB) tier.

+Use the following query to make a recommendation for the optimal pricing tier based on a workspace's usage patterns. This query looks at the monitored nodes and data ingested into a workspace in the last seven days. For each day, it evaluates which pricing tier would have been optimal. To use the query, you must specify:

+- Whether the workspace is using Microsoft Defender for Cloud by setting `workspaceHasSecurityCenter` to `true` or `false`.

+- Specify the number of days to look back and analyze by setting `daysToEvaluate`. This option is useful if the query is taking too long trying to look at seven days of data.

+// For pay-as-you-go (per-GB) and commitment tier pricing details, see https://azure.microsoft.com/pricing/details/monitor/.

+let PerGBPrice = 2.30; // Enter the pay-as-you-go price for your workspace's region (from https://azure.microsoft.com/pricing/details/monitor/)

+This query isn't an exact replication of how usage is calculated, but it provides pricing tier recommendations in most cases.

+> To use the entitlements that come from purchasing OMS E1 Suite, OMS E2 Suite, or OMS Add-On for System Center, choose the Log Analytics Per Node pricing tier.

+- See [Analyze usage in Log Analytics workspace](analyze-usage.md) for details on analyzing the data in your workspace to determine the source of any higher-than-expected usage and opportunities to reduce your amount of data collected.

+- See [Set daily cap on Log Analytics workspace](daily-cap.md) to control your costs by configuring a maximum volume that might be ingested in a workspace each day.

+ Title: Configure data retention and archive in Azure Monitor Logs (preview)

+Retention policies define when to remove or archive data in a [Log Analytics workspace](log-analytics-workspace-overview.md). Archiving lets you keep older, less used data in your workspace at a reduced cost.

+During the interactive retention period, data is available for monitoring, troubleshooting, and analytics. When you no longer use the logs, but still need to keep the data for compliance or occasional investigation, archive the logs to save costs.

+Archived data stays in the same table, alongside the data that's available for interactive queries. When you set a total retention period that's longer than the interactive retention period, Log Analytics automatically archives the relevant data immediately at the end of the retention period.

+If you change the archive settings on a table with existing data, the relevant data in the table is also affected immediately. For example, you might have an existing table with 30 days of interactive retention and no archive period. You decide to change the retention policy to eight days of interactive retention and one year total retention. Log Analytics immediately archives any data that's older than eight days.

+You can access archived data by [running a search job](search-jobs.md) or [restoring archived logs](restore.md).

+You can set the workspace default retention policy in the Azure portal to 30, 31, 60, 90, 120, 180, 270, 365, 550, and 730 days. You can set a different policy for specific tables by [configuring the retention and archive policy at the table level](#set-retention-and-archive-policy-by-table). If you're on the *free* tier, you'll need to upgrade to the paid tier to change the data retention period.

+1. From the **Log Analytics workspaces** menu in the Azure portal, select your workspace.

+1. Select **Usage and estimated costs** in the left pane.

+1. Select **Data Retention** at the top of the page.

+ :::image type="content" source="media/manage-cost-storage/manage-cost-change-retention-01.png" alt-text="Screenshot that shows changing the workspace data retention setting.":::

+1. Move the slider to increase or decrease the number of days, and then select **OK**.

+You can keep data in interactive retention between 4 and 730 days. You can set the archive period for a total retention time of up to 2,556 days (seven years).

+1. From the **Log Analytics workspaces** menu, select **Tables**.

+ The **Tables** screen lists all the tables in the workspace.

+ :::image type="content" source="media/basic-logs-configure/log-analytics-table-configuration.png" lightbox="media/basic-logs-configure/log-analytics-table-configuration.png" alt-text="Screenshot that shows the Manage table button for one of the tables in a workspace.":::

+1. Configure the retention and archive duration in the **Data retention settings** section of the table configuration screen.

+ :::image type="content" source="media/data-retention-configure/log-analytics-configure-table-retention-archive.png" lightbox="media/data-retention-configure/log-analytics-configure-table-retention-archive.png" alt-text="Screenshot that shows the data retention settings on the table configuration screen.":::

+To set the retention and archive duration for a table, call the **Tables - Update** API:

+You can use either PUT or PATCH, with the following difference:

+- The **PUT** API sets `retentionInDays` and `totalRetentionInDays` to the default value if you don't set non-null values.

+- The **PATCH** API doesn't change the `retentionInDays` or `totalRetentionInDays` values if you don't specify values.

+|properties.retentionInDays | integer | The table's data retention in days. This value can be between 4 and 730. <br/>Setting this property to null will default to the workspace retention. For a Basic Logs table, the value is always 8. |

+|properties.totalRetentionInDays | integer | The table's total data retention including archive period. This value can be between 4 and 730; or 1095, 1460, 1826, 2191, or 2556. Set this property to null if you don't want to archive data. |

+This example sets the table's interactive retention to 30 days, and the total retention to two years, which means that the archive duration is 23 months:

+The **Tables** screen shows the interactive retention and archive period for all the tables in the workspace.

+To get all table-level retention policies in your workspace, don't set a table name.

+For example:

+When you shorten an existing retention policy, it takes several days for Azure Monitor to remove data that you no longer want to keep.

+If you set the data retention policy to 30 days, you can purge older data immediately by using the `immediatePurgeDataOn30Days` parameter in Azure Resource Manager. The purge functionality is useful when you need to remove personal data immediately. The immediate purge functionality isn't available through the Azure portal.

+Workspaces with a 30-day retention policy might keep data for 31 days if you don't set the `immediatePurgeDataOn30Days` parameter.

+You can also purge data from a workspace by using the [purge feature](personal-data-mgmt.md#exporting-and-deleting-personal-data), which removes personal data. You can't purge data from archived logs.

+The Log Analytics [Purge API](/rest/api/loganalytics/workspacepurge/purge) doesn't affect retention billing. To lower retention costs, *decrease the retention period for the workspace or for specific tables*.

+By default, two data types, `Usage` and `AzureActivity`, keep data for at least 90 days at no charge. When you increase the workspace retention to more than 90 days, you also increase the retention of these data types. You'll be charged for retaining this data beyond the 90-day period. These tables are also free from data ingestion charges.

+Tables related to Application Insights resources also keep data for 90 days at no charge. You can adjust the retention policy of each of these tables individually:

+- `AppPerformanceCounters`

+## Set data retention for classic Application Insights resources

+Workspace-based Application Insights resources store data in a Log Analytics workspace, so it's included in the data retention and archive settings for the workspace. Classic Application Insights resources have separate retention settings.

+The default retention for Application Insights resources is 90 days. You can select different retention periods for each Application Insights resource. The full set of available retention periods is 30, 60, 90, 120, 180, 270, 365, 550, or 730 days.

+To change the retention, from your Application Insights resource, go to the **Usage and estimated costs** page and select the **Data retention** option.

+The retention can also be [set programmatically with PowerShell](../app/powershell.md#set-the-data-retention) by using the `retentionInDays` parameter. If you set the data retention to 30 days, you can trigger an immediate purge of older data by using the `immediatePurgeDataOn30Days` parameter. This approach might be useful for compliance-related scenarios. This purge functionality is only exposed via Azure Resource Manager and should be used with extreme care. The daily reset time for the data volume cap can be configured by using Azure Resource Manager to set the `dailyQuotaResetTime` parameter.

+- [Learn more about Log Analytics workspaces and data retention and archive](log-analytics-workspace-overview.md)

+- [Create a search job to retrieve archive data matching particular criteria](search-jobs.md)

+- [Restore archive data within a particular time range](restore.md)

+ Title: Logs Ingestion API in Azure Monitor (preview)

+description: Send data to a Log Analytics workspace by using a REST API.

+# Logs Ingestion API in Azure Monitor (preview)

+The Logs Ingestion API in Azure Monitor lets you send data to a Log Analytics workspace from any REST API client. By using this API, you can send data from almost any source to [supported built-in tables](#supported-tables) or to custom tables that you create. You can even extend the schema of built-in tables with custom columns.

+> [!NOTE]

+> The Logs Ingestion API was previously referred to as the custom logs API.

+Your application sends data to a [data collection endpoint (DCE)](../essentials/data-collection-endpoint-overview.md), which is a unique connection point for your subscription. The payload of your API call includes the source data formatted in JSON. The call:

+- Specifies a [data collection rule (DCR)](../essentials/data-collection-rule-overview.md) that understands the format of the source data.

+- Potentially filters and transforms it for the target table.

+- Directs it to a specific table in a specific workspace.

+You can modify the target table and workspace by modifying the DCR without any change to the REST API call or source data.

+> To migrate solutions from the [Data Collector API](data-collector-api.md), see [Migrate from Data Collector API and custom fields-enabled tables to DCR-based custom logs](custom-logs-migrate.md).

+The following tables are supported.

+The Logs Ingestion API can send data to any custom table that you create and to certain built-in tables in your Log Analytics workspace. The target table must exist before you can send data to it.

+The Logs Ingestion API can send data to the following built-in tables. Other tables might be added to this list as support for them is implemented:

+Tables have the following limitations:

+* Custom tables must have the `_CL` suffix.

+* Column names can consist of alphanumeric characters and the characters `_` and `-`. They must start with a letter.

+* Columns extended on top of built-in tables must have the suffix `_CF`. Columns in a custom table don't need this suffix.

+Authentication for the Logs Ingestion API is performed at the DCE, which uses standard Azure Resource Manager authentication. A common strategy is to use an application ID and application key as described in [Tutorial: Add ingestion-time transformation to Azure Monitor Logs (preview)](tutorial-logs-ingestion-portal.md).

+The source data sent by your application is formatted in JSON and must match the structure expected by the DCR. It doesn't necessarily need to match the structure of the target table because the DCR can include a [transformation](../essentials//data-collection-transformations.md) to convert the data to match the table's structure.

+The DCR must understand the structure of the input data and the structure of the target table. If the two don't match, it can use a [transformation](../essentials/data-collection-transformations.md) to convert the source data to match the target table. You can also use the transformation to filter source data and perform any other calculations or conversions.

+## Send data

+To send data to Azure Monitor with the Logs Ingestion API, make a POST call to the DCE over HTTP. Details of the call are described in the following sections.

+> You can retrieve the immutable ID from the JSON view of the DCR. For more information, see [Collect information from DCR](tutorial-logs-ingestion-portal.md#collect-information-from-dcr).

+| Authorization | Yes | Bearer (bearer token obtained through the client credentials flow) | |

+| Content-Encoding | No | `gzip` | Use the gzip compression scheme for performance optimization. |

+For sample data and an API call using the Logs Ingestion API, see either [Send custom logs to Azure Monitor Logs using the Azure portal (preview)](tutorial-logs-ingestion-portal.md) or [Send custom logs to Azure Monitor Logs using Resource Manager templates](tutorial-logs-ingestion-api.md).

+For limits related to the Logs Ingestion API, see [Azure Monitor service limits](../service-limits.md#logs-ingestion-api).

+- [Walk through a tutorial sending custom logs using the Azure portal](tutorial-logs-ingestion-portal.md)

+- [Walk through a tutorial sending custom logs using Resource Manager templates and REST API](tutorial-logs-ingestion-api.md)

+To create a [custom role](../../role-based-access-control/custom-roles.md) that lets specific users or groups read data from specific tables in a workspace:

+description: The article describes how to monitor the health of your Log Analytics workspace by using data in the Operation table.

+# Monitor health of a Log Analytics workspace in Azure Monitor

+To maintain the performance and availability of your Log Analytics workspace in Azure Monitor, you need to be able to proactively detect any issues that arise. This article describes how to monitor the health of your Log Analytics workspace by using data in the [Operation](/azure/azure-monitor/reference/tables/operation) table. This table is included in every Log Analytics workspace. It contains error messages and warnings that occur in your workspace. We recommend that you create alerts for issues with the level of Warning and Error.

+Azure Monitor Logs sends information on any issues to the [Operation](/azure/azure-monitor/reference/tables/operation) table in the workspace where the issue occurred. The `_LogOperation` system function is based on the **Operation** table and provides a simplified set of information for analysis and alerting.

+The `_LogOperation` function returns the columns in the following table.

+| Category | Operation category group. Can be used to filter on types of operations and help create more precise system auditing and alerts. See the following section for a list of categories. |

+| Operation | Description of the operation type. The operation can indicate that one of the Log Analytics limits was reached, a back-end process related issue, or any other service message. |

+| Level | Severity level of the issue:<br>- Info: No specific attention needed.<br>- Warning: Process wasn't completed as expected, and attention is needed.<br>- Error: Process failed, and attention is needed.

+The following table describes the categories from the `_LogOperation` function.

+| Data collection | Operations related to data collection processes. |

+| Solution targeting | Operation of type `ConfigurationScope` was processed. |

+Ingestion operations are issues that occurred during data ingestion and include notification about reaching the Log Analytics workspace limits. Error conditions in this category might suggest data loss, so they're important to monitor. For service limits for Log Analytics workspaces, see [Azure Monitor service limits](../service-limits.md#log-analytics-workspaces).

+#### Operation: Data collection stopped

+In the past seven days, logs collection reached the daily set limit. The limit is set either as the workspace is set to **Free tier** or the daily collection limit was configured for this workspace.

+After your data collection reaches the set limit, it automatically stops for the day and will resume only during the next collection day.

+Recommended actions:

+* Check the `_LogOperation` table for collection stopped and collection resumed events:</br>

+* [Create an alert](daily-cap.md#alert-when-daily-cap-is-reached) on the "Data collection stopped" Operation event. This alert notifies you when the collection limit is reached.

+* Data collected after the daily collection limit is reached will be lost. Use the **Workspace insights** pane to review usage rates from each source. Or you can decide to [manage your maximum daily data volume](daily-cap.md) or [change the pricing tier](cost-logs.md#commitment-tiers) to one that suits your collection rates pattern.

+* The data collection rate is calculated per day and resets at the start of the next day. You can also monitor a collection resume event by [creating an alert](./daily-cap.md#alert-when-daily-cap-is-reached) on the "Data collection resumed" Operation event.

+"The data ingestion volume rate crossed the threshold in your workspace: {0:0.00} MB per one minute and data has been dropped."

+Recommended actions:

+* Check the `_LogOperation` table for an ingestion rate event:</br>

+`_LogOperation | where TimeGenerated >= ago(7d) | where Category == "Ingestion" | where Operation has "Ingestion rate"`

+ </br>An event is sent to the **Operation** table in the workspace every six hours while the threshold continues to be exceeded.

+* [Create an alert](daily-cap.md#alert-when-daily-cap-is-reached) on the "Data collection stopped" Operation event. This alert notifies you when the limit is reached.

+* Data collected while the ingestion rate reached 100 percent will be dropped and lost. Use the **Workspace insights** pane to review your usage patterns and try to reduce them.</br>

+For more information, see: </br>

+ - [Azure Monitor service limits](../service-limits.md#data-ingestion-volume-rate) </br>

+ - [Analyze usage in Log Analytics workspace](analyze-usage.md)

+"Data of type \<**table name**\> was dropped because number of fields \<**new fields count**\> is above the limit of \<**current field count limit**\> custom fields per data type."

+Recommended action: For custom tables, you can move to [parsing the data](./parse-text.md) in queries.

+"The following fields' values \<**field name**\> of type \<**table name**\> have been trimmed to the max allowed size, \<**field size limit**\> bytes. Please adjust your input accordingly."

+A field larger than the limit size was processed by Azure logs. The field was trimmed to the allowed field limit. We don't recommend sending fields larger than the allowed limit because it results in data loss.

+Recommended actions:

+* If the data is being sent through the HTTP Data Collector API, you need to change your code\script to split the data before it's ingested.

+* For custom logs, collected by a Log Analytics agent, change the logging settings of the application or tool.

+* For any other data type, raise a support case. For more information, see [Azure Monitor service limits](../service-limits.md#data-ingestion-volume-rate).

+The following section provides information on data collection.

+"Access to the subscription was lost. Ensure that the \<**subscription id**\> subscription is in the \<**tenant id**\> Azure Active Directory tenant. If the subscription is transferred to another tenant, there is no impact to the services, but information for the tenant could take up to an hour to propagate."

+In some situations, like moving a subscription to a different tenant, the Azure activity logs might stop flowing into the workspace. In those situations, you need to reconnect the subscription following the process described in this article.

+Recommended actions:

+* If the subscription mentioned in the warning message no longer exists, go to the **Azure Activity log** pane under **Workspace Data Sources**. Select the relevant subscription, and then select the **Disconnect** button.

+* If you no longer have access to the subscription mentioned in the warning message:

+ * Follow the preceding step to disconnect the subscription.

+ * To continue collecting logs from this subscription, contact the subscription owner to fix the permissions and re-enable activity log collection.

+* [Create a diagnostic setting](../essentials/activity-log.md#send-to-log-analytics-workspace) to send the activity log to a Log Analytics workspace.

+The following section provides information on agents.

+"Two successive configuration applications from OMS Settings failed."

+Configuration settings on the portal have changed.

+Recommended action:

+This issue is raised in case there's an issue for the agent to retrieve the new config settings. To mitigate this issue, reinstall the agent.

+Check the `_LogOperation` table for the agent event:</br>

+ `_LogOperation | where TimeGenerated >= ago(6h) | where Category == "Agent" | where Operation == "Linux Agent" | distinct _ResourceId`

+The list will show the resource IDs where the agent has the wrong configuration. To mitigate the issue, reinstall the agents listed.

+Use [log query alerts](../alerts/alerts-log-query.md) in Azure Monitor to be proactively notified when an issue is detected in your Log Analytics workspace. Use a strategy that allows you to respond in a timely manner to issues while minimizing your costs. Your subscription will be charged for each alert rule as listed in [Azure Monitor pricing](https://azure.microsoft.com/pricing/details/monitor/#platform-logs).

+A recommended strategy is to start with two alert rules based on the level of the issue. Use a short frequency such as every 5 minutes for Errors and a longer frequency such as 24 hours for Warnings. Because Errors indicate potential data loss, you want to respond to them quickly to minimize any loss. Warnings typically indicate an issue that doesn't require immediate attention, so you can review them daily.

+Use the process in [Create, view, and manage log alerts by using Azure Monitor](../alerts/alerts-log.md) to create the log alert rules. The following sections describe the details for each rule.

+| `_LogOperation | where Level == "Warning"` | 0 | 1,440 | 1,440 |

+These alert rules will respond the same to all operations with Error or Warning. As you become more familiar with the operations that are generating alerts, you might want to respond differently for particular operations. For example, you might want to send notifications to different people for particular operations.

+To create an alert rule for a specific operation, use a query that includes the **Category** and **Operation** columns.

+The following example creates a Warning alert when the ingestion volume rate has reached 80 percent of the limit:

+The following example creates a Warning alert when the data collection has reached the daily limit:

+Watch this video to see how you can use Azure Workbooks to get insights and visualize your data.

+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5a1su]

+For different options to enable the Change Tracking solution on your virtual machines, see [Enable Change Tracking and Inventory](../../automation/change-tracking/overview.md#enable-change-tracking-and-inventory). This solution includes methods to configure virtual machines at scale. You'll have to [create an Azure Automation account](../../automation/quickstarts/create-azure-automation-account-portal.md) to support the solution.

+* [Learn about alerts using metrics and logs in Azure Monitor](../alerts/alerts-overview.md)

+|[Azure Monitor Agent overview](./agents/agents-overview.md)|Added Azure Monitor Agent support for ARM64-based virtual machines for a number of distributions. <br><br>Azure Monitor Agent and legacy agents don't support machines and appliances that run heavily customized or stripped-down versions of operating system distributions. <br><br>Azure Monitor Agent versions 1.15.2 and higher now support syslog RFC formats, including Cisco Meraki, Cisco ASA, Cisco FTD, Sophos XG, Juniper Networks, Corelight Zeek, CipherTrust, NXLog, McAfee, and Common Event Format (CEF).|

+|[Convert ITSM actions that send events to ServiceNow to secure webhook actions](./alerts/itsm-convert-servicenow-to-webhook.md)|As of September 2022, we're starting the 3-year process of deprecating support of using ITSM actions to send events to ServiceNow. Learn how to convert ITSM actions that send events to ServiceNow to secure webhook actions|

+|[Create a new alert rule](./alerts/alerts-create-new-alert-rule.md)|Added description of all available monitoring services to create a new alert rule and alert processing rules pages. <br><br>Added support for regional processing for metric alert rules that monitor a custom metric with the scope defined as one of the supported regions. <br><br> Clarified that selecting the **Automatically resolve alerts** setting makes log alerts stateful.<|

+|[Upgrade legacy rules management to the current Log Alerts API from legacy Log Analytics Alert API](./alerts/alerts-log-api-switch.md)|The process of moving legacy log alert rules management from the legacy API to the current API is now supported by the government cloud.|

+|[Azure Monitor OpenTelemetry-based auto-instrumentation for Java applications](./app/java-in-process-agent.md)|New OpenTelemetry `@WithSpan` annotation guidance.|

+|[Capture Application Insights custom metrics with .NET and .NET Core](./app/tutorial-asp-net-custom-metrics.md)|Tutorial steps and images have been updated.|

+|[Configuration options - Azure Monitor Application Insights for Java](/azure/azure-monitor/app/java-in-process-agent)|Connection string guidance updated.|

+|[Enable Application Insights for ASP.NET Core applications](./app/tutorial-asp-net-core.md)|Tutorial steps and images have been updated.|

+|[Enable Azure Monitor OpenTelemetry Exporter for .NET, Node.js, and Python applications (preview)](./app/opentelemetry-enable.md)|Our product feedback link at the bottom of each document has been fixed.|

+|[Filter and preprocess telemetry in the Application Insights SDK](./app/api-filtering-sampling.md)|Added sample initializer to control which client IP gets used as part of geo-location mapping.|

+|[Java Profiler for Azure Monitor Application Insights](./app/java-standalone-profiler.md)|Our new Java Profiler was announced at Ignite. Read all about it!|

+|[Release notes for Azure Web App extension for Application Insights](./app/web-app-extension-release-notes.md)|Added release notes for 2.8.44 and 2.8.43.|

+|[Resource Manager template samples for creating Application Insights resources](./app/resource-manager-app-resource.md)|Fixed inaccurate tagging of workspace-based resources as still in Preview.|

+|[Unified cross-component transaction diagnostics](./app/transaction-diagnostics.md)|A complete FAQ section is added to help troubleshoot Azure portal errors, such as "error retrieving data".|

+|[Upgrading from Application Insights Java 2.x SDK](./app/java-standalone-upgrade-from-2x.md)|Additional upgrade guidance added. Java 2.x has been deprecated.|

+|[Using Azure Monitor Application Insights with Spring Boot](./app/java-spring-boot.md)|Configuration options have been updated.|

+|[Autoscale with multiple profiles](./autoscale/autoscale-multiprofile.md)|New article: Using multiple profiles in autoscale with CLI PowerShell and templates.|

+|[Flapping in Autoscale](./autoscale/autoscale-flapping.md)|New Article: Flapping in autoscale.|

+|[Understand Autoscale settings](./autoscale/autoscale-understanding-settings.md)|Clarified how often autoscale runs.|

+|[Troubleshoot Azure Monitor's Change Analysis](./change/change-analysis-troubleshoot.md)|Added section about partial data and how to mitigate to the troubleshooting guide.|

+|[Structure of transformation in Azure Monitor (preview)](./essentials/data-collection-transformations-structure.md)|New KQL functions supported.|

+|[Migrate from Service Map to Azure Monitor VM insights](./vm/vminsights-migrate-from-service-map.md)|Added a new article with guidance for migrating from the Service Map solution to Azure Monitor VM insights.|

+|[Access deprecated Troubleshooting guides in Azure Workbooks](./visualize/workbooks-access-troubleshooting-guide.md)|New article: Access deprecated Troubleshooting guides in Azure Workbooks.|

+| [VM insights guest health (preview)](vm/vminsights-health-overview.md) | Added deprecation statement |

+ Refer to [Naming rules and restrictions for Azure resources](../azure-resource-manager/management/resource-name-rules.md#microsoftnetapp) for naming conventions on volumes. Additionally, you cannot use `default` or `bin` as the volume name.

+ Specify the name for the volume that you are creating.

+ Refer to [Naming rules and restrictions for Azure resources](../azure-resource-manager/management/resource-name-rules.md#microsoftnetapp) for naming conventions on volumes. Additionally, you cannot use `default` or `bin` as the volume name.

+* [Managing SQL Server 2022 T-SQL snapshot backup with Azure NetApp Files snapshots](https://techcommunity.microsoft.com/t5/azure-architecture-blog/managing-sql-server-2022-t-sql-snapshot-backup-with-azure-netapp/ba-p/3654798)

+* [Protecting HANA databases configured with HSR on Azure NetApp Files with AzAcSnap](https://techcommunity.microsoft.com/t5/running-sap-applications-on-the/protecting-hana-databases-configured-with-hsr-on-azure-netapp/ba-p/3654620)

+* The LDAP with extended groups feature supports the dual protocol of both [NFSv3 and SMB] and [NFSv4.1 and SMB] with the Unix security style. See [Configure AD DS LDAP with extended groups for NFS volume access](configure-ldap-extended-groups.md) for more information.

+* If you have large topologies, and you use the Unix security style with a dual-protocol volume or LDAP with extended groups, you should use the **LDAP Search Scope** option on the Active Directory Connections page to avoid "access denied" errors on Linux clients for Azure NetApp Files. See [Configure AD DS LDAP with extended groups for NFS volume access](configure-ldap-extended-groups.md#ldap-search-scope) for more information.

+ Refer to [Naming rules and restrictions for Azure resources](../azure-resource-manager/management/resource-name-rules.md#microsoftnetapp) for naming conventions on volumes. Additionally, you can't use `default` or `bin` as the volume name.

+> The **Allow local NFS users with LDAP** option is part of the **LDAP with extended groups** feature and requires registration. See [Configure AD DS LDAP with extended groups for NFS volume access](configure-ldap-extended-groups.md) for details.

+* [Configure AD DS LDAP over TLS for Azure NetApp Files](configure-ldap-over-tls.md)

+* [Configure AD DS LDAP with extended groups for NFS volume access](configure-ldap-extended-groups.md)

+## Accidental deletion

+If you accidentally delete a resource group or resource, in some situations it might be possible to recover it.

+Some resource types support *soft delete*. You might have to configure soft delete before you can use it. For more information about enabling soft delete, see the documentation for [Azure Key Vault](../../key-vault/general/soft-delete-overview.md), [Azure Backup](../../backup/backup-azure-delete-vault.md), and [Azure Storage](../../storage/blobs/soft-delete-container-overview.md).

+You can also [open an Azure support case](../../azure-portal/supportability/how-to-create-azure-support-request.md). Provide as much detail as you can about the deleted resources, including their resource IDs, types, and resource names, and request that the support engineer check if the resources can be restored.

+> [!NOTE]

+> Recovery of deleted resources is not possible under all circumstances. A support engineer will investigate your scenario and advise you whether it's possible.

+> | netAppAccounts / volumes | NetApp account | 1-64 | Alphanumerics, underscores, and hyphens. <br><br> Start with alphanumeric. <br><br> Volume cannot be named `bin` or `default`. |

+A reverse proxy server can be used in front of Azure SignalR Service. Reverse proxy servers sit in between the clients and the Azure SignalR service and other services can help in various scenarios. For example, reverse proxy servers can load balance different client requests to different backend services, you can usually configure different routing rules for different client requests, and provide seamless user experience for users accessing different backend services. They can also protect your backend servers from common exploits vulnerabilities with centralized protection control. Services such as [Azure Application Gateway](../application-gateway/overview.md), [Azure API Management](../api-management/api-management-key-concepts.md) or [Akamai](https://www.akamai.com) can act as reverse proxy servers.

+- Learn more about [the internals of Azure SignalR](./signalr-concept-internals.md).

+If you need help with Azure Video Indexer, find support [here](../cognitive-services/cognitive-services-support-options.md).

+## View an intro video

+You can view the following short video that discusses how to view and use the featured clothing insight.

+[An intro video](https://www.youtube.com/watch?v=x33fND286eE).

+**America** : East US, East US 2, West US, Central US, South Central US, North Central US, Canada East, Canada Central .

+**Asia** : East Asia, Southeast Asia, Japan East, Japan West.

+The vSAN datastore capacity can be expanded by connecting Azure storage resources such as [Azure NetApp Files volumes as datastores](./attach-azure-netapp-files-to-azure-vmware-solution-hosts.md). Virtual machines can be migrated between vSAN and Azure NetApp Files datastores using storage vMotion.

+Azure NetApp Files is available in [Ultra, Premium and Standard performance tiers](../azure-netapp-files/azure-netapp-files-service-levels.md) to allow for adjusting performance and cost to the requirements of the workloads.

+- [Azure NetApp Files with Azure VMware Solution](netapp-files-with-azure-vmware-solution.md) - You can use Azure NetApp Files to migrate and run the most demanding enterprise file-workloads in the cloud: databases, and general purpose computing applications, with no code changes. Azure NetApp Files volumes can be attached to virtual machines, and as [datastores](./attach-azure-netapp-files-to-azure-vmware-solution-hosts.md) to extend the vSAN datastore capacity without adding more nodes.

+[concepts-identity]: ./concepts-identity.md

+- You'll need an Azure Key Vault to use CMK functionality. If you don't have an Azure Key Vault, you can create one using [Quickstart: Create a key vault using the Azure portal](../key-vault/general/quick-create-portal.md).

+- If you enabled restricted access to key vault, you'll need to allow Microsoft Trusted Services to bypass the Azure Key Vault firewall. Go to [Configure Azure Key Vault networking settings](../key-vault/general/how-to-azure-key-vault-network-security.md?tabs=azure-portal) to learn more.

+ >After firewall rules are in effect, users can only perform Key Vault [data plane](../key-vault/general/security-features.md#privileged-access) operations when their requests originate from allowed VMs or IPv4 address ranges. This also applies to accessing key vault from the Azure portal. This also affects the key vault Picker by Azure VMware Solution. Users may be able to see a list of key vaults, but not list keys, if firewall rules prevent their client machine or user does not have list permission in key vault.

+ To configure the system-assigned identity on Azure VMware Solution private cloud with Azure CLI, call [az-resource-update](/cli/azure/resource?view=azure-cli-latest#az-resource-update) and provide the variable for the private cloud resource ID that you previously retrieved.

+ To configure the key vault access policy with Azure CLI, call [az keyvault set-policy](/cli/azure/keyvault#az-keyvault-set-policy) and provide the variable for the principal ID that you previously retrieved for the managed identity.

+ Learn more about how to [Assign an Azure Key Vault access policy](../key-vault/general/assign-access-policy.md?tabs=azure-portal).

+To configure customer-managed keys for an Azure VMware Solution private cloud with automatic updating of the key version, call [az vmware private-cloud add-cmk-encryption](/cli/azure/vmware/private-cloud?view=azure-cli-latest#az-vmware-private-cloud-add-cmk-encryption). Get the key vault URL and save it to a variable. You'll need this value in the next step to enable CMK.

+Learn about [Azure Key Vault backup and restore](../key-vault/general/backup.md?tabs=azure-cli)

+Learn about [Azure Key Vault recovery](../key-vault/general/key-vault-recovery.md?tabs=azure-portal#list-recover-or-purge-a-soft-deleted-key-vault)

+When the request support details are received, quota will be reserved for a stretched cluster environment in the region requested. The subscription gets enabled to deploy a stretched cluster SDDC through the Azure portal. A confirmation email will be sent to the designated point of contact within two business days upon which you should be able to [self-deploy a stretched cluster private cloud via the Azure portal](./tutorial-create-private-cloud.md?tabs=azure-portal#create-a-private-cloud). Be sure to select **Hosts in two availability zones** to ensure that a stretched cluster gets deployed in the region of your choice.

+Once the private cloud is created, you can peer both availability zones (AZs) to your on-premises ExpressRoute circuit with Global Reach that helps connect your on-premises data center to the private cloud. Peering both the AZs will ensure that an AZ failure doesn't result in a loss of connectivity to your private cloud. Since an ExpressRoute Auth Key is valid for only one connection, repeat the [Create an ExpressRoute auth key in the on-premises ExpressRoute circuit](./tutorial-expressroute-global-reach-private-cloud.md#create-an-expressroute-auth-key-in-the-on-premises-expressroute-circuit) process to generate another authorization.

+Next, repeat the process to [peer ExpressRoute Global Reach](./tutorial-expressroute-global-reach-private-cloud.md#peer-private-cloud-to-on-premises) two availability zones to the on-premises ExpressRoute circuit.

+Stretched clusters will solely be supported on the AV36 SKU.

+If the existing commitments prevent upgrading Windows Server or SQL Server, migrate them to Azure and [use Azure Backup to protect the servers](./index.yml). For more information, see [migration of Windows Server, apps and workloads](https://azure.microsoft.com/migration/windows-server/).

+* [Support matrix for backup with Microsoft Azure Backup Server or System Center DPM](backup-support-matrix-mabs-dpm.md)

+If the existing commitments prevent upgrading Windows Server or SQL Server, migrate them to Azure and [use Azure Backup to protect the servers](./index.yml). For more information, see [migration of Windows Server, apps and workloads](https://azure.microsoft.com/migration/windows-server/).

+Azure Backup Server can protect cluster workloads that are located in the same domain as the MABS server, and in a child or trusted domain. If you want to protect data sources in untrusted domains or workgroups, use NTLM or certificate authentication for a single server, or certificate authentication only for a cluster.

+* Reader role on the virtual network of the target virtual machine (if the Bastion deployment is in a peered virtual network).

+See the [Azure Bastion FAQ](bastion-faq.md) for additional requirements.

+Read the [Bastion FAQ](bastion-faq.md) for additional connection information.

+- A **User-assigned managed identity** which has Contributor role access on the Subscription or atleast all resource groups (Compute, Network,Storage). If you wish to install SAP Software through the Azure Center for SAP solutions, also provide Storage Blob data Reader, Reader and Data Access roles to the identity on SAP bits storage account where you would store the SAP Media.

+| Rel 22-10 | [5020438] | Latest Cumulative Update(LCU) | 6.50 | Oct 17, 2022 |

+| Rel 22-10 | [5018413] | IE Cumulative Updates | 2.130, 3.117, 4.110 | Oct 11, 2022 |

+| Rel 22-10 | [5020436] | Latest Cumulative Update(LCU) | 7.18 | Oct 17, 2022 |

+| Rel 22-10 | [5020439] | Latest Cumulative Update(LCU) | 5.74 | Aug 9, 2022 |

+| Rel 22-10 | [5013637] | .NET Framework 3.5 Security and Quality Rollup LKG | 2.130 | Oct 11, 2022 |

+| Rel 22-10 | [5013644] | .NET Framework 4.6.2 Security and Quality Rollup LKG | 2.130 | May 10, 2022 |

+| Rel 22-10 | [5013638] | .NET Framework 3.5 Security and Quality Rollup LKG | 4.110 | Jun 14, 2022 |

+| Rel 22-10 | [5013643] | .NET Framework 4.6.2 Security and Quality Rollup LKG | 4.110 | May 10, 2022 |

+| Rel 22-10 | [5013635] | .NET Framework 3.5 Security and Quality Rollup LKG | 3.117 | Oct 11, 2022 |

+| Rel 22-10 | [5013642] | .NET Framework 4.6.2 Security and Quality Rollup LKG | 3.117 | May 10, 2022 |

+| Rel 22-10 | [5013641] | . NET Framework 3.5 and 4.7.2 Cumulative Update LKG | 6.50 | May 10, 2022 |

+| Rel 22-10 | [5013626] | .NET Framework 4.8 Security and Quality Rollup LKG | 6.50 | May 10, 2022 |

+| Rel 22-10 | [5017028] | .NET Framework 4.8 Security and Quality Rollup LKG | 7.18 | Sep 13, 2022 |

+| Rel 22-10 | [5018454] | Monthly Rollup | 2.130 | Oct 11, 2022 |

+| Rel 22-10 | [5020448] | OOB Monthly Rollup | 2.130 | Oct 17, 2022 |

+| Rel 22-10 | [5018457] | Monthly Rollup | 3.117 | Oct 11, 2022 |

+| Rel 22-10 | [5020449] | OOB Monthly Rollup | 3.117 | Oct 17, 2022 |

+| Rel 22-10 | [5018474] | Monthly Rollup | 4.110 | Oct 11, 2022 |

+| Rel 22-10 | [5020447] | OOB Monthly Rollup | 4.110 | Oct 17, 2020 |

+| Rel 22-10 | [5016263] | Servicing Stack update | 3.117 | Jul 12, 2022 |

+| Rel 22-10 | [5018922] | Servicing Stack update | 4.110 | Oct 11, 2022 |

+| Rel 22-10 | [4578013] | OOB Standalone Security update | 4.110 | Aug 19, 2020 |

+| Rel 22-10 | [5017396] | Servicing Stack update | 5.74 | Sep 13, 2022 |

+| Rel 22-10 | [5017397] | Servicing Stack update | 2.130 | Sep 13, 2022 |

+| Rel 22-10 | [4494175] | Microcode | 5.74 | Sep 1, 2020 |

+| Rel 22-10 | [4494174] | Microcode | 6.50 | Sep 1, 2020 |

+[5020438]: https://support.microsoft.com/kb/5020438

+[5018413]: https://support.microsoft.com/kb/5018413

+[5020436]: https://support.microsoft.com/kb/5020436

+[5020439]: https://support.microsoft.com/kb/5020439

+[5013626]: https://support.microsoft.com/kb/5013626

+[5020448]: https://support.microsoft.com/kb/5020448

+[5020449]: https://support.microsoft.com/kb/5020449

+[5020447]: https://support.microsoft.com/kb/5020447

+[Overview of Creating a Hosted Service for Azure]: ./index.yml

+[The status of the Remove-AzureService command]: ./media/cloud-services-nodejs-develop-deploy-app/node49.png

+Using Anomaly Detector doesn't require any prior experience in machine learning, and the REST API enables you to easily integrate the service into your applications and processes.

+ 2. Go to Key Vault > Access policies, and grant the [Azure Synapse workspace](../../../data-factory/data-factory-service-identity.md?context=%2fazure%2fsynapse-analytics%2fcontext%2fcontext&tabs=synapse-analytics) permission to read secrets from Azure Key Vault.

+* Quick start: [Configure prerequisites for using Cognitive Services in Azure Synapse Analytics](../../../synapse-analytics/machine-learning/tutorial-configure-cognitive-services-synapse.md#create-a-key-vault-and-configure-secrets-and-access).

+* Learn more about [Synapse Analytics](../../../synapse-analytics/index.yml).

+* Read about the [SynapseML v0.9.5 release](https://github.com/microsoft/SynapseML/releases/tag/v0.9.5) on GitHub.

+The following table shows the parameters required by each of the vehicle analysis operations. Many are shared with Spatial Analysis; the only one not shared is the `PARKING_REGIONS` setting. The full list of Spatial Analysis operation parameters can be found in the [Spatial Analysis container](./spatial-analysis-container.md?tabs=azure-stack-edge#iot-deployment-manifest) guide.

+* Set up a [Spatial Analysis container](spatial-analysis-container.md)

+ * [LUIS Endpoint APIs v2.0](/azure/cognitive-services/LUIS/luis-migration-api-v1-to-v2)

+> To deploy a call center transcription solution to Azure with a no-code approach, try the [Ingestion Client](./ingestion-client.md).

+- [Real-time speech-to-text](./how-to-recognize-speech.md): Recognize and transcribe audio in real-time from multiple inputs. For example, with virtual agents or agent-assist, you can continuously recognize audio input and control how to process results based on multiple events.

+- [Batch speech-to-text](./batch-transcription.md): Transcribe large amounts of audio files asynchronously including speaker diarization and is typically used in post-call analytics scenarios. Diarization is the process of recognizing and separating speakers in mono channel audio data.

+- [Text-to-speech](./text-to-speech.md): Text-to-speech enables your applications, tools, or devices to convert text into humanlike synthesized speech.

+- [Speaker identification](./speaker-recognition-overview.md): Helps you determine an unknown speakerΓÇÖs identity within a group of enrolled speakers and is typically used for call center customer verification scenarios or fraud detection.

+- [Language Identification](./language-identification.md): Identify languages spoken in audio and can be used in real-time and post-call analysis for insights or to control the environment (such as output language of a virtual agent).

+| [Custom Speech](./custom-speech-overview.md) | A speech-to-text feature used evaluate and improve the speech recognition accuracy of use-case specific entities (such as alpha-numeric customer, case, and contract IDs, license plates, and names). You can also train a custom model with your own product names and industry terminology. |

+| [Custom Neural Voice](./custom-neural-voice.md) | A text-to-speech feature that lets you create a one-of-a-kind, customized, synthetic voice for your applications. |

+- [Personally Identifiable Information (PII) extraction and redaction](../language-service/personally-identifiable-information/how-to-call-for-conversations.md): Identify, categorize, and redact sensitive information in conversation transcription.

+- [Conversation summarization](../language-service/summarization/overview.md?tabs=conversation-summarization): Summarize in abstract text what each conversation participant said about the issues and resolutions. For example, a call center can group product issues that have a high volume.

+- [Sentiment analysis and opinion mining](../language-service/sentiment-opinion-mining/overview.md): Analyze transcriptions and associate positive, neutral, or negative sentiment at the utterance and conversation-level.

+| [Custom NER (named entity recognition)](../language-service/custom-named-entity-recognition/overview.md) | Improve the detection and extraction of entities in transcriptions. |

+| [Custom text classification](../language-service/custom-text-classification/overview.md) | Classify and label transcribed utterances with either single or multiple classifications. |

+You can find an overview of all Language service features and customization options [here](../language-service/overview.md#available-features).

+* [Post-call transcription and analytics quickstart](./call-center-quickstart.md)

+* [Try out the Speech Studio](https://aka.ms/speechstudio/callcenter)

+To build this integration we recommend using the [Speech SDK](./speech-sdk.md).

+> For guidance on reducing Text to Speech latency check out the **[How to lower speech synthesis latency](./how-to-lower-speech-synthesis-latency.md?pivots=programming-language-csharp)** guide.

+* [Learn about Speech SDK](./speech-sdk.md)

+* [How to lower speech synthesis latency](./how-to-lower-speech-synthesis-latency.md)

+The Ingestion Client is a tool released by Microsoft on GitHub that helps you quickly deploy a call center transcription solution to Azure with a no-code approach.

+Ingestion Client uses the [Azure Cognitive Service for Language](../language-service/index.yml), [Azure Cognitive Service for Speech](./index.yml), [Azure storage](https://azure.microsoft.com/product-categories/storage/), and [Azure Functions](https://azure.microsoft.com/services/functions/).

+- [Batch speech-to-text](./batch-transcription.md): Transcribe large amounts of audio files asynchronously including speaker diarization and is typically used in post-call analytics scenarios. Diarization is the process of recognizing and separating speakers in mono channel audio data.

+- [Speaker identification](./speaker-recognition-overview.md): Helps you determine an unknown speakerΓÇÖs identity within a group of enrolled speakers and is typically used for call center customer verification scenarios or fraud detection.

+- [Personally Identifiable Information (PII) extraction and redaction](../language-service/personally-identifiable-information/how-to-call-for-conversations.md): Identify, categorize, and redact sensitive information in conversation transcription.

+- [Sentiment analysis and opinion mining](../language-service/sentiment-opinion-mining/overview.md): Analyze transcriptions and associate positive, neutral, or negative sentiment at the utterance and conversation-level.

+* [Learn more about Cognitive Services features for call center](./call-center-overview.md)

+* [Explore the Language service features](../language-service/overview.md#available-features)

+* [Explore the Speech service features](./overview.md)

+> For the code samples below, you'll hard-code your Shared Access Signature (SAS) URL where indicated. Remember to remove the SAS URL from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Managed Identity](managed-identity.md). See the Azure Storage [security](../../../storage/common/authorize-data-access.md) article for more information.

+>

+After you set up your Spark cluster and environment, you can run a short sample. This sample assumes Azure Databricks and the `mmlspark.cognitive` package. For an example using `synapseml.cognitive`, see [Add search to AI-enriched data from Apache Spark using SynapseML](../../search/search-synapseml-cognitive-services.md).

+- [Recipe: Intelligent Art Exploration](recipes/art-explorer.md)

+Assigning deployment resources requires Microsoft Azure Active Directory (Azure AD) authentication. Azure AD is used to confirm you have access to the resources you are interested in assigning to your project for multi-region deployment. In the Language Studio, you can automatically [enable Azure AD authentication](https://aka.ms/rbac-language) by assigning yourself the _Cognitive Services Language Owner_ role to your original resource. To programmatically use Azure AD authentication, learn more from the [Cognitive Services documentation](../../../authentication.md?source=docs&tabs=powershell&tryIt=true#authenticate-with-azure-active-directory).

+* [Orchestration workflow](../../orchestration-workflow/how-to/deploy-model.md)

+| [C#/.NET → v1.0.0](https://www.nuget.org/packages/Azure.AI.Language.Conversations/1.0.0) | [C# documentation](/dotnet/api/overview/azure/ai.language.conversations-readme) | [C# samples](https://aka.ms/sdk-sample-conversation-dot-net) |

+| [C#/.NET → v1.0.0](https://www.nuget.org/packages/Azure.AI.Language.QuestionAnswering/1.0.0#readme-body-tab) | [C# documentation](/dotnet/api/overview/azure/ai.language.questionanswering-readme) | [C# samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering) |

+[Azure Cognitive Service for Language overview](../overview.md)

+Language service features utilize AI models. We update the language service with new model versions to improve accuracy, support, and quality. As models become older, they are retired. Use this article for information on that process, and what you can expect for your applications.

+Our standard (not customized) language service features are built on AI models that we call pre-trained models.

+We regularly update the language service with new model versions to improve model accuracy, support, and quality.

+By default, all API requests will use the latest Generally Available (GA) model.

+We recommend using the `latest` model version to utilize the latest and highest quality models. As our models improve, itΓÇÖs possible that some of your model results may change.

+Preview models used for preview features do not maintain a minimum retirement period and may be deprecated at any time.

+By default, API and SDK requests will use the latest Generally Available model. You can use an optional parameter to select the version of the model to be used (not recommended).

+| Feature | Supported versions | Model versions to be deprecated October 30, 2022|

+Azure Cognitive Service for Language supports Azure role-based access control (Azure RBAC), an authorization system for managing individual access to Azure resources. Using Azure RBAC, you assign different team members different levels of permissions for your projects authoring resources. See the [Azure RBAC documentation](../../../role-based-access-control/index.yml) for more information.

+Within a few minutes, the target will be assigned the selected role at the selected scope. For help with these steps, see [Assign Azure roles using the Azure portal](../../../role-based-access-control/role-assignments-portal.md).

+| `regexKey`| `{REGEX-PATTERN}` | A normalized value for the regular expression to map back to in prediction. | `ProductPattern1` |

+|LUIS Runtime APIs and SDK support in .NET, Python, Java, and Node.js |[CLU Runtime APIs](/rest/api/language/conversation-analysis-runtime). CLU Runtime SDK support for [.NET](/dotnet/api/overview/azure/ai.language.conversations-readme) and [Python](/python/api/overview/azure/ai-language-conversations-readme?view=azure-python-preview&preserve-view=true). | See [how to call the API](../how-to/call-api.md#use-the-client-libraries-azure-sdk) for more information. [Refactoring](#do-i-have-to-refactor-my-code-if-i-migrate-my-applications-from-luis-to-clu) will be necessary to use the CLU runtime API response. |

+* [CLU FAQ](../faq.md)

+|C# (Runtime) | [C# documentation](/dotnet/api/overview/azure/ai.language.conversations-readme) | [C# samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples) |

+|C# (Runtime) | [C# documentation](/dotnet/api/overview/azure/ai.language.conversations-readme) | [C# samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples) |

+ Title: "Tutorial: Add your Question Answering project to Power Virtual Agents"

+description: In this tutorial, you will learn how to add your Question Answering project to Power Virtual Agents.

+# Add your Question Answering project to Power Virtual Agents

+Create and extend a [Power Virtual Agents](https://powervirtualagents.microsoft.com/) bot to provide answers from your knowledge base.

+> [!NOTE]

+> The integration demonstrated in this tutorial is in preview and is not intended for deployment to production environments.

+In this tutorial, you learn how to:

+> [!div class="checklist"]

+> * Create a Power Virtual Agents bot

+> * Create a system fallback topic

+> * Add Question Answering as an action to a topic as a Power Automate flow

+> * Create a Power Automate solution

+> * Add a Power Automate flow to your solution

+> * Publish Power Virtual Agents

+> * Test Power Virtual Agents, and receive an answer from your Question Answering project

+> [!Note]

+> The QnA Maker service is being retired on the 31st of March, 2025. A newer version of the question and answering capability is now available as part of [Azure Cognitive Service for Language](/azure/cognitive-services/language-service/). For question answering capabilities within the Language Service, see [question answering](../overview.md). Starting 1st October, 2022 you wonΓÇÖt be able to create new QnA Maker resources. For information on migrating existing QnA Maker knowledge bases to question answering, consult the [migration guide](../how-to/migrate-qnamaker.md).

+## Create and publish a project

+1. Follow the [quickstart](../quickstart/sdk.md?pivots=studio) to create a Question Answering project. Once you have deployed your project.

+2. After deploying your project from Language Studio, click on ΓÇ£Get Prediction URLΓÇ¥.

+3. Get your Site URL from the hostname of Prediction URL and your Account key which would be the Ocp-Apim-Subscription-Key.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/get-prediction-url.png#lightbox)

+4. Create a Custom Question Answering connector: Follow the [connector documentation](/connectors/languagequestionansw/) to create a connection to Question Answering.

+5. Use this tutorial to create a Bot with Power Virtual Agents instead of creating a bot from Language Studio.

+## Create a bot in Power Virtual Agents

+[Power Virtual Agents](https://powervirtualagents.microsoft.com/) allows teams to create powerful bots by using a guided, no-code graphical interface. You don't need data scientists or developers.

+Create a bot by following the steps in [Create and delete Power Virtual Agents bots](/power-virtual-agents/authoring-first-bot).

+## Create the system fallback topic

+In Power Virtual Agents, you create a bot with a series of topics (subject areas), in order to answer user questions by performing actions.

+Although the bot can connect to your project from any topic, this tutorial uses the system fallback topic. The fallback topic is used when the bot can't find an answer. The bot passes the user's text to Question Answering Query knowledgebase API, receives the answer from your project, and displays it to the user as a message.

+Create a fallback topic by following the steps in [Configure the system fallback topic in Power Virtual Agents](/power-virtual-agents/authoring-system-fallback-topic).

+## Use the authoring canvas to add an action

+Use the Power Virtual Agents authoring canvas to connect the fallback topic to your project. The topic starts with the unrecognized user text. Add an action that passes that text to Question Answering, and then shows the answer as a message. The last step of displaying an answer is handled as a [separate step](../../../QnAMaker/Tutorials/integrate-with-power-virtual-assistant-fallback-topic.md#add-your-solutions-flow-to-power-virtual-agents), later in this tutorial.

+This section creates the fallback topic conversation flow.

+The new fallback action might already have conversation flow elements. Delete the **Escalate** item by selecting the **Options** menu.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/delete-action.png#lightbox)

+Below the *Message* node, select the (**+**) icon, then select **Call an action**.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/trigger-action-for-power-automate.png#lightbox)

+Select **Create a flow**. This takes you to the Power Automate portal.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/create-flow.png#lightbox)

+Power Automate opens a new template as shown below.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/power-automate-actions.png#lightbox)

+**Do not use the template shown above.**

+Instead you need to follow the steps below that creates a Power Automate flow. This flow:

+- Takes the incoming user text as a question, and sends it to Question Answering.

+- Returns the top response back to your bot.

+click on **Create** in the left panel, then click "OK" to leave the page.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/power-automate-create-new.png#lightbox)

+Select "Instant Cloud flow"

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/create-instant-cloud-flow.png#lightbox)

+For testing this connector, you can click on ΓÇ£When PowerVirtual Agents calls a flowΓÇ¥ and click on **Create**.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/create-trigger.png#lightbox)

+Click on "New Step" and search for "Power Virtual Agents". Choose "Add an input" and select text. Next, provide the keyword and the value.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-1.png#lightbox)

+Click on "New Step" and search "Language - Question Answering" and choose "Generate answer from Project" from the three actions.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-2.png#lightbox)

+This option helps in answering the specified question using your project. Type in the project name, deployment name and API version and select the question from the previous step.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-3.png#lightbox)

+Click on "New Step" and search for "Initialize variable". Choose a name for your variable, and select the "String" type.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-4.png#lightbox)

+Click on "New Step" again, and search for "Apply to each", then select the output from the previous steps and add an action of "Set variable" and select the connector action.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-5.png#lightbox)

+Click on "New Step" and search for "Return value(s) to Power Virtual Agents" and type in a keyword, then choose the previous variable name in the answer.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-6.png#lightbox)

+The list of completed steps should look like this.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-7.png#lightbox)

+Select **Save** to save the flow.

+## Create a solution and add the flow

+For the bot to find and connect to the flow, the flow must be included in a Power Automate solution.

+1. While still in the Power Automate portal, select Solutions from the left-side navigation.

+2. Select **+ New solution**.

+3. Enter a display name. The list of solutions includes every solution in your organization or school. Choose a naming convention that helps you filter to just your solutions. For example, you might prefix your email to your solution name: jondoe-power-virtual-agent-question-answering-fallback.

+4. Select your publisher from the list of choices.

+5. Accept the default values for the name and version.

+6. Select **Create** to finish the process.

+**Add your flow to the solution**

+1. In the list of solutions, select the solution you just created. It should be at the top of the list. If it isn't, search by your email name, which is part of the solution name.

+2. In the solution, select **+ Add existing**, and then select Flow from the list.

+3. Find your flow from the **Outside solutions** list, and then select Add to finish the process. If there are many flows, look at the **Modified** column to find the most recent flow.

+## Add your solution's flow to Power Virtual Agents

+1. Return to the browser tab with your bot in Power Virtual Agents. The authoring canvas should still be open.

+2. To insert a new step in the flow, above the **Message** action box, select the plus (+) icon. Then select **Call an action**.

+3. From the **Flow** pop-up window, select the new flow named **Generate answers using Question Answering Project...**. The new action appears in the flow.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-8.png#lightbox)

+4. To correctly set the input variable to the QnA Maker action, select **Select a variable**, then select **bot.UnrecognizedTriggerPhrase**.

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-9.png#lightbox)

+5. To correctly set the output variable to the Question Answering action, in the **Message** action, select **UnrecognizedTriggerPhrase**, then select the icon to insert a variable, {x}, then select **FinalAnswer**.

+6. From the context toolbar, select **Save**, to save the authoring canvas details for the topic.

+Here's what the final bot canvas looks like:

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-10.png#lightbox)

+## Test the bot

+As you design your bot in Power Virtual Agents, you can use the [Test bot pane](/power-virtual-agents/authoring-test-bot) to see how the bot leads a customer through the bot conversation.

+1. In the test pane, toggle **Track between topics**. This allows you to watch the progression between topics, as well as within a single topic.

+2. Test the bot by entering the user text in the following order. The authoring canvas reports the successful steps with a green check mark.

+|**Question order**|**Test questions** |**Purpose** |

+||-|--|

+|1 |Hello |Begin conversation |

+|2 |Store hours |Sample topic. This is configured for you without any additional work on your part. |

+|3 |Yes |In reply to "Did that answer your question?" |

+|4 |Excellent |In reply to "Please rate your experience." |

+|5 |Yes |In reply to "Can I help with anything else?" |

+|6 |How can I improve the throughput performance for query predictions?|This question triggers the fallback action, which sends the text to your knowledge base to answer. Then the answer is shown. the green check marks for the individual actions indicate success for each action.|

+> [!div class="mx-imgBorder"]

+> [  ]( ../media/power-virtual-agents/flow-step-11.png#lightbox)

+## Publish your bot

+To make the bot available to all members of your organization, you need to publish it.

+Publish your bot by following the steps in [Publish your bot](/power-virtual-agents/publication-fundamentals-publish-channels).

+## Share your bot

+To make your bot available to others, you first need to publish it to a channel. For this tutorial we'll use the demo website.

+Configure the demo website by following the steps in [Configure a chatbot for a live or demo website](/power-virtual-agents/publication-connect-bot-to-web-channels).

+Then you can share your website URL with your school or organization members.

+## Clean up resources

+When you are done with the knowledge base, remove the QnA Maker resources in the Azure portal.

+## See also

+* [Tutorial: Create an FAQ bot](../tutorials/bot-service.md)

+Recall that Personalizer will either return the _best action_ or an _exploratory action_ chosen by the exploration policy. The best action is the one that the model has determined has the highest probability of maximizing the average reward, whereas exploratory actions are chosen among the set of all possible actions provided in the Rank API call. Actions taken during exploration do not leverage the feature scores in determining which action to take, therefore **feature scores for exploratory actions should not be used to gain an understanding of why the action was taken.** [You can learn more about exploration here](./concepts-exploration.md).

+[Reinforcement learning](concepts-reinforcement-learning.md)

+| [Authentication options](./authentication.md)| Authentication is the act of verifying a user's identity. Authorization, by contrast, is the specification of access rights and privileges to resources for a given identity. An identity is a collection of information about a <a href="https://en.wikipedia.org/wiki/Principal_(computer_security)" target="_blank">principal</a>, and a principal can be either an individual user or a service.</br></br>By default, you authenticate your own calls to Cognitive Services using the subscription keys provided; this is the simplest method but not the most secure. The most secure authentication method is to use managed roles in Azure Active Directory. To learn about this and other authentication options, see [Authenticate requests to Cognitive Services](./authentication.md). |

+| [Bring your own storage (BYOS)](./speech-service/speech-encryption-of-data-at-rest.md)| The Speech service doesn't currently support Customer Lockbox. However, you can arrange for your service-specific data to be stored in your own storage resource using bring-your-own-storage (BYOS). BYOS allows you to achieve similar data controls to Customer Lockbox. Keep in mind that Speech service data stays and is processed in the Azure region where the Speech resource was created. This applies to any data at rest and data in transit. For customization features like Custom Speech and Custom Voice, all customer data is transferred, stored, and processed in the same region where the Speech service resource and BYOS resource (if used) reside. </br></br>To use BYOS with Speech, follow the [Speech encryption of data at rest](./speech-service/speech-encryption-of-data-at-rest.md) guide.</br></br> Microsoft does not use customer data to improve its Speech models. Additionally, if endpoint logging is disabled and no customizations are used, then no customer data is stored by Speech. |

+* Explore [Cognitive Services](./what-are-cognitive-services.md) and choose a service to get started.

+Use this article to learn how to develop Cognitive Services applications securely by using [Azure Key Vault](../key-vault/general/overview.md).

+* An [Azure Key Vault](../key-vault/general/quick-create-portal.md)

+* An [Azure Key Vault](../key-vault/general/quick-create-portal.md)

+* An [Azure Key Vault](../key-vault/general/quick-create-portal.md)

+* An [Azure Key Vault](../key-vault/general/quick-create-portal.md)

+For your application to retrieve and use your credentials to authenticate API calls, you will need to add them to your [key vault secrets](../key-vault/secrets/about-secrets.md).

+* See [What are Cognitive Services](./what-are-cognitive-services.md) for available features you can develop along with [Azure key vault](../key-vault/general/index.yml).

+ * [Best practices for using Azure Key Vault](../key-vault/general/best-practices.md)

+ * [Azure security baseline for Cognitive Services](/security/benchmark/azure/baselines/cognitive-services-security-baseline?toc=/azure/cognitive-services/TOC.json)

+The `participantEndReason` will contain a value from the set of Calling SDK error codes. You can refer to these codes to troubleshoot issues during the call, per Endpoint. See [troubleshooting in Azure communication Calling SDK error codes](../troubleshooting-info.md?tabs=csharp%2cios%2cdotnet#calling-sdk-error-codes)

+| [GCC-H](/office365/servicedescriptions/office-365-platform-service-description/office-365-us-government/gcc-high-and-dod) | [US Government](../../../../azure-government/documentation-government-welcome.md) | ✔️ |

+- [1] Gov cloud users can join a channel Teams meeting with audio and video, but they won't be able to send or receive any chat messages

+Find more details in [Azure Active Directory documentation](../../../../active-directory/roles/permissions-reference.md).

+| [GCC-H](/office365/servicedescriptions/office-365-platform-service-description/office-365-us-government/gcc-high-and-dod) | [US Government](../../../../azure-government/documentation-government-welcome.md) | ❌ |

+[useraccesstokens]: ../../quickstarts/access-tokens.md?pivots=programming-language-csharp

+[worker-scoring]: ../../how-tos/router-sdk/customize-worker-scoring.md

+- [Receive message as Teams user on webhook](/graph/teams-changenotifications-chatMessage) and then push message to the client with, for example, [SignalR](../../azure-signalr/signalr-overview.md).

+- [Start a call to Teams user as a Teams user](../quickstarts/voice-video-calling/get-started-with-voice-video-calling-custom-teams-client.md)

+1. Finish all the prerequisite steps in [Chat Quickstart](../quickstarts/chat/get-started.md?pivots=programming-language-swift)

+6. As User B, send a chat message. You (User A) should be able to receive a push notification in your IOS device.

+- Access to a public or private container registry, such as the [Azure Container Registry](../container-registry/index.yml).

+> [Environments in Azure Container Apps](environment.md)

+[Azure Container Apps](overview.md) provides a [managed identity](managed-identity.md) for your app, which is a turn-key solution for securing access to [Azure Database for PostgreSQL](../postgresql/index.yml) and other Azure services. Managed identities in Container Apps make your app more secure by eliminating secrets from your app, such as credentials in the environment variables.

+> [Azure for Java Developers](/java/azure/)

+The [Conditional Access policy](../active-directory/conditional-access/overview.md) is designed to enforce strong authentication. The authentication is based on the location, trusted and compliant devices, user assigned roles, authorization method, and the client applications. The policy enables the security to meet the organizations compliance requirements and keep the data and user accounts safe.

+Learn more about [Conditional Access policy](../active-directory/conditional-access/overview.md), the [conditions](../active-directory/conditional-access/overview.md#common-signals) you'll take it into consideration to make [policy decisions.](../active-directory/conditional-access/overview.md#common-decisions)

+ > To configure and grant multi-factor authentication, see [configure and conditions for multi-factor authentication.](../active-directory/authentication/tutorial-enable-azure-mfa.md#configure-the-conditions-for-multi-factor-authentication)

+* Learn more about [common access concerns that Conditional Access policies can help with](../active-directory/conditional-access/concept-conditional-access-policy-common.md).

+* Learn more about [Conditional Access policy components](../active-directory/conditional-access/concept-conditional-access-policies.md).

+* You can find the steps to move resources of registry to a new resource group in the same subscription or move resources to a [new subscription.](../azure-resource-manager/management/move-resource-group-and-subscription.md)

+* See the [Resource Manager template reference](/azure/templates/microsoft.containerregistry/registries) for Azure Container Registry.

+Here's how you can [index data from the Azure Cosmos DB for MongoDB account](../../search/search-howto-index-cosmosdb-mongodb.md) to use with Azure Cognitive Search.

+* [Set up analytics with Azure Synapse Link.](../configure-synapse-link.md)

+* To learn more about Azure Cosmos DB, refer to the service's [documentation](../index.yml) page.

+ * If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

+* To learn more about Azure Cosmos DB, see the [Azure Cosmos DB documentation landing page](../index.yml).

+Add the following variables to manage unique database and container names and the [partition key (pk)](../partitioning-overview.md).

+> [Tutorial: Build a Node.js console app](sql-api-nodejs-get-started.md)

+ Title: API for NoSQL Go examples for Azure Cosmos DB

+description: Find Go examples on GitHub for common tasks in Azure Cosmos DB, including CRUD operations.

+ms.devlang: go

+# Azure Cosmos DB Go examples

+> [!div class="op_single_selector"]

+> * [.NET SDK Examples](samples-dotnet.md)

+> * [Java V4 SDK Examples](samples-java.md)

+> * [Spring Data V3 SDK Examples](samples-java-spring-data.md)

+> * [Node.js Examples](samples-nodejs.md)

+> * [Python Examples](samples-python.md)

+> * [Go Examples](samples-go.md)

+> * [Azure Code Sample Gallery](https://azure.microsoft.com/resources/samples/?sort=0&service=cosmos-db)

+Sample solutions that do CRUD operations and other common operations on Azure Cosmos DB resources are included in the [azure-documentdb-go](https://github.com/Azure/azure-sdk-for-go) GitHub repository. This article provides:

+* Links to the tasks in each of the Go example project files.

+* Links to the related API reference content.

+## Prerequisites

+- An Azure Cosmos DB Account. Your options are:

+ * Within an Azure active subscription:

+ * [Create an Azure free Account](https://azure.microsoft.com/free) or use your existing subscription

+ * [Visual Studio Monthly Credits](https://azure.microsoft.com/pricing/member-offers/credit-for-visual-studio-subscribers)

+ * [Azure Cosmos DB Free Tier](../free-tier.md)

+ * Without an Azure active subscription:

+ * [Try Azure Cosmos DB for free](../try-free.md), a tests environment that lasts for 30 days.

+ * [Azure Cosmos DB Emulator](https://aka.ms/cosmosdb-emulator)

+- [go](https://go.dev/) installed on your computer, and a working knowledge of Go.

+- [Visual Studio Code](https://code.visualstudio.com/).

+- The [Go extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=golang.Go).

+- [Git](https://www.git-scm.com/downloads).

+- [Azure Cosmos DB for NoSQL SDK for Go](https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/data/azcosmos)

+## Database examples

+The [cosmos_client.go](https://github.com/Azure/azure-sdk-for-go/blob/sdk/dat) conceptual article.

+| Task | API reference |

+| | |

+| [Create a database](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_client.go#L151) |Client.CreateDatabase |

+| [Read a database by ID](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_client.go#L119) |Client.NewDatabase|

+| [Delete a database](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_database.go#L155) |DatabaseClient.Delete|

+## Container examples

+The [cosmos_database.go](https://github.com/Azure/azure-sdk-for-go/blob/sdk/dat) conceptual article.

+| Task | API reference |

+| | |

+| [Create a container](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_database.go#L47) |DatabaseClient.CreateContainer |

+| [Get a container by its ID](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_database.go#L35) |DatabaseClient.NewContainer |

+| [Delete a container](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_container.go#L109) |ContainerClient.Delete |

+## Item examples

+The [cosmos_container.go](https://github.com/Azure/azure-sdk-for-go/blob/sdk/dat) conceptual article.

+| Task | API reference |

+| | |

+| [Create a item in a container](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_container.go#L184) |ContainerClient.CreateItem |

+| [Read an item by its ID](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_container.go#L325) |ContainerClient.ReadItem |

+| [Query items](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_container.go#L410) |ContainerClient.NewQueryItemsPager |

+| [Replace an item](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_container.go#L279) |ContainerClient.ReplaceItem |

+| [Upsert an item](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_container.go#L229) |ContainerClient.UpsertIitem |

+| [Delete an item](https://github.com/Azure/azure-sdk-for-go/blob/sdk/data/azcosmos/v0.3.2/sdk/data/azcosmos/cosmos_container.go#L366) |ContainerClient.DeleteItem |

+## Next steps

+Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.

+* If all you know is the number of vcores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md)

+* If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

+>

+> - [.NET SDK Examples](samples-dotnet.md)

+> - [Java V4 SDK Examples](samples-java.md)

+> - [Spring Data V3 SDK Examples](samples-java-spring-data.md)

+> - [Node.js Examples](samples-nodejs.md)

+> - [Python Examples](samples-python.md)

+> - [Azure Code Sample Gallery](https://azure.microsoft.com/resources/samples/?sort=0&service=cosmos-db)

+>

+Sample solutions that do CRUD operations and other common operations on Azure Cosmos DB resources are included in the `main/sdk/cosmos` folder of the [azure/azure-sdk-for-python](https://github.com/azure/azure-sdk-for-python/tree/main/sdk/cosmos) GitHub repository. This article provides:

+- Links to the tasks in each of the Python example project files.

+- Links to the related API reference content.

+- An Azure Cosmos DB Account. Your options are:

+ - Within an Azure active subscription:

+ - [Create an Azure free Account](https://azure.microsoft.com/free) or use your existing subscription

+ - [Visual Studio Monthly Credits](https://azure.microsoft.com/pricing/member-offers/credit-for-visual-studio-subscribers)

+ - [Azure Cosmos DB Free Tier](../free-tier.md)

+ - Without an Azure active subscription:

+ - [Try Azure Cosmos DB for free](../try-free.md), a tests environment that lasts for 30 days.

+ - [Azure Cosmos DB Emulator](https://aka.ms/cosmosdb-emulator)

+- [Git](https://www.git-scm.com/downloads).

+- If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md)

+- If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

+- A supported [Java Development Kit](/azure/developer/jav).

+This quickstart shows you how to use the [psql](https://www.postgresql.org/docs/current/app-psql.html) connection string in [Azure Cloud Shell](../../cloud-shell/overview.md) to connect to an Azure Cosmos DB for PostgreSQL cluster.

+> [Create and distribute tables >](quickstart-distribute-tables.md)

+- If you want to run the code locally, [Azure CLI](/cli/azure/install-azure-cli) installed. You can also run the code in [Azure Cloud Shell](../../cloud-shell/overview.md).

+* Learn about [private DNS zones](../../dns/private-dns-overview.md)

+## Exceeding reserved capacity

+When you reserve capacity for your Azure Cosmos DB resources, you are reserving [provisioned thorughput](set-throughput.md). If the provisioned throughput is exceeded, requests beyond that provisioning will be rate-limited. For more information, see [provisioned throughput types](how-to-choose-offer.md#overview-of-provisioned-throughput-types).

+* [Azure Storage documentation](../../storage/index.yml)

+When you shut down, stop, or suspend the Azure Data Explorer cluster, the applicable reservations automatically apply to other matching resources (compute and Azure Data Explorer markup) in the specified scope. If no matching resources are found in the specified scope, then the reserved hours are *lost*.

+* [Understand reservation usage for CSP subscriptions](/partner-center/azure-reservations)

+* Use updated [default parameterization template.](./continuous-integration-delivery-resource-manager-custom-parameters.md#default-parameterization-template) as one time migration to new method of including global parameters. This template references to all values in global parameter list. You also have to update the deployment task in the **release pipeline** if you are already overriding the template parameters there.

+* [Twitter information about Data Factory](https://twitter.com/hashtag/DataFactory)

+When you perform data integration and ETL processes in the cloud, your jobs can perform much better and be more effective when you only read the source data that has changed since the last time the pipeline ran, rather than always querying an entire dataset on each run. ADF provides multiple different ways for you to easily get delta data only from the last run.

+### Native change data capture in mapping data flow

+The changed data including inserted, updated and deleted rows can be automatically detected and extracted by ADF mapping data flow from the source databases. No timestamp or ID columns are required to identify the changes since it uses the native change data capture technology in the databases. By simply chaining a source transform and a sink transform reference to a database dataset in a mapping data flow, you will see the changes happened on the source database to be automatically applied to the target database, so that you can easily synchronize data between two tables. You can also add any transformations in between for any business logic to process the delta data.

+**Supported connectors**

+- [SAP CDC](connector-sap-change-data-capture.md)

+- [Azure SQL Database](connector-azure-sql-database.md)

+- [Azure SQL Server](connector-sql-server.md)

+- [Azure SQL Managed Instance](connector-azure-sql-managed-instance.md)

+- [Azure Cosmos DB (SQL API)](connector-azure-cosmos-db.md)

+### Auto incremental extraction in mapping data flow

+The newly updated rows or updated files can be automatically detected and extracted by ADF mapping data flow from the source stores. When you want to get delta data from the databases, the incremental column is required to identify the changes. When you want to load new files or updated files only from a storage store, ADF mapping data flow just works through filesΓÇÖ last modify time.

+**Supported connectors**

+- [Azure Blob Storage](connector-azure-blob-storage.md)

+- [ADLS Gen2](load-azure-data-lake-storage-gen2.md)

+- [ADLS Gen1](load-azure-data-lake-store.md)

+- [Azure SQL Database](connector-azure-sql-database.md)

+- [Azure SQL Server](connector-sql-server.md)

+- [Azure SQL Managed Instance](connector-azure-sql-managed-instance.md)

+- [Azure Database for MySQL](connector-azure-database-for-mysql.md)

+- [Azure Database for PostgreSQL](connector-azure-database-for-postgresql.md)

+- [Common data model](format-common-data-model.md)

+### Customer managed delta data extraction in pipeline

+You can always build your own delta data extraction pipeline for all ADF supported data stores including using lookup activity to get the watermark value stored in an external control table, copy activity or mapping data flow activity to query the delta data against timestamp or ID column, and SP activity to write the new watermark value back to your external control table for the next run. When you want to load new files only from a storage store, you can either delete files every time after they have been moved to the destination successfully, or leverage the time partitioned folder or file names or last modified time to identify the new files.

+## Best Practices

+**Change data capture from databases:**

+- Native change data capture is always recommended as the simplest way for you to get change data. It also brings much less burden on your source database when ADF extracts the change data for further processing.

+- If your database stores are not part of the ADF connector list with native change data capture support, we recommend you to check the auto incremental extraction option where you only need to input incremental column to capture the changes. ADF will take care of the rest including creating a dynamic query for delta loading and managing the checkpoint for each activity run.

+- Customer managed delta data extraction in pipeline covers all the ADF supported databases and give you the flexibility to control everything by yourself.

+**Change files capture from file based storages:**

+- When you want to load data from Azure Blob Storage, Azure Data Lake Storage Gen2 or Azure Data Lake Storage Gen1, mapping data flow provides you the opportunity to get new or updated files only by simple one click. It is the simplest and recommended way for you to achieve delta load from these file based storages in mapping data flow.

+- You can get more [best practices](https://techcommunity.microsoft.com/t5/azure-data-factory-blog/best-practices-of-how-to-use-adf-copy-activity-to-copy-new-files/ba-p/1532484).

+## Checkpoint

+When you enable native change data capture or auto incremental extraction options in ADF mapping data flow, ADF helps you to manage the checkpoint to make sure each activity run will automatically only read the source data that has changed since the last time the pipeline run. By default, the checkpoint is coupled with your pipeline and activity name. If you change your pipeline name or activity name, the checkpoint will be reset, which leads you to start from beginning or get changes from now in the next run. If you do want to change the pipeline name or activity name but still keep the checkpoint to get changed data from the last run automatically, please use your own [Checkpoint key](control-flow-execute-data-flow-activity.md#checkpoint-key) in data flow activity to achieve that.

+When you debug the pipeline, this feature works the same. The checkpoint will be reset when you refresh your browser during the debug run. After you are satisfied with the pipeline result from debug run, you can go ahead to publish and trigger the pipeline. At the moment when you first time trigger your published pipeline, it automatically restarts from the beginning or gets changes from now on.

+In the monitoring section, you always have the chance to rerun a pipeline. When you are doing so, the changed data is always captured from the previous checkpoint of your selected pipeline run.

+## Tutorials

+The followings are the tutorials to start the change data capture in Azure Data Factory and Azure Synapse Analytics.

+- [SAP CDC tutorial in ADF](sap-change-data-capture-introduction-architecture.md#sap-cdc-capabilities)

+- [Incrementally copy data from a source data store to a destination data store tutorials](tutorial-incremental-copy-overview.md)

+| billingReference | The billing consumption for the given run. Learn more from [Monitor consumption at activity-run level](plan-manage-costs.md#monitor-consumption-at-activity-run-level-in-azure-data-factory). | Object |

+If you do not have an Azure Automation account already, create one by following the instructions in this step. For detailed steps, see [Create an Azure Automation account](../automation/quickstarts/create-azure-automation-account-portal.md) article. As part of this step, you create an **Azure Run As** account (a service principal in your Azure Active Directory) and assign it a **Contributor** role in your Azure subscription. Ensure that it is the same subscription that contains your ADF with Azure SSIS IR. Azure Automation will use this account to authenticate to Azure Resource Manager and operate on your resources.

+- [Connect to on-premises data sources with Windows authentication](/sql/integration-services/lift-shift/ssis-azure-connect-with-windows-auth)

+First, at the beginning of the ETL project, you use a combination of the Azure pricing and per-pipeline consumption and pricing calculators to help plan for Azure Data Factory costs before you add any resources for the service to estimate costs. Next, as you add Azure resources, review the estimated costs. After you've started using Azure Data Factory resources, use Cost Management features to set budgets and monitor costs. You can also review forecasted costs and identify spending trends to identify areas where you might want to act. Costs for Azure Data Factory are only a portion of the monthly costs in your Azure bill. Note that this article only explains how to plan for and manage costs for data factory. You're billed for all Azure services and resources used in your Azure subscription, including the third-party services.

+Use the [ADF pricing calculator](https://azure.microsoft.com/pricing/calculator/?service=data-factory) to get an estimate of the cost of running your ETL workload in Azure Data Factory. .To use the calculator, you have to input details such as number of activity runs, number of data integration unit hours, type of compute used for Data Flow, core count, instance count, execution duration, and etc.

+Here's a sample copy activity run detail (your actual mileage will vary based on the shape of your specific dataset, network speeds, egress limits on S3 account, ingress limits on ADLS Gen2, and other factors).

+By using the [consumption monitoring at pipeline-run level](#monitor-consumption-at-pipeline-run-level-in-azure-data-factory), you can see the corresponding data movement meter consumption quantities:

+Azure Data Factory runs on Azure infrastructure that accrues costs when you deploy new resources. It's important to understand that other extra infrastructure costs might accrue.

+Azure Data Factory is a serverless and elastic data integration service built for cloud scale. There isn't a fixed-size compute that you need to plan for peak load; rather you specify how much resource to allocate on demand per operation, which allows you to design the ETL processes in a much more scalable manner. In addition, ADF is billed on a consumption-based plan, which means you only pay for what you use.

+- Orchestration Activity Runs - You're charged for it based on the number of activity runs orchestrate.

+- Data Integration Unit (DIU) Hours ΓÇô For copy activities run on Azure Integration Runtime, you're charged based on number of DIU used and execution duration.

+- vCore Hours ΓÇô for data flow execution and debugging, you're charged for based on compute type, number of vCores, and execution duration.

+### Monitor costs at factory level with Cost Analysis

+As you use Azure resources with Data Factory, you incur costs. Azure resource usage unit costs vary by time intervals (seconds, minutes, hours, and days) or by unit usage (bytes, megabytes, and so on.) As soon as Data Factory use starts, costs are incurred and you can see the costs in [cost analysis](../cost-management-billing/costs/quick-acm-cost-analysis.md).

+### Monitor costs at pipeline level with Cost Analysis

+In certain cases, you may want a granular breakdown of cost of operations within our factory, for instance, for charge back purposes. Integrating Azure Billing [cost analysis](../cost-management-billing/costs/quick-acm-cost-analysis.md) platform, Data Factory can separate out billing charges for each pipeline. By **opting in** Azure Data Factory detailed billing reporting for a factory, you can better understand how much each pipeline is costing you, within the aforementioned factory.

+You need to opt in for _each_ factory that you want detailed billing for. To turn on per pipeline detailed billing feature,

+1. Go to Azure Data Factory portal

+1. Under _Monitor_ tab, select _Factory setting_ in _General_ section

+1. Select _Showing billing report_ by pipeline

+1. Publish the change

+> [!NOTE]

+> The detailed pipeline billing settings is _not_ included in the exported ARM templates from your factory. That means [Continuous Integration and Delivery (CI/CD)](continuous-integration-delivery-improvements.md) will not overwrite billing behaviors for the factory. This allows you to set different billing behaviors for development, test, and production factories.

+Once the feature is enabled, each pipeline will have a separate entry in our Billing report: It shows _exactly_ how much each pipeline costs, in the selected time interval. It allows you to identify spending trends, and notice overspending, if any occurred.

+Using the graphing tools of Cost Analysis, you get similar charts and trends lines as shown [above](#monitor-costs-at-factory-level-with-cost-analysis), but for individual pipelines. You also get the summary view by factory name, as factory name is included in billing report, allowing for proper filtering when necessary.

+> [!WARNING]

+> By opting in the per billing setting, there will be one entry for each pipeline in your factory. Please be particularly aware if you have excessive amount of pipelines in the factory, as it may significantly lengthen and complicate your billing report.

+#### Limitations

+Following are known limitations of per pipeline billing features. These billing meters won't file under the pipeline that spins it, but instead will file under a fall-back line item for your factory.

+- Data Factory Operations charges, including Read/Write and Monitoring

+- Charges for [Azure Data Factory SQL Server Integration Services (SSIS) nodes](tutorial-deploy-ssis-packages-azure.md)

+- If you have [Time to Live (TTL)](concepts-integration-runtime-performance.md#time-to-live) configured for Azure Integration Runtime (Azure IR), Data Flow activities run on these IR won't file under individual pipelines.

+### Monitor consumption at pipeline-run level in Azure Data Factory

+Depending on the types of activities you have in your pipeline, how much data you're moving and transforming, and the complexity of the transformation, executing a pipeline will spin different billing meters in Azure Data Factory.

+You can view the amount of consumption for different meters for individual pipeline runs in the Azure Data Factory user experience. To open the monitoring experience, select the **Monitor & Manage** tile in the data factory blade of the [Azure portal](https://portal.azure.com/). If you're already in the ADF UX, select on the **Monitor** icon on the left sidebar. The default monitoring view is list of pipeline runs.

+The pipeline run consumption view shows you the amount consumed for each ADF meter for the specific pipeline run, but it doesn't show the actual price charged, because the amount billed to you is dependent on the type of Azure account you have and the type of currency used. To view the full list of supported account types, see [Understand Cost Management data](../cost-management-billing/costs/understand-cost-mgt-data.md).

+### Monitor consumption at activity-run level in Azure Data Factory

+To see the consumption at activity-run level, go to your data factory **Author & Monitor** UI. From the **Monitor** tab where you see a list of pipeline runs, select the **pipeline name** link to access the list of activity runs in the pipeline run. Select on the **Output** button next to the activity name and look for **billableDuration** property in the JSON output:

+Here's a sample out from a copy activity run:

+And here's a sample out from a Mapping Data Flow activity run:

+Budgets can be created with filters for specific resources or services in Azure if you want more granularity present in your monitoring. Filters help ensure that you don't accidentally create new resources that cost you extra money. For more information about the filter options available when you create a budget, see [Group and filter options](../cost-management-billing/costs/group-filter.md?WT.mc_id=costmanagementcontent_docsacmhorizontal_-inproduct-learn).

+You can also [export your cost data](../cost-management-billing/costs/tutorial-export-acm-data.md?WT.mc_id=costmanagementcontent_docsacmhorizontal_-inproduct-learn) to a storage account. This is helpful when you need or others to do other data analysis for costs. For example, finance teams can analyze the data using Excel or Power BI. You can export your costs on a daily, weekly, or monthly schedule and set a custom date range. Exporting cost data is the recommended way to retrieve cost datasets.

+- [Join Azure-SSIS IR to a virtual network that connects to on-premises sources](./join-azure-ssis-integration-runtime-virtual-network.md)

+- [Use self-hosted IR to connect on-premises sources](./self-hosted-integration-runtime-proxy-ssis.md).

+- [Change to %TEMP%](./ssis-azure-files-file-shares.md)

+- [Migrate your files to Azure Files](./ssis-azure-files-file-shares.md)

+- [Join Azure-SSIS IR to a virtual network that connects to on-premises sources](./join-azure-ssis-integration-runtime-virtual-network.md).

+- [Use self-hosted IR to connect on-premises sources](./self-hosted-integration-runtime-proxy-ssis.md).

+[Customize Azure-SSIS integration runtime](./how-to-configure-azure-ssis-ir-custom-setup.md) to install non built-in provider or driver.

+- [Customize SSIS integration runtime setup](./how-to-configure-azure-ssis-ir-custom-setup.md) with Windows environment variables.

+[Configure Azure SSIS integration runtime to enterprise edition](./how-to-configure-azure-ssis-ir-enterprise-edition.md).

+Install compatible JRE by [customize setup for the Azure-SSIS integration runtime](./how-to-configure-azure-ssis-ir-custom-setup.md).

+- For in-house or open source component, [customize Azure-SSIS integration runtime](./how-to-configure-azure-ssis-ir-custom-setup.md) to install necessary SQL Server 2017 compatible components.

+[Customize Azure-SSIS integration runtime](./how-to-configure-azure-ssis-ir-custom-setup.md) to install non built-in provider or driver.

+- [Migrate your executable(s) to Azure Files](./ssis-azure-files-file-shares.md).

+- [Join Azure-SSIS IR to a virtual network](./join-azure-ssis-integration-runtime-virtual-network.md) that connects to on-premises sources.

+- If necessary, [customize setup script to install your executable(s)](./how-to-configure-azure-ssis-ir-custom-setup.md) in advance when starting IR.

+- [Migrate your files to Azure Files](./ssis-azure-files-file-shares.md)

+- [Join Azure-SSIS IR to a virtual network that connects to on-premises sources](./join-azure-ssis-integration-runtime-virtual-network.md).

+- [Use self-hosted IR to connect on-premises sources](./self-hosted-integration-runtime-proxy-ssis.md).

+[Access Control for Sensitive Data in Packages](/sql/integration-services/security/access-control-for-sensitive-data-in-packages)

+[ML Studio (classic)](../machine-learning/index.yml) enables you to build, test, and deploy predictive analytics solutions. From a high-level point of view, it is done in three steps:

+Azure Data Factory and Synapse Analytics enable you to easily create pipelines that use a published [Machine Learning Studio (classic)](../machine-learning/index.yml) web service for predictive analytics. Using the **Batch Execution Activity** in a pipeline, you can invoke Machine Learning Studio (classic) web service to make predictions on the data in batch.

+* [Stored procedure activity](transform-data-using-stored-procedure.md)

+[ML Studio (classic)](../../machine-learning/index.yml) enables you to build, test, and deploy predictive analytics solutions. From a high-level point of view, it is done in three steps:

+[azure-machine-learning]: https://azure.microsoft.com/services/machine-learning/

+* [Azure Data Factory](../index.yml)

+* [Azure Batch](../../batch/index.yml)

+[batch-explorer-walkthrough]: /archive/blogs/windowshpc/azure-batch-explorer-sample-walkthrough

+To deploy NVIDIA DIGITS, see [Enable a GPU in a prefabricated NVIDIA module](../iot-edge/configure-connect-verify-gpu.md?preserve-view=true&view=iotedge-2020-11#enable-a-gpu-in-a-prefabricated-nvidia-module).

+> You will need to enable multifactor authentication for the user who manages the VMs and images that are deployed on your device from the cloud. The cloud operations will fail if the user doesn't have multifactor authentication enabled. For steps to enable multifactor authentication, see [Manage authentication methods for Azure AD Multi-Factor Authentication](../active-directory/authentication/howto-mfa-userdevicesettings.md).

+- [Monitor CPU and memory on a VM](azure-stack-edge-gpu-monitor-virtual-machine-metrics.md)

+This reference architecture shows running an Azure App Service application in a single region. This architecture shows a set of proven practices for a web application that uses [Azure App Service](../app-service/index.yml) and [Azure SQL Database](/azure/sql-database/).

+- Learn how to [create a DDoS protection plan](manage-ddos-protection.md).

+description: Learn how Microsoft Defender for Cloud uses the guest configuration to compare your OS hardening with the guidance from Microsoft cloud security benchmark

+The Microsoft cloud security benchmark has guidance for OS hardening which has led to security baseline documents for [Windows](../governance/policy/samples/guest-configuration-baseline-windows.md) and [Linux](../governance/policy/samples/guest-configuration-baseline-linux.md).

+These recommendations use the guest configuration feature of Azure Policy to compare the OS configuration of a machine with the baseline defined in the [Microsoft cloud security benchmark](/security/benchmark/azure/overview).

+- [Microsoft cloud security benchmark](/security/benchmark/azure/overview)

+| Internet exposed VM has high severity vulnerabilities and read permission to a data store with sensitive data | Virtual machine '\[MachineName]' is reachable from the internet, has high severity vulnerabilities \[RCE] and \[IdentityDescription] with read permission to \[DatabaseType] '\[DatabaseName]' containing sensitive data. For more details, you can learn how to [prioritize security actions by data sensitivity](./information-protection.md). |

+| VM has high severity vulnerabilities and read permission to a data store with sensitive data | Virtual machine '\[MachineName]' has high severity vulnerabilities \[RCE] and \[IdentityDescription] with read permission to \[DatabaseType] '\[DatabaseName]' containing sensitive data. For more details, you can learn how to [prioritize security actions by data sensitivity](./information-protection.md). |

+| Internet exposed EC2 instance has high severity vulnerabilities and read permission to a S3 bucket with sensitive data | Option 1 <br> AWS EC2 instance '\[MachineName]' is reachable from the internet, has high severity vulnerabilities\[RCE] and has IAM role attached with '\[Rolepermission]' permission via IAM policy to S3 bucket '\[BucketName]' containing sensitive data <br> <br> Option 2 <br> AWS EC2 instance '\[MachineName]' is reachable from the internet, has high severity vulnerabilities\[RCE] and has IAM role attached with '\[S3permission]' permission via bucket policy to S3 bucket '\[BucketName]' containing sensitive data <br> <br> Option 3 <br> AWS EC2 instance '\[MachineName]' is reachable from the internet, has high severity vulnerabilities\[RCE] and has IAM role attached with '\[Rolepermission]' permission via IAM policy and '\[S3permission] permission via bucket policy to S3 bucket '\[BucketName]' containing sensitive data <br><br> . For more details, you can learn how to [prioritize security actions by data sensitivity](./information-protection.md). |

+| Internet exposed AWS S3 Bucket with sensitive data is publicly accessible | S3 bucket '\[BucketName]' with sensitive data is reachable from the internet and allows public read access without authorization required. For more details, you can learn how to [prioritize security actions by data sensitivity](./information-protection.md). |

+| Contains sensitive data | Indicates that a resource contains sensitive data based on Microsoft Purview scan and applicable only if Microsoft Purview is enabled. For more details, you can learn how to [prioritize security actions by data sensitivity](./information-protection.md). | Azure SQL Server, Azure Storage Account, AWS S3 bucket. |

+- [What are the cloud security graph, attack path analysis, and the cloud security explorer?](concept-attack-path.md)

+- [Cloud security explorer](how-to-manage-cloud-security-explorer.md)

+ - [Install Azure Arc](../azure-arc/servers/learn/quick-enable-hybrid-vm.md).

+ - The Log Analytics agent isn't uninstalled from machines that already have it installed. You can [leave the Log Analytics agent](#impact-of-running-with-both-the-log-analytics-and-azure-monitor-agents) on the machine, or you can manually [remove the Log Analytics agent](../azure-monitor/agents/azure-monitor-agent-migration.md) if you don't require it for other protections.

+Learn more about [migrating to the Azure Monitor Agent](../azure-monitor/agents/azure-monitor-agent-migration.md).

+The required [Log Analytics workspace solutions](../azure-monitor/insights/solutions.md) for the data that you're collecting are:

+If you want to collect security events when you auto-provision the Azure Monitor Agent, you can create a [Data Collection Rule](../azure-monitor/essentials/data-collection-rule-overview.md) to collect the required events.

+- [File Integrity Monitoring](file-integrity-monitoring-enable-ama.md)

+ Title: What are the cloud security graph, attack path analysis, and the cloud security explorer?

+# What are the cloud security graph, attack path analysis, and the cloud security explorer?

+## What is cloud security graph?

+The cloud security graph is a graph-based context engine that exists within Defender for Cloud. The cloud security graph collects data from your multicloud environment and other data sources. For example, the cloud assets inventory, connections and lateral movement possibilities between resources, exposure to internet, permissions, network connections, vulnerabilities and more. The data collected is then used to build a graph representing your multicloud environment.

+Defender for Cloud then uses the generated graph to perform an attack path analysis and find the issues with the highest risk that exist within your environment. You can also query the graph using the cloud security explorer.

+## What is attack path analysis?

+Attack path analysis is a graph-based algorithm that scans the cloud security graph. The scans expose exploitable paths that attackers may use to breach your environment to reach your high-impact assets. Attack path analysis exposes those attack paths and suggests recommendations as to how best remediate the issues that will break the attack path and prevent successful breach.

+By taking your environment's contextual information into account such as, internet exposure, permissions, lateral movement, and more. Attack path analysis identifies issues that may lead to a breach on your environment, and helps you to remediate the highest risk ones first.

+Learn how to use [attack path analysis](how-to-manage-attack-path.md).

+## What is cloud security explorer?

+Using the cloud security explorer, you can proactively identify security risks in your multicloud environment by running graph-based queries on the cloud security graph. Your security team can use the query builder to search for and locate risks, while taking your organization's specific contextual and conventional information into account.

+Cloud security explorer provides you with the ability to perform proactive exploration features. You can search for security risks within your organization by running graph-based path-finding queries on top the contextual security data that is already provided by Defender for Cloud. Such as, cloud misconfigurations, vulnerabilities, resource context, lateral movement possibilities between resources and more.

+Learn how to use the [cloud security explorer](how-to-manage-cloud-security-explorer.md), or check out the list of [insights and connections](attack-path-reference.md#insights-and-connections).

+The Defender CSPM plan comes with two options, foundational CSPM capabilities and Defender Cloud Security Posture Management (CSPM). When you deploy Defender for Cloud to your subscription and resources, you'll automatically gain the basic coverage offered by the CSPM plan. To gain access to the other capabilities provided by Defender CSPM, you'll need to [enable the Defender Cloud Security Posture Management (CSPM) plan](enable-enhanced-security.md) on your subscription and resources.

+| [Cloud security explorer](#cloud-security-explorer) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS |

+| [Attack path analysis](#attack-path-analysis) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS |

+> If you have enabled Defender for DevOps, you will only gain cloud security graph and attack path analysis to the artifacts that arrive through those connectors.

+## Cloud security explorer

+The cloud security graph is a graph-based context engine that exists within Defender for Cloud. The cloud security graph collects data from your multicloud environment and other data sources. For example, the cloud assets inventory, connections and lateral movement possibilities between resources, exposure to internet, permissions, network connections, vulnerabilities and more. The data collected is then used to build a graph representing your multicloud environment.

+Defender for Cloud then uses the generated graph to perform an attack path analysis and find the issues with the highest risk that exist within your environment. You can also query the graph using the cloud security explorer.

+Learn more about [cloud security explorer](concept-attack-path.md#what-is-cloud-security-explorer)

+## Attack path analysis

+Attack path analysis is a graph-based algorithm that scans the cloud security graph. The scans:

+- expose exploitable paths that attackers may use to breach your environment and reach your high-impact assets

+- provide recommendations for ways to prevent successful breaches

+By taking your environment's contextual information into account such as, internet exposure, permissions, lateral movement, and more, this analysis identifies issues that may lead to a breach on your environment, and helps you to remediate the highest risk ones first.

+Learn more about [attack path analysis](concept-attack-path.md#what-is-attack-path-analysis).

+[What are the cloud security graph, attack path analysis, and the cloud security explorer?](concept-attack-path.md)

+ Title: Regulatory compliance Microsoft cloud security benchmark

+description: Learn about the Microsoft cloud security benchmark and the benefits it can bring to your compliance standards across your multicloud environments.

+# Microsoft cloud security benchmark in Defender for Cloud

+The [Microsoft cloud security benchmark](/security/benchmark/azure/introduction) (MCSB) is automatically assigned to your subscriptions and accounts when you onboard Defender for Cloud. This benchmark builds on the cloud security principles defined by the Azure Security Benchmark and applies these principles with detailed technical implementation guidance for Azure, for other cloud providers (such as AWS and GCP), and for other Microsoft clouds.

+Defender for Cloud has a built-in initiative, [Microsoft cloud security benchmark](/security/benchmark/azure/introduction), that includes all of its security policies. To assess Defender for CloudΓÇÖs policies on your Azure resources, you should create an assignment on the management group, or subscription you want to assess.

+- **Generates a secure score** for your subscriptions based on an assessment of your connected resources compared with the guidance in [Microsoft cloud security benchmark](/security/benchmark/azure/overview). Use the score to understand your security posture, and the compliance dashboard to review your compliance with the built-in benchmark. When you've enabled the enhanced security features, you can customize the standards used to assess your compliance, and add other regulations (such as NIST and Azure CIS) or organization-specific security requirements. You can also apply recommendations, and score based on the AWS Foundational Security Best practices standards.

+- **Analyze and secure your attack paths** through the cloud security graph, which is a graph-based context engine that exists within Defender for Cloud. The cloud security graph collects data from your multicloud environment and other data sources. For example, the cloud assets inventory, connections and lateral movement possibilities between resources, exposure to internet, permissions, network connections, vulnerabilities and more. The data collected is then used to build a graph representing your multicloud environment.

+ Attack path analysis is a graph-based algorithm that scans the cloud security graph. The scans expose exploitable paths that attackers may use to breach your environment to reach your high-impact assets. Attack path analysis exposes those attack paths and suggests recommendations as to how best remediate the issues that will break the attack path and prevent successful breach.

+ By taking your environment's contextual information into account such as, internet exposure, permissions, lateral movement, and more. Attack path analysis identifies issues that may lead to a breach on your environment, and helps you to remediate the highest risk ones first.

+The list of recommendations is enabled and supported by the Microsoft cloud security benchmark. This Microsoft-authored benchmark, based on common compliance frameworks, began with Azure and now provides a set of guidelines for security and compliance best practices for multiple cloud environments. Learn more in [Microsoft cloud security benchmark introduction](/security/benchmark/azure/introduction).

+ - [Cloud security explorer](concept-cloud-security-posture-management.md#cloud-security-explorer)

+ - [Attack path analysis](concept-cloud-security-posture-management.md#attack-path-analysis)

+ - **Track compliance with a range of standards** - Defender for Cloud continuously assesses your hybrid cloud environment to analyze the risk factors according to the controls and best practices in [Microsoft cloud security benchmark](/security/benchmark/azure/introduction). When you enable the enhanced security features, you can apply a range of other industry standards, regulatory standards, and benchmarks according to your organization's needs. Add standards and track your compliance with them from the [regulatory compliance dashboard](update-regulatory-compliance-packages.md).

+ Title: Defender for Azure Cosmos DB | Defender for Cloud in the Field

+description: Learn about Defender for Cloud integration with Azure Cosmos DB.

+# Defender for Azure Cosmos DB | Defender for Cloud in the Field

+**Episode description**: In this episode of Defender for Cloud in the Field, Haim Bendanan joins Yuri Diogenes to talk about Defender for Azure Cosmos DB. Haim explains the rationale behind the use of this plan to protect Azure Cosmos DB databases, the different threat detections that are available with this plan, and the security recommendations that were added. Haim also demonstrates how Defender for Azure Cosmos DB detects a SQL injection attack.

+<br>

+<br>

+<iframe src="https://aka.ms/docs/player?id=94238ff5-930e-48be-ad27-a2fff73e473f" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+- [00:00](https://learn.microsoft.com/shows/mdc-in-the-field/defender-cosmos-db#time=00m00s) - Intro

+- [01:37](https://learn.microsoft.com/shows/mdc-in-the-field/defender-cosmos-db#time=01m37s) - Azure Cosmos DB main use case scenarios

+- [02:30](https://learn.microsoft.com/shows/mdc-in-the-field/defender-cosmos-db#time=02m30s) - Recommendations and alerts in Defender for Azure Cosmos DB

+- [04:30](https://learn.microsoft.com/shows/mdc-in-the-field/defender-cosmos-db#time=04m30s) - SQL Injection detection for Azure Cosmos DB

+- [06:15](https://learn.microsoft.com/shows/mdc-in-the-field/defender-cosmos-db#time=06m15s) - Key extraction detection for Azure Cosmos DB

+- [11:00](https://learn.microsoft.com/shows/mdc-in-the-field/defender-cosmos-db#time=11m00s) - Demonstration

+- [14:30](https://learn.microsoft.com/shows/mdc-in-the-field/defender-cosmos-db#time=14m30s) - Final considerations

+## Recommended resources

+Learn more about [Enable Microsoft Defender for Azure Cosmos DB](https://learn.microsoft.com/azure/defender-for-cloud/defender-for-databases-enable-cosmos-protections?tabs=azure-portal)

+- Subscribe to [Microsoft Security on YouTube](https://www.youtube.com/redirect?event=video_description&redir_token=QUFFLUhqa0ZoTml2Qm9kZ2pjRzNMUXFqVUwyNl80YVNtd3xBQ3Jtc0trVm9QM2Z0NlpOeC1KSUE2UEd1cVJ5aHQ0MTN6WjJEYmNlOG9rWC1KZ1ZqaTNmcHdOOHMtWXRLSGhUTVBhQlhhYzlUc2xmTHZtaUpkd1c4LUQzLWt1YmRTbkVQVE5EcTJIM0Foc042SGdQZU5acVRJbw&q=https%3A%2F%2Faka.ms%2FSubscribeMicrosoftSecurity)

+- Follow us on social media:

+ [LinkedIn](https://www.youtube.com/redirect?event=video_description&redir_token=QUFFLUhqbFk5TXZuQld2NlpBRV9BQlJqMktYSm95WWhCZ3xBQ3Jtc0tsQU13MkNPWGNFZzVuem5zc05wcnp0VGxybHprVTkwS2todWw0b0VCWUl4a2ZKYVktNGM1TVFHTXpmajVLcjRKX0cwVFNJaDlzTld4MnhyenBuUGRCVmdoYzRZTjFmYXRTVlhpZGc4MHhoa3N6ZDhFMA&q=https%3A%2F%2Fwww.linkedin.com%2Fshowcase%2Fmicrosoft-security%2F)

+ [Twitter](https://twitter.com/msftsecurity)

+- Join our [Tech Community](https://aka.ms/SecurityTechCommunity)

+- For more about [Microsoft Security](https://msft.it/6002T9HQY)

+## Next steps

+> [!div class="nextstepaction"]

+> [New AWS Connector in Microsoft Defender for Cloud](episode-one.md)

+> [New AWS Connector in Microsoft Defender for Cloud](episode-eighteen.md)

+| Limitations: | Exemptions can be created only for recommendations included in Defender for Cloud's default initiative, [Microsoft cloud security benchmark](/security/benchmark/azure/introduction), or any of the supplied regulatory standard initiatives. Recommendations that are generated from custom initiatives can't be exempted. Learn more about the relationships between [policies, initiatives, and recommendations](security-policy-concept.md). |

+> Exemptions can be created only for recommendations included in Defender for Cloud's default initiative, Microsoft cloud security benchmark or any of the supplied regulatory standard initiatives. Recommendations that are generated from any custom initiatives assigned to your subscriptions cannot be exempted. Learn more about the relationships between [policies, initiatives, and recommendations](security-policy-concept.md).

+Attack path analysis helps you to address the security issues that pose immediate threats with the greatest potential of being exploited in your environment. Defender for Cloud analyzes which security issues are part of potential attack paths that attackers could use to breach your environment. It also highlights the security recommendations that need to be resolved in order to mitigate it.

+Learn how to [Build queries with cloud security explorer](how-to-manage-cloud-security-explorer.md).

+ Title: Build queries with cloud security explorer

+description: Learn how to build queries in cloud security explorer to find vulnerabilities that exist on your multicloud environment.

+# Cloud security explorer

+By using the cloud security explorer, you can proactively identify security risks in your cloud environment by running graph-based queries on the cloud security graph, which is Defender for Cloud's context engine. You can prioritize your security team's concerns, while taking your organization's specific context and conventions into account.

+With the cloud security explorer, you can query all of your security issues and environment context such as assets inventory, exposure to internet, permissions, lateral movement between resources and more.

+## Build a query with the cloud security explorer

+You can use the cloud security explorer to build queries that can proactively hunt for security risks in your environments.

+ :::image type="content" source="media/concept-cloud-map/cloud-security-explorer.png" alt-text="Screenshot of the cloud security explorer page." lightbox="media/concept-cloud-map/cloud-security-explorer.png":::

+The following information can be queried in the cloud security explorer:

+ categories: 'IaC'

+**Recommendation**: To [enforce FTPS](../app-service/deploy-ftp.md?tabs=portal#enforce-ftps), in the [Microsoft.Web/sites/config resource properties](/azure/templates/microsoft.web/sites/config-web?tabs=json#SiteConfig), add (or update) the *ftpsState* property, setting its value to `"FtpsOnly"` or `"Disabled"` if you don't need FTPS enabled.

+**Recommendation**: To [use HTTPS to ensure, server/service authentication and protect data in transit from network layer eavesdropping attacks](../app-service/configure-ssl-bindings.md#enforce-https), in the [Microsoft.Web/Sites resource properties](/azure/templates/microsoft.web/sites?tabs=json#siteproperties-object), add (or update) the *httpsOnly* property, setting its value to `true`.

+**Recommendation**: To [enforce the latest TLS version](../app-service/configure-ssl-bindings.md#enforce-tls-versions), in the [Microsoft.Web/sites/config resource properties](/azure/templates/microsoft.web/sites/config-web?tabs=json#SiteConfig), add (or update) the *minTlsVersion* property, setting its value to `1.2`.

+**Recommendation**: To [use Managed Identity](../app-service/overview-managed-identity.md?tabs=dotnet), in the [Microsoft.Web/sites resource managed identity property](/azure/templates/microsoft.web/sites?tabs=json#ManagedServiceIdentity), add (or update) the *type* property, setting its value to `"SystemAssigned"` or `"UserAssigned"` and providing any necessary identifiers for the identity if required.

+**Recommendation**: To [enforce FTPS](../app-service/deploy-ftp.md?tabs=portal#enforce-ftps), in the [Microsoft.Web/sites/config resource properties](/azure/templates/microsoft.web/sites/config-web?tabs=json#SiteConfig), add (or update) the *ftpsState* property, setting its value to `"FtpsOnly"` or `"Disabled"` if you don't need FTPS enabled.

+**Recommendation**: To [use HTTPS to ensure, server/service authentication and protect data in transit from network layer eavesdropping attacks](../app-service/configure-ssl-bindings.md#enforce-https), in the [Microsoft.Web/Sites resource properties](/azure/templates/microsoft.web/sites?tabs=json#siteproperties-object), add (or update) the *httpsOnly* property, setting its value to `true`.

+**Recommendation**: To [enforce the latest TLS version](../app-service/configure-ssl-bindings.md#enforce-tls-versions), in the [Microsoft.Web/sites/config resource properties](/azure/templates/microsoft.web/sites/config-web?tabs=json#SiteConfig), add (or update) the *minTlsVersion* property, setting its value to `1.2`.

+**Recommendation**: To [use Managed Identity](../app-service/overview-managed-identity.md?tabs=dotnet), in the [Microsoft.Web/sites resource managed identity property](/azure/templates/microsoft.web/sites?tabs=json#ManagedServiceIdentity), add (or update) the *type* property, setting its value to `"SystemAssigned"` or `"UserAssigned"` and providing any necessary identifiers for the identity if required.

+**Recommendation**: To [enforce FTPS](../app-service/deploy-ftp.md?tabs=portal#enforce-ftps), in the [Microsoft.Web/sites/config resource properties](/azure/templates/microsoft.web/sites/config-web?tabs=json#SiteConfig), add (or update) the *ftpsState* property, setting its value to `"FtpsOnly"` or `"Disabled"` if you don't need FTPS enabled.

+**Recommendation**: To [use HTTPS to ensure server/service authentication and protect data in transit from network layer eavesdropping attacks](../app-service/configure-ssl-bindings.md#enforce-https), in the [Microsoft.Web/Sites resource properties](/azure/templates/microsoft.web/sites?tabs=json#siteproperties-object), add (or update) the *httpsOnly* property, setting its value to `true`.

+To [enforce the latest TLS version](../app-service/configure-ssl-bindings.md#enforce-tls-versions), in the [Microsoft.Web/sites/config resource properties](/azure/templates/microsoft.web/sites/config-web?tabs=json#SiteConfig), add (or update) the *minTlsVersion* property, setting its value to `1.2`.

+**Recommendation**: To [use Managed Identity](../app-service/overview-managed-identity.md?tabs=dotnet), in the [Microsoft.Web/sites resource managed identity property](/azure/templates/microsoft.web/sites?tabs=json#ManagedServiceIdentity), add (or update) the *type* property, setting its value to `"SystemAssigned"` or `"UserAssigned"` and providing any necessary identifiers for the identity if required.

+**Recommendation**: [Use built-in roles such as 'Owner, Contributer, Reader' instead of custom RBAC roles](../role-based-access-control/built-in-roles.md)

+**Recommendation**: [Enable encryption of Automation account variable assets](../automation/shared-resources/variables.md?tabs=azure-powershell)

+**Recommendation**: [Restrict access by defining authorized IP ranges](../aks/api-server-authorized-ip-ranges.md) or [set up your API servers as private clusters](../aks/private-clusters.md)

+**Recommendation**: [Enable RBAC in Kubernetes clusters](../aks/operator-best-practices-identity.md#use-azure-rbac)

+**Recommendation**: To [upgrade Kubernetes service clusters](../aks/upgrade-cluster.md), in the [Microsoft.ContainerService/managedClusters resource properties](/azure/templates/microsoft.containerservice/managedclusters?tabs=json#managedclusterproperties-object), update the *kubernetesVersion* property, setting its value to one of the following versions (making sure to specify the minor version number): 1.11.9+, 1.12.7+, 1.13.5+, or 1.14.0+.

+**Recommendation**: [Enable AAD client authentication on your Service Fabric clusters](../service-fabric/service-fabric-cluster-creation-setup-aad.md)

+Learn how to [connect your Azure DevOps](quickstart-onboard-devops.md) to Defender for Cloud.

+| Required roles and permissions: | - To enable/disable the integration: **Security admin** or **Owner**<br>- To view Defender for Endpoint alerts in Defender for Cloud: **Security reader**, **Reader**, **Resource Group Contributor**, **Resource Group Owner**, **Security admin**, **Subscription owner**, or **Subscription Contributor** |

+Licenses for Defender for Endpoint for servers are included with **Microsoft Defender for Servers**. Alternatively, you can [purchase licenses for Defender for Endpoint](https://www.microsoft.com/en-us/security/business/get-started/contact-us) for servers separately.

+Defender for Servers Plan 1 and Plan 2 provides the capabilities of [Microsoft Defender for Endpoint Plan 2](/microsoft-365/security/defender-endpoint/microsoft-defender-endpoint).

+- Compare your resource configuration against industry standards, regulations, and benchmarks. [Learn more](./update-regulatory-compliance-packages.md) about standards.

+In this article, you've learned how to determine your business needs when designing a multicloud security solution. Continue with the next step to [determine an adoption strategy](plan-multicloud-security-define-adoption-strategy.md).

+- Non-Azure public clouds connect to Azure by leveraging the [Azure Arc](../azure-arc/servers/overview.md) service.

+- The [Azure Connected Machine agent](../azure-arc/servers/agent-overview.md) is installed on multicloud machines that onboard as Azure Arc machines. Defender for Cloud should be enabled in the subscription in which the Azure Arc machines are located.

+- Defender for Cloud leverages the Connected Machine agent to install extensions (such as Microsoft Defender for Endpoint) that are needed for [Defender for Servers](./defender-for-servers-introduction.md) functionality.

+- [Log analytics agent/Azure Monitor Agent (AMA)](../azure-monitor/agents/agents-overview.md) is needed for some [Defender for Service Plan 2](./defender-for-servers-introduction.md) functionality.

+ - If you select to continuously export data, you can drill into and configure the types of events and alerts that are saved. [Learn more](./continuous-export.md?tabs=azure-portal).

+ - There are [several reasons](../azure-monitor/logs/workspace-design.md) to select the default workspace rather than the custom workspace.

+[Defender for Containers](./defender-for-containers-introduction.md) protects your multicloud container deployments running in:

+- **Other Kubernetes distributions** - using [Azure Arc-enabled Kubernetes](../azure-arc/kubernetes/overview.md), which allows you to attach and configure Kubernetes clusters running anywhere, including other public clouds and on-premises.

+- **Agent-based Azure Arc-enabled Kubernetes**: Connects your EKS and GKE clusters to Azure using [Azure Arc agents](../azure-arc/kubernetes/conceptual-agent-overview.md), so that theyΓÇÖre treated as Azure Arc resources.

+For the [Defender for Databases plan](./quickstart-enable-database-protections.md) in a multicloud scenario, you leverage Azure Arc to manage the multicloud SQL Server databases. The SQL Server instance is installed in a virtual or physical machine connected to Azure Arc.

+- The [Azure Connected Machine agent](../azure-arc/servers/agent-overview.md) is installed on machines connected to Azure Arc.

+In this article, you have learned how to determine your data residency requirements when designing a multicloud security solution. Continue with the next step to [determine compliance requirements](plan-multicloud-security-determine-compliance-requirements.md).

+- Learn about the [IAM permissions](./quickstart-onboard-aws.md?pivots=env-settings) needed to discover AWS resources for CSPM.

+- [Defender for Servers](./defender-for-servers-introduction.md): Protect AWS/GCP Windows and Linux machines.

+- [Defender for Containers](./defender-for-containers-introduction.md): Help secure your Kubernetes clusters with security recommendations and hardening, vulnerability assessments, and runtime protection.

+- [Defender for SQL](./defender-for-sql-usage.md): Protect SQL databases running in AWS and GCP.

+ Review the [features of each plan](./defender-for-servers-introduction.md) before onboarding to Defender for Servers.

+To auto-provision the Azure Arc agent, the OS configuration agent on [GCP VM instances](./quickstart-onboard-gcp.md?pivots=env-settings) and the AWS Systems Manager (SSM) agent for [AWS EC2 instances](./quickstart-onboard-aws.md?pivots=env-settings) must be configured. [Learn more](../azure-arc/servers/agent-overview.md) about the agent.

+- **Defender for Endpoint capabilities**: The [Microsoft Defender for Endpoint](./integration-defender-for-endpoint.md?tabs=linux) agent provides comprehensive endpoint detection and response (EDR) capabilities.

+- **Vulnerability assessment**: Using either the integrated [Qualys vulnerability scanner](./deploy-vulnerability-assessment-vm.md), or the [Microsoft threat and vulnerability management](/microsoft-365/security/defender-vulnerability-management/defender-vulnerability-management?view=o365-worldwide) solution.

+- **Log Analytics agent/[Azure Monitor Agent](../azure-monitor/agents/agents-overview.md) (AMA) (in preview)**: Collects security-related configuration information and event logs from machines.

+Machines must meet [network requirements](../azure-arc/servers/network-requirements.md?tabs=azure-cloud) before onboarding the agents. Auto-provisioning is enabled by default.

+The required [components](./defender-for-containers-introduction.md) are as follows:

+ - To auto-provision the Azure Arc agent, the OS configuration agent on [GCP VM instances](./quickstart-onboard-gcp.md?pivots=env-settings) and the AWS Systems Manager (SSM) agent for [AWS EC2 instances](./quickstart-onboard-aws.md?pivots=env-settings) must be configured. [Learn more](../azure-arc/servers/agent-overview.md) about the agent.

+- **Log Analytics agent/[Azure Monitor Agent](../azure-monitor/agents/agents-overview.md) (AMA) (in preview)**: Collects security-related configuration information and event logs from machines

+In this article, you have learned how to determine multicloud dependencies when designing a multicloud security solution. Continue with the next step to [automate connector deployment](plan-multicloud-security-automate-connector-deployment.md).

+ - [Assigning owners with due dates](./governance-rules.md) and [defining governance rules](./governance-rules.md) creates accountability and transparency, as you drive processes to improve security posture.

+In this article, you have learned how to determine ownership requirements when designing a multicloud security solution. Continue with the next step to [determine access control requirements](plan-multicloud-security-determine-access-control-requirements.md).

+- The [default initiative](#defender-for-clouds-default-initiative-microsoft-cloud-security-benchmark) group lists all the Azure Policy definitions that are part of Defender for Cloud's default initiative, [Microsoft cloud security benchmark](/security/benchmark/azure/introduction). This Microsoft-authored, widely respected benchmark builds on controls from the [Center for Internet Security (CIS)](https://www.cisecurity.org/benchmark/azure/) and the [National Institute of Standards and Technology (NIST)](https://www.nist.gov/) with a focus on cloud-centric security.

+## Defender for Cloud's default initiative (Microsoft cloud security benchmark)

+1. By default the **Servers** plan is set to **On**. This is necessary to extend Defender for server's coverage to your AWS EC2. Ensure you've fulfilled the [network requirements for Azure Arc](../azure-arc/servers/network-requirements.md?tabs=azure-cloud).

+- [Troubleshoot your multicloud connectors](troubleshooting-guide.md#troubleshooting-the-native-multicloud-connector)

+To protect your ADO-based resources, you can connect your ADO organizations on the environment settings page in Microsoft Defender for Cloud. This page provides a simple onboarding experience (including auto discovery).

+- **Defender for Cloud's Cloud Security Posture Management (CSPM) features** - Assesses your Azure DevOps resources according to ADO-specific security recommendations. You can also learn about all the [recommendations for DevOps](recommendations-reference.md) resources. Resources are assessed for compliance with built-in standards that are specific to DevOps. Defender for Cloud's [asset inventory page](asset-inventory.md) is a multicloud enabled feature that helps you manage your Azure DevOps resources alongside your Azure resources.

+- **Defender for Cloud's Workload Protection features** - Extends Defender for Cloud's threat detection capabilities and advanced defenses to your Azure DevOps resources.

+| Pricing: | For pricing please see the Defender for Cloud [pricing page](https://azure.microsoft.com/pricing/details/defender-for-cloud/?v=17.23h#pricing). |

+| Required permissions: | **- Azure account:** with permissions to sign into Azure portal <br> **- Contributor:** on the Azure subscription where the connector will be created <br> **- Security Admin Role:** in Defender for Cloud <br> **- Organization Administrator:** in Azure DevOps <br> - In Azure DevOps, configure: Third-party applications gain access via OAuth, which must be set to `On` . [Learn more about OAuth](/azure/devops/organizations/accounts/change-application-access-policies?view=azure-devops)|

+| Regions: | Central US |

+

+ > [!NOTE]

+ > The authorization will automatically login using the session from your browser's tab. After you select **Authorize**, if you don't see the Azure DevOps organizations you expect to see, check whether you are logged in to Microsoft Defender for Cloud in one browser tab and logged in to Azure DevOps in another browser tab.

+ > If you select your relevant project(s) from the drop down menu, you will also need to select auto discover repositories or select individual repositories.

+- Ensure you've fulfilled the [network requirements for Azure Arc](../azure-arc/servers/network-requirements.md?tabs=azure-cloud).

+- [Troubleshoot your multicloud connectors](troubleshooting-guide.md#troubleshooting-the-native-multicloud-connector)

+To protect your GitHub-based resources, you can connect your GitHub organizations on the environment settings page in Microsoft Defender for Cloud. This page provides a simple onboarding experience (including auto discovery).

+- **Defender for Cloud's Cloud Security Posture Management (CSPM) features** - Assesses your GitHub resources according to GitHub-specific security recommendations. You can also learn about all of the [recommendations for DevOps](recommendations-reference.md) resources. Resources are assessed for compliance with built-in standards that are specific to DevOps. Defender for Cloud's [asset inventory page](asset-inventory.md) is a multicloud enabled feature that helps you manage your GitHub resources alongside your Azure resources.

+- **Defender for Cloud's Cloud Workload Protection features** - Extends Defender for Cloud's threat detection capabilities and advanced defenses to your GitHub resources.

+| Pricing: | For pricing please see the Defender for Cloud [pricing page](https://azure.microsoft.com/pricing/details/defender-for-cloud/?v=17.23h#pricing).

+| Required permissions: | **- Azure account:** with permissions to sign into Azure portal <br> **- Contributor:** on the Azure subscription where the connector will be created <br> **- Security Admin Role:** in Defender for Cloud <br> **- Organization Administrator:** in GitHub |

+| Regions: | Central US |

+ > [!NOTE]

+ > The authorization will auto-login using the session from your browser tab. After you select Authorize, if you do not see the GitHub organizations you expect to see, check whether you are logged in to MDC in one browser tab and logged in to GitHub in another browser tab.

+The Defender for DevOps service automatically discovers the repositories you selected and analyzes them for any security issues. The Inventory page populates with your selected repositories, and the Recommendations page shows any security issues related to a selected repository. This can take up to an average of 3 hours.

+- You can learn more about [how Azure and GitHub integrate](/azure/developer/github/).

+Learn how to [configure pull request annotations](tutorial-enable-pull-request-annotations.md) in Defender for Cloud.

+When you enable Defender for Cloud on an Azure subscription, the [Microsoft cloud security benchmark](/security/benchmark/azure/introduction) is automatically assigned to that subscription. This widely respected benchmark builds on the controls from the [Center for Internet Security (CIS)](https://www.cisecurity.org/benchmark/azure/), [PCI-DSS](https://www.pcisecuritystandards.org/) and the [National Institute of Standards and Technology (NIST)](https://www.nist.gov/) with a focus on cloud-centric security.

+[Microsoft cloud security benchmark](/security/benchmark/azure/introduction) (MCSB) is the canonical set of security recommendations and best practices defined by Microsoft, aligned with common compliance control frameworks including [CIS Control Framework](https://www.cisecurity.org/benchmark/azure/), [NIST SP 800-53](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) and PCI-DSS. MCSB is a comprehensive cloud agnostic set of security principles designed to recommend the most up-to-date technical guidelines for Azure along with other clouds such as AWS and GCP. We recommend MCSB to customers who want to maximize their security posture and align their compliance status with industry standards.

+Since weΓÇÖve released the Microsoft cloud security benchmark, many customers have chosen to migrate to it as a replacement for CIS benchmarks.

+By default, the regulatory compliance dashboard shows you the Microsoft cloud security benchmark. The Microsoft cloud security benchmark is the Microsoft-authored, Azure-specific guidelines for security, and compliance best practices based on common compliance frameworks. Learn more in the [Microsoft cloud security benchmark introduction](/security/benchmark/azure/introduction).

+- [Announcing the Microsoft cloud security benchmark](#announcing-the-microsoft-cloud-security-benchmark)

+### Announcing the Microsoft cloud security benchmark

+The [Microsoft cloud security benchmark](/security/benchmark/azure/introduction) (MCSB) is a new framework defining fundamental cloud security principles based on common industry standards and compliance frameworks, together with detailed technical guidance for implementing these best practices across cloud platforms. Replacing the Azure Security Benchmark, the MCSB provides prescriptive details for how to implement its cloud-agnostic security recommendations on multiple cloud service platforms, initially covering Azure and AWS.

+Microsoft cloud security benchmark is automatically assigned to your Azure subscriptions and AWS accounts when you onboard Defender for Cloud.

+Learn more about the [Microsoft cloud security benchmark](/security/benchmark/azure/introduction).

+The new cloud security graph, attack path analysis and contextual cloud security capabilities are now available in Defender for Cloud in preview.

+Learn more about the new [cloud security graph, attack path analysis, and the cloud security explorer](concept-attack-path.md).

+With agentless scanning for VMs, you get wide visibility on installed software and software CVEs, without the challenges of agent installation and maintenance, network connectivity requirements, and performance impact on your workloads. The analysis is powered by Microsoft Defender vulnerability management.

+Security teams can configure pull request annotations to help developers address secret scanning findings in Azure DevOps directly on their pull requests.

+| [ESlint](https://github.com/eslint/eslint) | JavaScript | [MIT License](https://github.com/microsoft/binskim/blob/main/LICENSE) |

+| [Trivy](https://github.com/aquasecurity/trivy) | Container images, file systems, git repositories | [Apache License 2.0](https://github.com/tenable/terrascan/blob/master/LICENSE) |

+The following new recommendations are now available for DevOps security assessments:

+### Regulatory Compliance dashboard now supports manual control management and detailed information on Microsoft's compliance status

+- **Compliance offerings** provide a central location to check Azure, Dynamics 365, and Power Platform products and their respective regulatory compliance certifications.

+- Attack path analysis

+The default initiative automatically assigned to every subscription in Microsoft Defender for Cloud is Microsoft cloud security benchmark. This benchmark is the Microsoft-authored, Azure-specific set of guidelines for security and compliance best practices based on common compliance frameworks. This widely respected benchmark builds on the controls from the [Center for Internet Security (CIS)](https://www.cisecurity.org/benchmark/azure/) and the [National Institute of Standards and Technology (NIST)](https://www.nist.gov/) with a focus on cloud-centric security. Learn more about [Microsoft cloud security benchmark](/security/benchmark/azure/introduction).

+- **View and edit the built-in default initiative** - When you enable Defender for Cloud, the initiative named 'Microsoft cloud security benchmark' is automatically assigned to all Defender for Cloud registered subscriptions. To customize this initiative, you can enable or disable individual policies within it by editing a policy's parameters. See the list of [built-in security policies](./policy-reference.md) to understand the options available out-of-the-box.

+1. Microsoft cloud security benchmark is an ***initiative*** that contains requirements.

+As mentioned above, Defender for Cloud's built in recommendations are based on the Microsoft cloud security benchmark. Almost every recommendation has an underlying policy that is derived from a requirement in the benchmark.

+Some policies in your initiatives might be disabled by default. For example, in the Microsoft cloud security benchmark initiative, some policies are provided for you to enable only if they meet a specific regulatory or compliance requirement for your organization. Such policies include recommendations to encrypt data at rest with customer-managed keys, such as "Container registries should be encrypted with a customer-managed key (CMK)".

+By default, every Azure subscription has the **Microsoft cloud security benchmark** assigned. This is the Microsoft-authored, cloud specific guidelines for security and compliance best practices based on common compliance frameworks. [Learn more about Microsoft cloud security benchmark](/security/benchmark/azure/introduction).

+By default, every AWS connector subscription has the **Microsoft cloud security benchmark (MCSB)** assigned along with the **AWS Foundational Security Best Practices**. MCSB is the Microsoft recommended cloud security best practices based on common compliance frameworks, with detailed guidance for applying to an AWS environment. AWS Foundational Security Best Practices is the AWS-recommended security guidelines.

+- [Microsoft cloud security benchmark](/security/benchmark/azure/introduction)

+For more information, see:

+- [View and manage alerts on the Defender for IoT portal (Preview)](how-to-manage-cloud-alerts.md)

+- [Manage alerts](how-to-manage-the-alert-event.md)

+- [View alerts on your sensor](how-to-view-alerts.md)

+- [Accelerate alert workflows](how-to-accelerate-alert-incident-response.md)

+- [Forward alert information](how-to-forward-alert-information-to-partners.md)

+- [Work with alerts on the on-premises management console](how-to-work-with-alerts-on-premises-management-console.md)

+- [Alert management API reference for on-premises management consoles](api/management-alert-apis.md)

+- [Alert management API reference for OT monitoring sensors](api/sensor-alert-apis.md)

+- [Forward alert information](how-to-forward-alert-information-to-partners.md)

+ Title: Alert management API reference for on-premises management consoles - Microsoft Defender for IoT

+description: Learn about the alert management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

+# Alert management API reference for on-premises management consoles

+This article lists the alert management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

+## alerts (Retrieve alert information)

+Use this API to retrieve all or filtered alerts from an on-premises management console.

+**URI**: `/external/v1/alerts` or `/external/v2/alerts`

+### GET

+# [Request](#tab/alerts-get-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**state** | Get only handled or unhandled alerts. Supported values: <br>- `handled`<br>- `unhandled` <br>All other values are ignored. | `/api/v1/alerts?state=handled` |Optional |

+|**fromTime** | Get alerts created starting at a given time, in milliseconds from Epoch time and in UTC timezone. | `/api/v1/alerts?fromTime=<epoch>` | Optional |

+|**toTime** | Get alerts created only before at a given time, in milliseconds from Epoch time and in UTC timezone. | `/api/v1/alerts?toTime=<epoch>` | Optional |

+|**siteId** | The site on which the alert was discovered. | `/api/v1/alerts?siteId=1` |Optional |

+|**zoneId** | The zone on which the alert was discovered. | `/api/v1/alerts?zoneId=1` |Optional |

+|**sensorId** | The sensor on which the alert was discovered. | `/api/v1/alerts?sensorId=1` |Optional |

+> [!NOTE]

+> You might not have the site and zone ID. If this is the case, first query all devices to retrieve the site and zone ID. For more information, see [Integration API reference for on-premises management consoles (Public preview)](management-integration-apis.md).

+# [Response](#tab/alerts-get-response)

+**Type**: JSON

+A list of alerts with the following fields:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **Id** | Numeric | Not nullable | - |

+| **sensorId** | Numeric | Not nullable | - |

+| **zoneId** | Numeric | Not nullable | - |

+| **time** | Numeric | Not nullable | Milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time), in UTC timezone|

+| **title** | String | Not nullable | - |

+| **message** | String | Not nullable | - |

+| **severity** | String | Not nullable | `Warning`, `Minor`, `Major`, or `Critical` |

+| **engine** | String | Not nullable | `Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`, or `Operational` |

+| **sourceDevice** | Numeric | Nullable | Device ID |

+| **destinationDevice** | Numeric | Nullable | Device ID |

+| **remediationSteps** | String | Nullable | Remediation steps shown in alert|

+| **additionalInformation** | Additional information object | Nullable | - |

+| **handled** | Boolean, state of the alert | Not nullable | `true` or `false` |

+<a name="add-info"></a>**Additional information fields**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **description** | String | Not nullable | - |

+| **information** | JSON array | Not nullable | String |

+**Added for V2**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **sourceDeviceAddress** | String | Nullable | IP or MAC address|

+| **destinationDeviceAddress** | String | Nullable | IP or MAC address |

+| **remediationSteps** | JSON array | Not nullable | Strings, remediation steps described in alert |

+| **sensorName** | String | Not nullable | Name of sensor defined by user |

+|**zoneName** | String | Not nullable | Name of zone associated with sensor|

+| **siteName** | String | Not nullable | Name of site associated with sensor |

+|

+For more information, see [Sensor API version reference](../references-work-with-defender-for-iot-apis.md#sensor-api-version-reference).

+#### Response example

+```rest

+[

+ {

+ "engine": "Operational",

+ "handled": false,

+ "title": "Traffic Detected on sensor Interface",

+ "additionalInformation": null,

+ "sourceDevice": 0,

+ "zoneId": 1,

+ "siteId": 1,

+ "time": 1594808245000,

+ "sensorId": 1,

+ "message": "The sensor resumed detecting network traffic on ens224.",

+ "destinationDevice": 0,

+ "id": 1,

+ "severity": "Warning"

+ },

+ {

+ "engine": "Anomaly",

+ "handled": false,

+ "title": "Address Scan Detected",

+ "additionalInformation": null,

+ "sourceDevice": 4,

+ "zoneId": 1,

+ "siteId": 1,

+ "time": 1594808260000,

+ "sensorId": 1,

+ "message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",

+ "destinationDevice": 0,

+ "id": 2,

+ "severity": "Critical"

+ },

+ {

+ "engine": "Operational",

+ "handled": false,

+ "title": "Suspicion of Unresponsive MODBUS Device",

+ "additionalInformation": null,

+ "sourceDevice": 194,

+ "zoneId": 1,

+ "siteId": 1,

+ "time": 1594808285000,

+ "sensorId": 1,

+ "message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",

+ "destinationDevice": 0,

+ "id": 3,

+ "severity": "Minor"

+ }

+]

+```

+# [cURL command](#tab/alerts-get-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'

+```

+## UUID (Manage alerts based on the UUID)

+Use this API to take specified action on a specific alert detected by Defender for IoT.

+For example, you can use this API to create a forwarding rule that forwards data to QRadar. For more information, see [Integrate Qradar with Microsoft Defender for IoT](../tutorial-qradar.md).

+**URI**: `/external/v1/alerts/<UUID>`

+### PUT

+# [Request](#tab/uuid-request)

+**Type**: JSON

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**UUID** | Defines the universally unique identifier (UUID) for the alert you want to handle or handle and learn. | `/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0` |Required |

+**Body parameters**

+|Name |Description |Example | Required / Optional |

+|||||

+| **action** | String | Either `handle` or `handleAndLearn` | Required |

+**Request example**

+```rest

+{

+ "action": "handle"

+}

+```

+# [Response](#tab/uuid-response)

+**Type**: JSON

+Array of JSON objects that represent devices.

+**Response fields**:

+| Name | Type | Required / Optional | Description |

+|--|--|--|--|

+| **content / error** | String | Required | If the request is successful, the content property appears. Otherwise, the error property appears. |

+**Possible content values**:

+| Status code | Message | Description |

+|--|--|--|

+| **200** | Alert update request finished successfully. | The update request finished successfully. No comments. |

+| **200** | Alert was already handled (**handle**). | The alert was already handled when a handle request for the alert was received.<br />The alert remains **handled**. |

+| **200** | Alert was already handled and learned (**handleAndLearn**). | The alert was already handled and learned when a request to **handleAndLearn** was received.<br />The alert remains in the **handledAndLearn** status. |

+| **200** | Alert was already handled (**handled**).<br />Handle and learn (**handleAndLearn**) was performed on the alert. | The alert was already handled when a request to **handleAndLearn** was received.<br />The alert becomes **handleAndLearn**. |

+| **200** | Alert was already handled and learned (**handleAndLearn**). Ignored handle request. | The alert was already **handleAndLearn** when a request to handle the alert was received. The alert stays **handleAndLearn**. |

+| **500** | Invalid action. | The action that was sent is not a valid action to perform on the alert. |

+| **500** | Unexpected error occurred. | An unexpected error occurred. To resolve the issue, contact Technical Support. |

+| **500** | Couldn't execute request because no alert was found for this UUID. | The specified alert UUID was not found in the system. |

+### Response example: Successful

+```rest

+{

+ "content": "Alert update request finished successfully"

+}

+```

+### Response example: Unsuccessful

+```rest

+{

+ "error": "Invalid action"

+}

+```

+# [cURL command](#tab/uuid-curl)

+**Type**: PUT

+**APIs**:

+```rest

+curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>

+```

+**Example**:

+```rest

+curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

+```

+## maintenanceWindow (Create alert exclusions)

+Manages maintenance windows, under which alerts won't be sent. Use this API to define and update stop and start times, devices, or subnets that should be excluded when triggering alerts, or define and update Defender for IoT engines that should be excluded.

+For example, during a maintenance window, you might want to stop alert delivery of all alerts, except for malware alerts on critical devices.

+The maintenance windows that define with the `maintenanceWindow` API appear in the on-premises management console's Alert Exclusions window as a read-only exclusion rule, named with the following syntax: `Maintenance-{token name}-{ticket ID}`.

+> [!IMPORTANT]

+> This API is supported for maintenance purposes only and for a limited time period, and is not meant to be used instead of [alert exclusion rules](../how-to-work-with-alerts-on-premises-management-console.md#create-alert-exclusion-rules). Use this API for one-time, temporary maintenance operations only.

+**URI**: `/external/v1/maintenanceWindow`

+### POST

+Creates a new maintenance window.

+# [Request](#tab/maintenanceWindow-request-post)

+**Body parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**ticketId** | String. Defines the maintenance ticket ID in the user's systems. Make sure that the ticket ID is not linked to an existing open window. | `2987345p98234` | Required |

+|**ttl** | Positive integer. Defines the TTL (time to live), which is the duration of the maintenance window, in minutes. After the defined time period is completed, the maintenance window is over and the system behaves normally again. | `180`| Required|

+|**engines** | JSON array of strings. Defines which engine to suppress alerts from during the maintenance window. Possible values: <br><br> - `ANOMALY`<br> - `MALWARE`<br> - `OPERATIONAL`<br> - `POLICY_VIOLATION`<br> - `PROTOCOL_VIOLATION` | `ANOMALY,OPERATIONAL`| Optional|

+|**sensorIds** | JSON array of strings. Defines which sensors to suppress alerts from during the maintenance window. You can get these sensor IDs from the [appliances (Manage OT sensor appliances)](management-appliances-apis.md#appliances-manage-ot-sensor-appliances) API. | `1,35,63`| Optional |

+|**subnets** | JSON array of strings. Defines the subnets to suppress alerts from during the maintenance window. Define each subnet in a CIDR notation. | `192.168.0.0/16,138.136.80.0/14,112.138.10.0/8` | Optional|

+# [Response](#tab/maintenanceWindow-response-post)

+| Status code | Message | Description |

+|--|--|--|

+|**201 (Created)** | - | The action was successfully completed. |

+|**400 (Bad Request)** | No TicketId | API request was missing a `ticketId` value.|

+|**400 (Bad Request)** | Illegal TTL | API request included a non-positive or non-numeric TTL value. |

+|**400 (Bad Request)** | Couldn't parse request. | Issue parsing the body, such as incorrect parameters or invalid values.|

+|**400 (Bad Request)** | Maintenance window with same parameters already exists. | Appears when an existing maintenance window already exists with the same details. |

+|**404 (Not Found)** | Unknown sensor ID | One of the sensors listed in the request doesn't exist. |

+|**409 (Conflict)** | Ticket ID already has an open window. | The ticket ID is linked to another open maintenance window. |

+|**500 (Internal Server Error)** | - | Any other unexpected error. |

+# [cURL command](#tab/maintenanceWindow-post-curl)

+**Type**: POST

+**API**:

+```rest

+curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

+```

+**Example**:

+```rest

+curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

+```

+### DELETE

+Closes an existing maintenance window.

+# [Request](#tab/maintenanceWindow-delete-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**ticketId** | Defines the maintenance ticket ID in the user's systems. Make sure that the ticket ID is linked to an existing open window. | `2987345p98234` |Required |

+# [Response](#tab/maintenanceWindow-delete-response)

+**Error codes**:

+|Code | Message |Description |

+||||

+|**200 (OK)** | - | The action was successfully completed. |

+|**400 (Bad Request)** | No TicketId | The **ticketId** parameter is missing from the request. |

+|**404 (Not Found)**: | Maintenance window not found. | The ticket ID is not linked to an open maintenance window. |

+|**500 (Internal Server Error)** | - | Any other unexpected error. |

+# [cURL command](#tab/maintenanceWindow-delete-curl)

+**Type**: DELETE

+**API**:

+```rest

+curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

+```

+**Example**:

+```rest

+curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

+```

+### GET

+Retrieve a log of all the *open* ([POST](#post)), *close* ([DELETE](#delete)), and *update* ([PUT](#put)) actions that were performed using this API for handling maintenance windows. T

+# [Request](#tab/maintenanceWindow-request-put)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+| **fromDate** | Filters the logs from the predefined date and later. The format is `YYYY-MM-DD`.|`2022-08-10` |Optional |

+| **toDate** | Filters the logs up to the predefined date. The format is `YYYY-MM-DD`. |`2022-08-10` | Optional|

+| **ticketId** | Filters the logs related to a specific ticket ID. | `9a5fe99c-d914-4bda-9332-307384fe40bf` |Optional |

+| **tokenName** | Filters the logs related to a specific token name. | quarterly-sanity-window |Optional |

+**Error codes**:

+|Code |Message | Description |

+||||

+|**200** | OK | The action was successfully completed. |

+|**204**: | No Content | There is no data to show. |

+|**400** | Bad Request | The date format is incorrect. |

+|**500** | Internal Server Error | Any other unexpected error. |

+# [Response](#tab/maintenanceWindow-response-put)

+**Type**: JSON

+Array of JSON objects that represent maintenance window operations.

+**Response structure**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **id** | Long integer | Not nullable | An internal ID for the current log |

+| **dateTime** | String | Not nullable | The time that the activity occurred, for example: `2022-04-23T18:25:43.511Z `|

+| **ticketId** | String | Not nullable | The maintenance window ID. For example: `9a5fe99c-d914-4bda-9332-307384fe40bf` |

+| **tokenName** | String | Not nullable | The maintenance window token name. For example: `quarterly-sanity-window` |

+| **engines** | Array of strings | Nullable | The engines on which the maintenance window applies, as supplied during maintenance window creation: `Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`, or `Operational` |

+| **sensorIds** | Array of string | Nullable| The sensors on which the maintenance window applies, as supplied during maintenance window creation. |

+| **subnets** | Array of string | Nullable | The subnets on which the maintenance window applies, as supplied during maintenance window creation.|

+| **ttl** | Numeric | Nullable | The maintenance window's Time to Live (TTL), as supplied during maintenance window creation or update. |

+| **operationType** | String | Not nullable | One of the following values: `OPEN`, `UPDATE`, and `CLOSE` |

+# [cURL command](#tab/maintenanceWindow-get-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'

+```

+### PUT

+Allows you to update the maintenance window duration after you start the maintenance process by changing the `ttl` parameter. The new duration definition overrides the previous one.

+This method is useful when you want to set a longer duration than the currently configured duration. For example, if you've originally defined 180 minutes, 90 minutes have passed, and you want to add another 30 minutes, update the `ttl` to `120` minute to reset the duration count.

+# [Request](#tab/maintenanceWindow-put-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**ticketId** | String. Defines the maintenance ticket ID in the user's systems. | `2987345p98234` | Required |

+|**ttl** | Positive integer. Defines the duration of the window in minutes. | `210` | Required |

+# [Response](#tab/maintenanceWindow-put-response)

+**Error codes**:

+|Code | Message |Description |

+||||

+|**200 (OK)** | - | The action was successfully completed. |

+|**400 (Bad Request)** | No TicketId | The request is missing a `ticketId` value. |

+|**400 (Bad Request)** | Illegal TTL | The TTL defined is not numeric or not a positive integer. |

+|**400 (Bad Request)** | Couldn't parse request | The request is missing a `ttl` parameter value. |

+|**404 (Not Found)** | Maintenance window not found | The ticket ID is not linked to an open maintenance window. |

+|**500 (Internal Server Error)** | - | Any other unexpected error. |

+# [cURL command](#tab/maintenanceWindow-put-curl)

+**Type**: PUT

+**API**:

+```rest

+curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

+```

+**Example**:

+```rest

+curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

+```

+## pcap (Request alert PCAP)

+Use this API to request a PCAP file related to an alert.

+**URI**: `/external/v2/alerts/`

+### GET

+# [Request](#tab/pcap-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**id** | Alert ID from the on-premises management console | `/external/v2/alerts/pcap/<id>` | Required |

+# [Response](#tab/pcap-response)

+**Type**: JSON

+Message string with the operation status details:

+| Status code | Message | Description |

+|--|--|--|

+|**200 (OK)** | - | JSON object with data about the requested PCAP file. For more information, see [Data fields](#data-fields). |

+|**500 (Internal Server Error)**| Alert not found | The supplied alert ID wasn't found on the on-premises management console. |

+|**500 (Internal Server Error)**| Error while getting token for xsense id `<number>` | An error occurred when getting the sensor's token for the specified sensor ID |

+|**500 (Internal Server Error)**| - | Any other unexpected error. |

+#### Data fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+|**id**|Numeric|Not nullable| The on-premises management console alert ID |

+|**xsenseId**|Numeric|Not nullable| The sensor ID |

+|**xsenseAlertId**|Numeric|Not nullable| The sensor console alert ID |

+|**downloadUrl**|String|Not nullable| The URL used to download the PCAP file |

+|**token**|String|Not nullable| The sensor's token, to be used when downloading the PCAP file |

+### Response example: Success

+```json

+{

+ "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",

+ "xsenseId": 1,

+ "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",

+ "id": 1,

+ "xsenseAlertId": 1

+}

+```

+### Response example: Error

+```json

+{

+ "error": "alert not found"

+}

+```

+# [cURL command](#tab/pcap-curl)

+**Type**: GET

+**APIs**

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'

+```

+***Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

+```

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).

+ Title: Appliance management API reference for on-premises management consoles - Microsoft Defender for IoT

+description: Learn about the appliance management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

+# Appliance management API reference for on-premises management consoles

+This article lists the appliance management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

+## appliances (Manage OT sensor appliances)

+Use this API to manage your OT sensor appliances from an on-premises management console.

+**URI**: `/external/v1/appliances` or `/external/v2/appliances`

+### GET

+# [Request](#tab/appliances-get-request)

+No query parameters

+# [Response](#tab/appliances-get-response)

+**Type**: JSON

+A JSON array of appliance objects that represent sensor appliances.

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **id** | Long integer | Not nullable | The sensor ID |

+| **name** | String | Not nullable | The sensor's name |

+|**interfaceAddress** | String | Not nullable | The sensor's console URL |

+| **state** | JSON array | Not nullable | A JSON array that describes the sensor's connection status. For more information, see [XsenseState fields](#xsensestate-fields). |

+| **version** | String | Not nullable | The software version currently installed on the sensor. |

+|**alertCount** | Long integer | Not nullable |The total number of alerts currently active on the sensor. |

+| **deviceCount** |Long integer |Not nullable |The number of devices currently detected by the sensor. |

+| **unhandledAlertsCount** | long | Not nullable | The current number of unhandled alerts on the sensor. |

+| **isActivated** | Boolean |Not nullable | One of the following: `Activated` or `Unactivated` |

+|**dataIntelligenceVersion** | String |Not nullable | The version of threat intelligence data currently installed on the sensor |

+|**upgradeStatus** | JSON array | Not nullable | A JSON array that describes the sensor's update status. For more information, see [UpgradeStatusBean fields](#upgradestatusbean-fields).|

+|**upgradeFinishTime** | Long |Nullable | The time the last software update completed, in the following format: `YYYY-MM-DD` |

+|**hasLog** | Boolean | Not nullable | Defines whether an upgrade log exists for the sensor. |

+|**zoneId** | Long integer | Nullable | The ID of sensor's zone. |

+| **isInLearningMode**| Boolean | Not nullable | Defines whether the sensor is currently in learning mode. |

+#### XsenseState fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **id** | Long integer | Not nullable | An internal, auto-incremented ID on the on-premises management console database. |

+| **xsenseId** | Long integer | Not nullable | The sensor ID. |

+| **connectionState** | A JSON array of datetime values | Not nullable | One of the following: `SYNCED`, `OUT_OF_SYNC`, `TIME_DIFF_OFFSET`, `DISCONNECTED` |

+| **cmSyncedUntil** | DateTime | Not nullable | The timestamp for the most recent data sent from the sensor. |

+| **sensorSyncedUntil** | DateTime | Not nullable | The timestamp for the last update from the on-premises management console to the sensor.|

+| **sensorLastMessage** | DateTime | Not nullable | The timestamp for the last update from the sensor. |

+#### UpgradeStatusBean fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **startTime** | DateTime | Not nullable | The time the last update process was started. |

+| **percentage** | Integer between 0-100 | Not nullable | The completion percentage of the last update process. |

+| **stage** | String | Not nullable | One of the following statues: <br><br>- `UPLOADING`: Uploading Package<br>- `PREPARE_TO_INSTALL`: Preparing To Install<br>- `STOPPING_PROCESSES` Stopping Processes<br>- `BACKING_UP_DATA`: Backing Up Data<br>- `TAKING_SNAPSHOT`: Taking Snapshot<br>- `UPDATING_CONFIGURATION`: Updating Configuration<br>- `UPDATING_DEPENDENCIES`: Updating Dependencies<br>- `UPDATING_LIBRARIES`: Updating Libraries<br>- `PATCHING_DATABASES`: Patching Databases<br>- `STARTING_PROCESSES`: Starting Processes<br>- `VALIDATING_SYSTEM_SANITY`: Validating System Sanity<br>- `VALIDATION_SUCCEEDED_REBOOTING`: Validation Succeeded<br>- `SUCCESS`: Success<br>- `FAILURE`: Failure<br>- `UPGRADE_STARTED`: Upgrade Started<br>- `STARTING_INSTALLATION`: Starting Installation<br>- `INSTALLING_OPERATING_SYSTEM`: Installing OS |

+#### Response example

+```rest

+[

+ {

+ "dataIntelligenceVersion":"Dec 22, 2021",

+ "name":"Microsoft Defender for IoT",

+ "isActivated":true,

+ "hasLog":false,

+ "zoneId":null,

+ "upgradeStatus":null,

+ "deviceCount":22,

+ "state":{

+ "sensorLastMessage":1660217831000,

+ "xsenseId":1,

+ "sensorSyncedUntil":1660217741000,

+ "connectionState":{

+ "isConsideredConnected":true,

+ "id":1,

+ "description":"Connection is successful"

+ },

+ "cmSyncedUntil":1660217825000,

+ "id":1

+ },

+ "version":"22.1.4.8-r-6372aad",

+ "alertCount":9,

+ "upgradeFinishTime":null,

+ "uid":"a6218f1a-8ebf-4bb3-8613-c859b17eef01",

+ "interfaceAddress":"https://173.70.549.76",

+ "id":1,

+ "unhandledAlertsCount":9

+ }

+]

+```

+# [cURL command](#tab/appliances-get-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/appliances'

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/appliances'

+```

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).

+ Title: Authentication and password management API reference for on-premises management consoles - Microsoft Defender for IoT

+description: Learn about the authentication and password management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

+# Authentication and password management API reference for on-premises management consoles

+This article lists the authentication and password management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

+## set_password (Change password)

+Use this API to let users change their own passwords. All Defender for IoT user roles can work with the API.

+You don't need a Defender for IoT access token to use this API.

+**URI**: `/external/authentication/set_password`

+### POST

+# [Request](#tab/request-set-password)

+**Type**: JSON

+**Example**:

+```rest

+request:

+{

+ "username": "test",

+ "password": "Test12345\!",

+ "new_password": "Test54321\!"

+}

+```

+#### Request parameters

+| **Name** | **Type** | **Required / Optional** |

+|--|--|--|

+| **username** | String | Required |

+| **password** | String | Required |

+| **new_password** | String | Required |

+# [Response](#tab/response-set-password)

+**Type**: JSON

+|Message |Description |

+|||

+|**Success ΓÇô msg** | Password has been replaced |

+|**Failure ΓÇô error** | User authentication failure |

+|**Failure ΓÇô error** | Password does not match security policy |

+#### Response example

+```rest

+response:

+{

+ "error": {

+ "userDisplayErrorMessage": "User authentication failure"

+ }

+}

+```

+# [cURL command](#tab/set-password-curl)

+**Type**: POST

+**API**:

+```rest

+curl -k -d '{"username": "<USER_NAME>","password": "<CURRENT_PASSWORD>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/external/authentication/set_password

+```

+**Example**:

+```rest

+curl -k -d '{"username": "myUser","password": "1234@abcd","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/external/authentication/set_password

+```

+## set_password_by_admin (User password update by system admin)

+Use this API to let system administrators change passwords for specified users. Defender for IoT admin user roles can work with the API.

+You don't need a Defender for IoT access token to use this API.

+**URI**: `/external/authentication/set_password_by_admin`

+### POST

+# [Request](#tab/set-password-by-admin-request)

+**Type**: JSON

+#### Request example

+```rest

+request:

+{

+ "admin_username": "admin",

+ "admin_password: "Test0987"

+ "username": "test",

+ "new_password": "Test54321\!"

+}

+```

+#### Request parameters

+| **Name** | **Type** | **Required / Optional** |

+|--|--|--|

+| **admin_username** | String | Required |

+| **admin_password** | String | Required |

+| **username** | String | Required |

+| **new_password** | String | Required |

+# [Response](#tab/set-password-by-admin-response)

+**Type**: JSON

+Message string with the operation status details:

+|Message |Description |

+|||

+|**Success ΓÇô msg** | Password has been replaced |

+|**Failure ΓÇô error** | User authentication failure |

+|**Failure ΓÇô error** | User does not exist |

+|**Failure ΓÇô error** | Password doesn't match security policy |

+|**Failure ΓÇô error** | User does not have the permissions to change password |

+#### Response example

+```rest

+response:

+{

+ "error": {

+ "userDisplayErrorMessage": "The user 'test_user' doesn't exist",

+ "internalSystemErrorMessage": "The user 'yoavfe' doesn't exist"

+ }

+}

+```

+#### Device fields

+| **Name** | **Type** | **Required / Optional** |

+|--|--|--|

+| **admin_username** | String | Required |

+| **admin_password** | String | Required |

+| **username** | String | Required |

+| **new_password** | String | Required |

+# [cURL command](#tab/set-password-by-admin-curl)

+**Type**: POST

+**API**:

+```rest

+curl -k -d '{"admin_username":"<ADMIN_USERNAME>","admin_password":"<ADMIN_PASSWORD>","username": "<USER_NAME>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/external/authentication/set_password_by_admin

+```

+**Example**:

+```rest

+curl -k -d '{"admin_user":"adminUser","admin_password": "1234@abcd","username": "myUser","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/external/authentication/set_password_by_admin

+```

+## validation (Authenticate user credentials)

+Use this API to validate user credentials.

+You don't need a Defender for IoT access token to use this API.

+**URI**: `/external/authentication/validation`

+### POST

+# [Request](#tab/validation-request)

+**Type**: JSON

+#### Query parameters

+| **Name** | **Type** | **Required/Optional** |

+|--|--|--|

+| **username** | String | Required |

+| **password** | String | Required |

+#### Request example

+```rest

+request:

+{

+ "username": "test",

+ "password": "Test12345\!"

+}

+```

+# [Response](#tab/validation-response)

+**Type**: JSON

+Message string with the operation status details:

+|Message |Description |

+|||

+|**Success - msg** | Authentication succeeded |

+|**Failure - error** | Credentials validation failed |

+#### Response example

+```rest

+response:

+{

+ "msg": "Authentication succeeded."

+}

+```

+# [cURL command](#tab/validation-curl)

+**Type**: POST

+**API**:

+```rest

+curl -k -X POST -H "Authorization: <AUTH_TOKEN>" -H "Content-Type: application/json" -d '{"username": <USER NAME>, "password": <PASSWORD>}' https://<IP_ADDRESS>/external/authentication/validation

+```

+**Example**:

+```rest

+curl -k -X POST -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" -H "Content-Type: application/json" -d '{"username": "test", "password": "test"}' https://127.0.0.1/external/authentication/validation

+```

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).

+ Title: Integration API reference for on-premises management consoles - Microsoft Defender for IoT

+description: Learn about the APIs supported for integrating Microsoft Defender for IoT with partner services, such as ServiceNow.

+# Integration API reference for on-premises management consoles (Public preview)

+This article lists the APIs supported for integrating Microsoft Defender for IoT with partner services.

+For example, this API is currently implemented with [Tutorial: Integrate ServiceNow with Microsoft Defender for IoT](../tutorial-servicenow.md), via the ServiceNow Service Graph Connector for Defender for IoT.

+> [!NOTE]

+> Integration APIs are meant to run continuously and create a constantly running data stream, such as to query for new data from the last five minutes. Integration APIs return data with a timestamp.

+>

+> To simply query data, use the regular, non-integration APIs instead, for either an on-premises management console to query all devices, or for a specific sensor to query devices from that sensor only. For more information, see [Defender for IoT API reference](../references-work-with-defender-for-iot-apis.md).

+**URI**: `/external/v3/integration/`

+## devices (Create and update devices)

+This API returns data about all devices that were updated after the given timestamp.

+**URI**: `/external/v3/integration/devices/<timestamp>`

+**URI parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**timestamp** | The start time from which results are returned, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone. | `/external/v3/integration/devices/1664781014000` | Required |

+### GET

+# [Request](#tab/devices-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**sensorId** | Return only devices seen by a specific sensor. Use the ID value from the results of the [sensors (Get sensors)](#sensors-get-sensors) API. | `1` | Optional |

+|**notificationType** | Determines the types of devices to return. Supported values include: <br>- `0`: Both updated and new devices (default). <br>- `1`: Only new devices. <br>- `2`: Only updated devices. | `2` | Optional |

+|**page** | Defines the number where the result page numbering begins. For example, `0`= first page is **0**. <br>Default = `0`| `0` | Optional |

+|**size** |Defines the page sizing. Default = `50` | `75` | Optional |

+# [Response](#tab/devices-response)

+**Type**: JSON

+**Response fields**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+|**u_count** | Integer | Not nullable | The number of objects in the full result set, including all pages. |

+|**u_devices** |JSON array of device objects |Not nullable | An array of device objects, as defined by the [device (Get details for a device)](#device-get-details-for-a-device) API. |

+#### Response example

+```rest

+{

+ "u_devices": [{

+ "u_operating_system": "",

+ "u_ip_address_objects": [{

+ "u_ip_address": "10.10.50.5",

+ "u_guessed_mac_addresses": [{

+ "u_mac_address": "00:02:a2:1f:1c:59"

+ }]

+ }],

+ "u_zone": "asd",

+ "u_name": "10.10.50.5",

+ "u_mac_address_objects": [{

+ "u_mac_address": "00:02:a2:1f:1c:59"

+ }],

+ "u_last_update": 1664782919000,

+ "u_vendor": "HILSCHER GMBH",

+ "u_cm_device_url": "https://<IP address>/#/sites/1/zones/1/devices-maps?devices=1",

+ "u_sensor_ids": [{

+ "u_sensor_id": 1

+ }],

+ "u_appliance": "Management console (CM)",

+ "u_site": "asd",

+ "u_device_type": {

+ "u_category": "ICS",

+ "u_purdue_layer": "Process Control",

+ "u_name": "PLC"

+ },

+ "u_firmwares": [],

+ "u_last_activity": 1664782791000,

+ "u_purdue_layer": "N/A",

+ "u_device_urls": [{

+ "u_device_url": "https://<IP address>9/#/assets/highlight/1"

+ }],

+ "u_vlans": [{

+ "u_vlan": "1"

+ }],

+ "u_groups": ["asd"],

+ "u_first_discovered": 1664781051000,

+ "u_id": 1,

+ "u_protocol_objects": [{

+ "u_protocol": "MODBUS"

+ }]

+ }, {

+ "u_operating_system": "",

+ "u_ip_address_objects": [{

+ "u_ip_address": "10.10.20.10",

+ "u_guessed_mac_addresses": [{

+ "u_mac_address": "00:02:a2:1f:02:ba"

+ }]

+ }],

+ "u_zone": "asd",

+ "u_name": "10.10.20.10",

+ "u_mac_address_objects": [{

+ "u_mac_address": "00:02:a2:1f:02:ba"

+ }],

+ "u_last_update": 1664782859000,

+ "u_vendor": "HILSCHER GMBH",

+ "u_cm_device_url": "https://<IP address>/#/sites/1/zones/1/devices-maps?devices=50",

+ "u_sensor_ids": [{

+ "u_sensor_id": 1

+ }],

+ "u_appliance": "Management console (CM)",

+ "u_site": "asd",

+ "u_device_type": {

+ "u_category": "ICS",

+ "u_purdue_layer": "Process Control",

+ "u_name": "PLC"

+ },

+ "u_firmwares": [],

+ "u_last_activity": 1664782786000,

+ "u_purdue_layer": "N/A",

+ "u_device_urls": [{

+ "u_device_url": "https://<IP address>9/#/assets/highlight/50"

+ }],

+ "u_vlans": [{

+ "u_vlan": "1"

+ }],

+ "u_groups": ["asd"],

+ "u_first_discovered": 1664781052000,

+ "u_id": 50,

+ "u_protocol_objects": [{

+ "u_protocol": "MODBUS"

+ }]

+ }],

+ "u_count": 204

+}

+```

+# [cURL command](#tab/devices-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/devices/<Timestamp>"

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/devices/<Timestamp>"

+```

+## connections (Get device connections)

+This API returns data about all device connections that were updated after the given timestamp.

+**URI**: `/external/v3/integration/connections/<timestamp>`

+**URI parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**timestamp** | The start time from which results are returned, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone. | `/external/v3/integration/devices/1664781014000` | Required |

+### GET

+# [Request](#tab/connections-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**page** | Defines the number where the result page numbering begins. For example, `0`= first page is **0**. <br>Default = `0`| `0` | Optional |

+|**size** |Defines the page sizing. Default = `50` | `75` | Optional |

+# [Response](#tab/connections-response)

+**Type**: JSON

+**Response fields**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+|**u_count** | Integer | Not nullable | The number of objects in the full result set, including all pages. |

+|**u_connections** |JSON array of connection objects |Not nullable | An array of [connection](#connections-fields) objects|

+### connections fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_appliance** | String | Not nullable | The name of the sensor that discovered the connection. |

+| **u_src_device_id** |Integer | Not nullable | The ID of the connection's source device. |

+| **u_src_device_name** | String | Not nullable | The name of the connection's source device. |

+| **u_dest_device_id** |Integer | Not nullable | The ID of the connection's destination device. |

+| **u_dest_device_name** | String | Not nullable | The name of the connection's destination device. |

+| **u_connection_type** | String | Not nullable | One of the following: `One Way`, `Two Way`, `Multicast` |

+#### Response example

+```rest

+{

+ "u_count": 106,

+ "u_connections": [{

+ "u_src_device_id": 103,

+ "u_dest_device_name": "10.10.10.16",

+ "u_src_device_name": "10.10.10.18",

+ "u_appliance": "Management console (CM)",

+ "u_connection_type": "Two Way",

+ "u_dest_device_id": 95

+ }, {

+ "u_src_device_id": 115,

+ "u_dest_device_name": "10.10.10.64",

+ "u_src_device_name": "10.10.10.30",

+ "u_appliance": "Management console (CM)",

+ "u_connection_type": "Two Way",

+ "u_dest_device_id": 19

+ }, {

+ "u_src_device_id": 176,

+ "u_dest_device_name": "10.10.45.7",

+ "u_src_device_name": "10.10.45.100",

+ "u_appliance": "Management console (CM)",

+ "u_connection_type": "Two Way",

+ "u_dest_device_id": 134

+ },

+```

+# [cURL command](#tab/connections-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/connections/1664781014000"

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/connections/1664781014000"

+```

+## device (Get details for a device)

+This API returns data about a specific device per a given device ID.

+**URI**: `/external/v3/integration/device/{deviceId}`

+### GET

+# [Request](#tab/device-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**deviceId** | The ID of the requested device on the on-premises management console | `1` |Required |

+# [Response](#tab/device-response)

+**Type**: JSON

+**Response fields**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_id** | Long integer | Not nullable | The device's ID on the on-premises management console. |

+| **u_vendor** |String | Nullable | The device's vendor name. |

+| **u_appliance** | String | Not nullable | The name of the sensor that detected the device. |

+| **u_mac_address_objects** |JSON array of strings | Not nullable | An array of **u_mac_address** values, listing the device's MAC addresses. |

+| **u_groups** | JSON array of strings | Not nullable | An array of the groups that contains the device. |

+| **u_site** | String | Not nullable | The name of the device's site. |

+| **u_zone** | String | Not nullable | The name of the device's site. |

+| **u_last_activity** | DateTime |Not nullable | The timestamp of the last time the device was active. |

+| **u_first_discovered** | DateTime| Not nullable | The timestamp of the device's discovery time. |

+| **u_device_type** |String |Not nullable | The device [type](sensor-inventory-apis.md#supported-type-values) |

+| **u_name** | String| Not nullable| Defines the device name. |

+| **u_ip_address_objects** |JSON array of IP addresses | Not nullable | Array of [IP address](#ip_address_object-fields) objects |

+| **u_mac_address_objects** |JSON array of MAC addresses | Not nullable | Array of [MAC address](#mac_address_object-fields) objects |

+| **u_protocol_objects** | JSON array of protocols | Not nullable | An array of [protocol](#protocol_object-fields) objects |

+| **u_vlans** |JSON array of VLAN objects | Not nullable | An array of [VLAN](#vlan_object-fields) objects |

+| **u_purdue_layer** | String | Not nullable |Defines the default [Purdue layer](../plan-network-monitoring.md#purdue-reference-model-and-defender-for-iot) for this device type. |

+| **u_sensor_ids** |JSON array of sensor ID objects |Not nullable | An array of [sensor ID](#sensor_id_object-fields) objects |

+| **u_cm_device_url** |String |Not nullable | The URL used to access the device on the on-premises management console. |

+| **u_device_urls** |JSON array of URL objects |Not nullable | An array of [device URL](#device_url_object-fields) objects |

+| **u_last_update** | Long integer |Not nullable | Defines the timestamp of the device's last update time. |

+| **u_firmwares** |JSON array of firmware objects | Not nullable | An array of [firmware](#firmware_object-fields) objects|

+### ip_address_object fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_ip_address** | String | Not nullable | One of the device's IP addresses |

+| **u_guessed_mac_address** | String | Not nullable | The guessed MAC addresses associated with the IP address |

+### mac_address_object fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_mac_address** | String | Not nullable | One of the device's MAC addresses. |

+### protocol_object fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_protocol** | String | Not nullable | One of the protocols used by the device. |

+### vlan_object fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_vlan** | String | Not nullable | One of the VLANs where the device is found. |

+### sensor_id_object fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_sensor_id** | String | Not nullable | The ID of the sensor that detected the device.|

+### device_url_object fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_device_url** | String | Not nullable | The URLs used to view the device on the on-premises management console.|

+### firmware_object fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_appliance** | String | Not nullable | The name of the on-premises management console that manages the device. |

+| **u_id** | Long integer | Not nullable | The ID of the device on the on-premises management console |

+| **u_asset** | String | Not nullable | The name of the device |

+| **u_address** | String | Not nullable | The device's firmware address |

+| **u_module_address** | String | Nullable | The device's firmware module address |

+| **u_serial** | String | Nullable | The device's firmware serial number |

+| **u_model** | String | Nullable | The device's firmware model |

+| **u_version** | String | Nullable | The device's firmware version |

+| **u_additional_data** | String | Nullable | The device's firmware vendor-specific additional data |

+#### Response example

+```rest

+[{

+ "u_operating_system": "",

+ "u_ip_address_objects": [{

+ "u_ip_address": "10.10.50.5",

+ "u_guessed_mac_addresses": [{

+ "u_mac_address": "00:02:a2:1f:1c:59"

+ }]

+ }],

+ "u_zone": "asd",

+ "u_name": "10.10.50.5",

+ "u_mac_address_objects": [{

+ "u_mac_address": "00:02:a2:1f:1c:59"

+ }],

+ "u_last_update": 1664782919000,

+ "u_vendor": "HILSCHER GMBH",

+ "u_cm_device_url": "https://<IP address>/#/sites/1/zones/1/devices-maps?devices=1",

+ "u_sensor_ids": [{

+ "u_sensor_id": 1

+ }],

+ "u_appliance": "Management console (CM)",

+ "u_site": "asd",

+ "u_device_type": {

+ "u_category": "ICS",

+ "u_purdue_layer": "Process Control",

+ "u_name": "PLC"

+ },

+ "u_firmwares": [],

+ "u_last_activity": 1664782791000,

+ "u_purdue_layer": "N/A",

+ "u_device_urls": [{

+ "u_device_url": "https://<IP address>9/#/assets/highlight/1"

+ }],

+ "u_vlans": [{

+ "u_vlan": "1"

+ }],

+ "u_groups": ["asd"],

+ "u_first_discovered": 1664781051000,

+ "u_id": 1,

+ "u_protocol_objects": [{

+ "u_protocol": "MODBUS"

+ }]

+}]

+```

+# [cURL command](#tab/device-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/device/<device ID>"

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/device/1"

+```

+## deleteddevices (Get deleted devices)

+This API returns a list of IDs of recently deleted devices, from the supplied timestamp.

+**URI**: `/external/v3/integration/deleteddevices/`

+### GET

+# [Request](#tab/deleteddevices-request)

+**URI parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**timestamp** | The start time from which results are returned, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone. | `/external/v3/integration/deleteddevices/1664781014000` | Required |

+# [Response](#tab/deleteddevices-response)

+**Type**: JSON array of deleted devices

+**Deleted device fields**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_id** | Long integer | Not nullable | An ID of a deleted device |

+#### Response example

+```rest

+[{

+ "u_id": 192

+}, {

+ "u_id": 66

+}, {

+ "u_id": 4

+}, {

+ "u_id": 22

+}, {

+ "u_id": 24

+}]

+```

+# [cURL command](#tab/deleteddevices-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/deleteddevices/<timestamp>"

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/deleteddevices/1664781014000"

+```

+## sensors (Get sensors)

+This API returns a list of sensor objects for connected OT network sensors.

+**URI**: `/external/v3/integration/sensors/`

+### GET

+# [Request](#tab/sensors-request)

+**URI**: `/sensors`

+No query parameters

+# [Response](#tab/sensors-response)

+**Type**: JSON

+**Response fields**:

+An array of the following fields:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+|**u_id** | Long integer | Not nullable | Defines the internal sensor ID, to be used in the [devices (Create and update devices)](#devices-create-and-update-devices) API.|

+| **u_name** | String | Not nullable | Defines the sensor appliance's name. |

+| **u_interface_address** | String | Not nullable | Defines the sensor appliance's network address.|

+|**u_connection_state** |String |Not nullable | Defines the device's connection state with an on-premises management console, using one of the following values: <br><br>- **SYNCED**: Connection is successful. <br>- `OUT_OF_SYNC`: On-premises management console cannot process data received from the sensor. <br>- `TIME_DIFF_OFFSET`: Time drift detected. On-premises management console has been disconnected from the sensor. <br>`DISCONNECTED`: Sensor not communicating with management console. Check network connectivity. |

+|**u_version** | String | Not nullable | A string representation of the sensor's software version. |

+| **u_alert_count** | Long integer | Not nullable | The current number of alerts triggered by the sensor. |

+| **u_device_count** | Long integer | Not nullable | The current number of devices detected by the sensor. |

+| **u_unhandled_alert_count** |Long integer | Not nullable | The current number of currently unhandled alerts on the sensor. |

+| **u_is_activated** | Boolean | Not nullable | Defines whether the sensor is activated. |

+| **u_data_intelligence_version** |String | Not nullable |A string representation of the threat intelligence version installed on the sensor. |

+| **u_uid** |String | Not nullable | Defines the sensor's globally unique identifier. |

+| **u_zone_id** | Long integer | Nullable | Define's the device's zone. |

+| **u_is_in_learning_mode** | Boolean | Not nullable | Determines whether the sensor is in learning mode. |

+| **u_remote_upgrade_stage** | String |Nullable |Defines a current stage in a version update process as one of the following: <br> - `UPLOADING` <br>- `PREPARE_TO_INSTALL` <br>- `STOPPING_PROCESSES` <br>- `BACKING_UP_DATA` <br>- `TAKING_SNAPSHOT` <br>- `UPDATING_CONFIGURATION` <br>- `UPDATING_DEPENDENCIES` <br>- `UPDATING_LIBRARIES` <br>- `PATCHING_DATABASES` <br>- `STARTING_PROCESSES` <br>- `VALIDATING_SYSTEM_SANITY` <br>- `VALIDATION_SUCCEEDED_REBOOTING` <br>- `SUCCESS` <br>- `FAILURE` <br>- `UPGRADE_STARTED` <br>- `STARTING_INSTALLATION` <br>- `INSTALLING_OPERATING_SYSTEM`|

+#### Response example

+```rest

+[

+ {

+ u_connection_state: "SYNCED",

+ u_uid: "fab58081-1fde-4d3f-8eea-9aa723abbd55",

+ u_name: "Microsoft Defender for IoT",

+ u_is_activated: true,

+ u_alert_count: 6,

+ u_device_count: 202,

+ u_interface_address: "https://<IP address>9",

+ u_zone_id: 1,

+ u_data_intelligence_version: "May 26, 2022",

+ u_is_in_learning_mode: false,

+ u_unhandled_alert_count: 6,

+ u_remote_upgrade_stage: "",

+ u_id: 1,

+ u_version: "22.2.5.7-r-2121448",

+ },

+];

+```

+# [cURL command](#tab/sensors-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <Authorization token>" "https://<IP Address>/external/v3/integration/sensors"

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/sensors"

+```

+## devicecves (Get device CVEs)

+This API returns a list of active CVEs for all devices that were updated since the supplied timestamp.

+**URI**: `/external/v3/integration/devicecves/`

+### GET

+# [Request](#tab/devicecves-request)

+**URI**: `/external/v3/integration/devicecves/<timestamp>`

+#### URI parameters

+|Name |Description |Example | Required / Optional |

+|||||

+|**timestamp** | The start time from which results are returned, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone. | `/external/v3/integration/devicecves/1664781014000` | Required |

+#### Query parameters

+|Name |Description |Example | Required / Optional |

+|||||

+|**page** | Defines the number where the result page numbering begins. | `0`= first page is **0**. <br>Default = `0`| Optional |

+|**size** |Defines the page sizing. | Default = `50` | Optional |

+|**sensorId** | Shows results from a specific sensor, as defined by the given sensor ID. | `1` | Optional |

+| **score** | Determines a minimum CVE score to be retrieved. All results will have a CVE score equal to or greater than the given value. | Default = `0`. | Optional |

+| **deviceIds** | A comma-separated list of device IDs from which you want to show results. | For example: `1232,34,2,456` | Optional |

+# [Response](#tab/devicecves-response)

+**Type**: Count and JSON array of device CVEs

+#### Response fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+|**u_count** | Integer | Not nullable | The number of objects in the full result set, including all pages. |

+| **u_device_cves** | JSON array of device CVE objects | Not nullable | An array of [device CVE objects](#device-cve-fields)|

+#### Device CVE fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_id** | Integer | Not nullable | The device's ID in the on-premises management console. |

+| **u_name** | String | Not nullable | The device's name.|

+| **u_ip_address_objects** | JSON array of IP address objects | Not nullable | Array of [u_ip_address](#u_ip_address_objects-fields) values, defining the devices IP addresses. |

+| **u_mac_address_objects** | JSON array of MAC address objects | Not nullable | An array of [u_mac_address](#u_mac_address_objects-fields) values, listing the device's MAC addresses. |

+| **u_last_activity** | Integer | Not nullable | Timestamp of the last time traffic was seen from or to the device. |

+| **u_last_update** | Integer | Not nullable | The timestamp of the last time a property was changed on the device, including both user changes and automated system changes. |

+|**u_cves** | JSON array of CVEs | Not nullable | An array of [CVE details](#u_cves-fields) objects |

+> [!NOTE]

+> If Defender for IoT can confidently identify the MAC address of one of its IP addresses, the MAC address is returned in the `u_mac_address_objects` field directly.

+>

+> If Defender for IoT is not entirely confident about a MAC address, such as if the traffic has been routed via a router, the MAC address is returned in the `u_guessed_mac_address` field instead, as part of the JSON array of IP addresses.

+#### u_ip_address_objects fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_ip_address** | String | Not nullable | One of the device's IP addresses |

+| **u_guessed_mac_address** | JSON array of MAC address objects | Not nullable | JSON array of [MAC addresses](#u_mac_address_objects-fields) |

+#### u_mac_address_objects fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **u_mac_address** | String | Not nullable | One of the device's MAC addresses |

+#### u_cves fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+|**u_address** |String | Not nullable | Address of the specific interface, with the specific firmware where the CVE was detected. |

+| **u_cve_id**| String| Not nullable | Defines the CVE ID |

+|**u_score** | String| Not nullable | Defines the CVE risk score |

+| **u_attack_vector**|String | Not nullable | Defines the attack vector as one of the following: `ADJACENT_NETWORK`, `LOCAL`, `NETWORK` |

+| **u_description**| String| Not nullable | Defines the CVE description|

+#### Response example

+```rest

+{

+ "u_count": 2,

+ "u_device_cves": [{

+ "u_ip_address_objects": [{

+ "u_ip_address": "192.168.1.127",

+ "u_guessed_mac_addresses": [{

+ "u_mac_address": "00:0f:38:67:4f:1c"

+ }]

+ }],

+ "u_name": "192.168.1.127",

+ "u_mac_address_objects": [{

+ "u_mac_address": "00:0f:38:67:4f:1c"

+ }],

+ "u_last_update": 1664787209000,

+ "u_last_activity": 1664782792000,

+ "u_id": 135,

+ "u_cves": [{

+ "u_cve_id": "CVE-2015-2373",

+ "u_score": "10.0",

+ "u_ip_address": "192.168.1.127",

+ "u_description": "The Remote Desktop Protocol (RDP) server service in Microsoft Windows 7 SP1, Windows 8, and Windows Server 2012 allows remote attackers to execute arbitrary code via a series of crafted packets, aka \"Remote Desktop Protocol (RDP) Remote Code Execution Vulnerability.\"",

+ "u_attack_vector": "NETWORK"

+ }, {

+ "u_cve_id": "CVE-2015-1635",

+ "u_score": "10.0",

+ "u_ip_address": "192.168.1.127",

+ "u_description": "HTTP.sys in Microsoft Windows 7 SP1, Windows Server 2008 R2 SP1, Windows 8, Windows 8.1, and Windows Server 2012 Gold and R2 allows remote attackers to execute arbitrary code via crafted HTTP requests, aka \"HTTP.sys Remote Code Execution Vulnerability.\"",

+ "u_attack_vector": "NETWORK"

+ }, {

+ "u_cve_id": "CVE-2015-0014",

+ "u_score": "10.0",

+ "u_ip_address": "192.168.1.127",

+ "u_description": "Buffer overflow in the Telnet service in Microsoft Windows Server 2003 SP2, Windows Vista SP2, Windows Server 2008 SP2 and R2 SP1, Windows 7 SP1, Windows 8, Windows 8.1, and Windows Server 2012 Gold and R2 allows remote attackers to execute arbitrary code via crafted packets, aka \"Windows Telnet Service Buffer Overflow Vulnerability.\"",

+ "u_attack_vector": "NETWORK"

+ }]

+ }, {

+ "u_ip_address_objects": [{

+ "u_ip_address": "10.13.10.5",

+ "u_guessed_mac_addresses": [{

+ "u_mac_address": "00:05:f0:00:0f:cd"

+ }]

+ }],

+ "u_name": "10.13.10.5",

+ "u_mac_address_objects": [{

+ "u_mac_address": "00:05:f0:00:0f:cd"

+ }],

+ "u_last_update": 1664787149000,

+ "u_last_activity": 1664782792000,

+ "u_id": 181,

+ "u_cves": [{

+ "u_cve_id": "CVE-2016-7182",

+ "u_score": "10.0",

+ "u_ip_address": "10.13.10.5",

+ "u_description": "The Graphics component in Microsoft Windows Vista SP2; Windows Server 2008 SP2 and R2 SP1; Windows 7 SP1; Windows 8.1; Windows Server 2012 Gold and R2; Windows RT 8.1; Windows 10 Gold, 1511, and 1607; Office 2007 SP3; Office 2010 SP2; Word Viewer; Skype for Business 2016; Lync 2013 SP1; Lync 2010; Lync 2010 Attendee; and Live Meeting 2007 Console allows attackers to execute arbitrary code via a crafted True Type font, aka \"True Type Font Parsing Elevation of Privilege Vulnerability.\"",

+ "u_attack_vector": "NETWORK"

+ }, {

+ "u_cve_id": "CVE-2016-3270",

+ "u_score": "10.0",

+ "u_ip_address": "10.13.10.5",

+ "u_description": "The Graphics component in the kernel in Microsoft Windows Vista SP2; Windows Server 2008 SP2 and R2 SP1; Windows 7 SP1; Windows 8.1; Windows Server 2012 Gold and R2; Windows RT 8.1; and Windows 10 Gold, 1511, and 1607 allows local users to gain privileges via a crafted application, aka \"Win32k Elevation of Privilege Vulnerability.\"",

+ "u_attack_vector": "NETWORK"

+ }, {

+ "u_cve_id": "CVE-2016-3266",

+ "u_score": "10.0",

+ "u_ip_address": "10.13.10.5",

+ "u_description": "The kernel-mode drivers in Microsoft Windows Vista SP2, Windows Server 2008 SP2 and R2 SP1, Windows 7 SP1, Windows 8.1, Windows Server 2012 Gold and R2, Windows RT 8.1, and Windows 10 Gold, 1511, and 1607 allow local users to gain privileges via a crafted application, aka \"Win32k Elevation of Privilege Vulnerability,\" a different vulnerability than CVE-2016-3376, CVE-2016-7185, and CVE-2016-7211.",

+ "u_attack_vector": "NETWORK"

+ }]

+ }]

+}

+```

+# [cURL command](#tab/devicecves-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <Authorization token>" "https://<IP Address>/external/v3/integration/devicecves/<timestamp>"

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/devicecves/1664781014000"

+```

+## Next steps

+For more information, see:

+- [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md)

+- [Tutorial: Integrate ServiceNow with Microsoft Defender for IoT](../tutorial-servicenow.md)

+ Title: Inventory management API reference for on-premises management consoles - Microsoft Defender for IoT

+description: Learn about the inventory management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

+# Inventory management API reference for on-premises management consoles

+This article lists the inventory management REST APIs supported for Microsoft Defender for IoT on-premises management consoles

+## devices (Retrieve all device information)

+This API requests a list of all devices detected by Defender for IoT sensors that are connected to an on-premises management console.

+**URI**: `/external/v1/devices`

+### GET

+# [Request](#tab/appliances-get-request)

+**Query parameters**:

+|Name |Description |Example | Required / Optional |

+|||||

+|**authorized** | Boolean. Filters by whether the device is authorized or not. | `/external/v1/devices?authorized=true` <br><br>`/external/v1/devices?authorized=false`| Optional |

+|**siteId** | Comma separated list of long integers. Filter devices for specified sites by site ID. | `/external/v1/devices?siteId=1,2`| Optional |

+|**zoneId** |Comma separated list of long integers. Filter devices for specified zones by zone ID. | `/external/v1/devices?zoneId=5,6` | Optional |

+|**sensorId** | Comma separated list of long integers. Filter devices for specified sensors by sensor ID. | `/external/v1/devices?sensorId=8`| Optional |

+> [!TIP]

+> If you don't have a site, zone, or sensor ID, query all devices first to retrieve these values.

+>

+# [Response](#tab/devices-get-response)

+**Type**: JSON

+Array of JSON objects that represent devices.

+**Device fields**

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **id** | Long integer | Not nullable | Device ID on the on-premises management console |

+| **sensorId** | Long integer | Not nullable | Device ID on the sensor |

+| **zoneId** | Long integer | Not nullable | The device's zone ID |

+| **siteId** | Long integer | Not nullable | The device's site ID |

+| **ipAddresses** | JSON array of strings | Nullable | JSON array of IP addresses. Each device can have multiple addresses in case of internet addresses or a device with multiple NICs. |

+| **name** | String | Not nullable | The device name. |

+| **type** | String | Not nullable | The device type. For more information see [Supported `type` values](sensor-inventory-apis.md#supported-type-values).|

+| **macAddresses** | JSON array of strings | Nullable | JSON array of MAC addresses. Devices with multiple NICs can have multiple addresses. |

+| **operatingSystem** | String | Nullable | The device operating system.|

+| **engineeringStation** | Boolean | Not nullable | `True` or `false` |

+| **scanner** | Boolean | Not nullable | `True` or `false` |

+| **authorized** | Boolean | Not nullable | `True` or `false` |

+| **vendor** | String | Nullable | The device vendor.|

+| **Protocols** | JSON array | Nullable | JSON array of protocol objects. For more information, see [Protocol fields](#protocol-fields). |

+| **firmware** | JSON array | Nullable | JSON array of firmware objects. For more information, see [Firmware fields](#firmware-fields). |

+### Protocol fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **Name** | String | Not nullable | The protocol name |

+| **Addresses** | JSON array of protocol addresses | Not nullable | `Master`, `N/A`, or a numeric representation of the protocol address |

+### Firmware fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **serial** | String | Not nullable | `N/A`, or the firmware serial number |

+| **model** | String | Not nullable | `N/A`, or the firmware model |

+| **firmwareVersion** | Double | Not nullable | `N/A`, or the firmware version |

+| **additionalData** | String | Not nullable | `N/A` or additional, vendor-specific firmware data |

+| **moduleAddress** | String | Not nullable | `N/A`, or the firmware module address |

+| **rack** | String | Not nullable | `N/A`, or the firmware rack |

+| **slot** | String | Not nullable | `N/A`, or the firmware slot |

+| **address** | String | Not nullable | `N/A`, or the firmware address |

+### Response example

+```rest

+[

+ {

+ "sensorId": 7,

+ "zoneId": 1,

+ "siteId": 1,

+ "vendor": null,

+ "name": "10.4.14.102",

+ "firmware": [

+ {

+ "slot": "N/A",

+ "additionalData": "N/A",

+ "moduleAddress": "Network: Local network (0), Node: 0, Unit: CPU (0x0)",

+ "rack": "N/A",

+ "address": "10.4.14.102",

+ "model": "AAAAAAAAAA",

+ "serial": "N/A",

+ "firmwareVersion": "20.55"

+ },

+ {

+ "slot": "N/A",

+ "additionalData": "N/A",

+ "moduleAddress": "Network: Local network (0), Node: 0, Unit: Unknown (0x3)",

+ "rack": "N/A",

+ "address": "10.4.14.102",

+ "model": "AAAAAAAAAAAAAAAAAAAA",

+ "serial": "N/A",

+ "firmwareVersion": "20.55"

+ },

+ {

+ "slot": "N/A",

+ "additionalData": "N/A",

+ "moduleAddress": "Network: Local network (0), Node: 3, Unit: CPU (0x0)",

+ "rack": "N/A",

+ "address": "10.4.14.102",

+ "model": "AAAAAAAAAAAAAAAAAAAA",

+ "serial": "N/A",

+ "firmwareVersion": "20.55"

+ },

+ {

+ "slot": "N/A",

+ "additionalData": "N/A",

+ "moduleAddress": "Network: 3, Node: 0, Unit: CPU (0x0)",

+ "rack": "N/A",

+ "address": "10.4.14.102",

+ "model": "AAAAAAAAAAAAAAAAAAAA",

+ "serial": "N/A",

+ "firmwareVersion": "20.55"

+ }

+],

+"id": 79,

+"macAddresses": null,

+"authorized": true,

+"ipAddresses": [

+ "10.4.14.102"

+],

+"engineeringStation": false,

+"type": "PLC",

+"operatingSystem": null,

+"protocols": [

+ {

+ "addresses": [],

+ "id": 62,

+ "name": "Omron FINS"

+ }

+],

+"scanner": false

+}

+]

+```

+# [cURL command](#tab/devices-get-curl)

+**Type**: GET

+**APIs**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/devices?siteId=&zoneId=&sensorId=&uthorized='

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/devices?siteId=1&zoneId=2&sensorId=5&authorized=true'

+```

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).

+ Title: Alert management API reference for OT monitoring sensors - Microsoft Defender for IoT

+description: Learn about the alert management REST APIs supported for Microsoft Defender for IoT OT monitoring sensors.

+# Alert management API reference for OT monitoring sensors

+This article lists the alert management REST APIs supported for Microsoft Defender for IoT OT monitoring sensors.

+## alerts (Retrieve alert information)

+Use this API to request a list of all the alerts that the Defender for IoT sensor has detected.

+**URI**: `/api/v1/alerts`

+### GET

+# [Request](#tab/alerts-request)

+#### Query parameters

+|Name |Description |Example | Required / Optional |

+|||||

+|**state** | Get only handled or unhandled alerts. Supported values: <br>- `handled`<br>- `unhandled` | `/api/v1/alerts?state=handled` |Optional |

+|**fromTime** | Get alerts created starting at a given time, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone. | `/api/v1/alerts?fromTime=<epoch>` | Optional |

+|**toTime** | Get alerts created only before at a given time, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone. | `/api/v1/alerts?toTime=<epoch>` | Optional |

+|**type** | Get alerts of a specific type only. Supported values: <br>- `unexpected new devices` <br>- `disconnections` <br>All other values are ignored. | `/api/v1/alerts?type=disconnections` |Optional |

+# [Response](#tab/alerts-response)

+**Type**: JSON

+A list of alerts with the following fields:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **ID** | Numeric | Not nullable | - |

+| **time** | Numeric | Not nullable | Milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time), in UTC timezone |

+| **title** | String | Not nullable | - |

+| **message** | String | Not nullable | - |

+| **severity** | String | Not nullable | `Warning`, `Minor`, `Major`, or `Critical` |

+| **engine** | String | Not nullable | `Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`, or `Operational` |

+| **sourceDevice** | Numeric | Nullable | Device ID |

+| **destinationDevice** | Numeric | Nullable | Device ID |

+| **additionalInformation** | [Additional information object](#additional-information-fields) | Nullable | - |

+#### Additional information fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **description** | String | Not nullable | - |

+| **information** | JSON array | Not nullable | String |

+**Added for V2**:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **sourceDeviceAddress** | String | Nullable | IP or MAC address|

+| **destinationDeviceAddress** | String | Nullable | IP or MAC address |

+| **remediationSteps** | JSON array | Not nullable | Strings, remediation steps described in alert |

+For more information, see [Sensor API version reference](../references-work-with-defender-for-iot-apis.md#sensor-api-version-reference).

+#### Response example

+```rest

+[

+ {

+ "engine": "Policy Violation",

+ "severity": "Major",

+ "title": "Internet Access Detected",

+ "additionalinformation": {

+ "information": [

+ "170.60.50.201 over port BACnet (47808)"

+ ],

+ "description": "External Addresses"

+ },

+ "sourceDevice": null,

+ "destinationDevice": null,

+ "time": 1509881077000,

+ "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",

+ "id": 1

+ },

+ {

+ "engine": "Protocol Violation",

+ "severity": "Major",

+ "title": "Illegal MODBUS Operation (Exception Raised by Master)",

+ "sourceDevice": 3,

+ "destinationDevice": 4,

+ "time": 1505651605000,

+ "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",

+ "id": 2,

+ "additionalInformation": null,

+ }

+]

+```

+# [cURL command](#tab/alerts-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

+```

+## events (Retrieve timeline events)

+Use this API to request a list of events reported to the event timeline.

+> [!NOTE]

+> Running the identical API within the same hour, with the exact same parameter values, returns a cached value. If you are running this API twice in an hour, we recommend that you modify the query parameters to get an updated response.

+>

+**URI**: `/api/v1/events`

+### GET

+# [Request](#tab/events-request)

+#### Query parameters

+|Name |Description |Example | Required / Optional |

+|||||

+|**minutesTimeFrame** | Filter results by a given time frame during which events were reported. Defined backwards from the current time. <br>Maximum = `4320` (3 days). Any larger value is treated as 4320, with no error | `/api/v1/events?minutesTimeFrame=20` |Optional |

+|**type** | Filter results for a specific type only. Any value other than supported types is ignored. For more information, see [Event `type` and `title` reference](#event-type-and-title-reference). | `/api/v1/events?type=DEVICE_CONNECTION_CREATED` <br><br> `/api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame`|Optional |

+# [Response](#tab/events-response)

+**Type**: JSON

+Array of JSON objects that represent the latest 100 events, sorted by event timestamp, with the latest event first.

+Event fields include:

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|--|

+| **timestamp** | Numeric | Not nullable | Milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time), in UTC timezone |

+| **type** | String | Not nullable | One of the [supported types](#event-type-and-title-reference) |

+| **title** | String | Not nullable | One of the [supported titles](#event-type-and-title-reference) |

+| **severity** | String | Not nullable | `INFO`, `NOTICE`, or `ALERT` |

+| **owner** | String | Nullable | String. If the event was created manually, this field will include the username that created the event. |

+| **content** | String | Not nullable | String that describes the event. |

+#### Response example

+```rest

+[

+ {

+ "severity": "INFO",

+ "title": "Back to Normal",

+ "timestamp": 1504097077000,

+ "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",

+ "owner": null,

+ "type": "BACK_TO_NORMAL"

+ },

+ {

+ "severity": "ALERT",

+ "title": "Alert Detected",

+ "timestamp": 1504096909000,

+ "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",

+ "owner": null,

+ "type": "ALERT_REPORTED"

+ },

+ {

+ "severity": "ALERT",

+ "title": "Alert Detected",

+ "timestamp": 1504094446000,

+ "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",

+ "owner": null,

+ "type": "ALERT_REPORTED"

+ },

+ {

+ "severity": "NOTICE",

+ "title": "PLC Program Update",

+ "timestamp": 1504094344000,

+ "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",

+ "owner": null,

+ "type": "PROGRAM_DEVICE"

+ }

+]

+```

+# [cURL command](#tab/events-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

+```

+## Event `type` and `title` reference

+This section lists the values supported as event *type* and *title* values for the [events](#events-retrieve-timeline-events) API.

+| Event type | Event title |

+| - | - |

+| DEVICE_CREATE | Device Detected |

+| DEVICE_UPDATE | Device Updated |

+| ALERT_REPORTED | Alert Detected |

+| ALERT_UPDATED | Alert Updated |

+| SCAN | Scan Device Detected |

+| PROGRAM_DEVICE | PLC Programming |

+| MMS_PROGRAM_DEVICE | PLC Program Update |

+| SCL_UPLOADED | SCL Uploaded |

+| EXCLUSION_RULE_CREATED | Exclusion Rule Created |

+| EXCLUSION_RULE_REMOVED | Exclusion Rule Removed |

+| EXCLUSION_RULE_UPDATED | Exclusion Rule Updated |

+| DEVICE_CONNECTION_CREATED | Device Connection Detected |

+| USER_LOGIN | User Login Attempt |

+| FILE_TRANSFER | File Transfer Detected |

+| CUSTOM_EVENT | User Defined Event |

+| REMOTE_ACCESS | Remote Access Connection Established |

+| BACK_TO_NORMAL | Back to Normal |

+| MMS_MEMORY_BLOCK_OPERATION | MMS Memory Block Operation |

+| MMS_PROGRAM_OPERATION | MMS Program Operation |

+| HTTP_BASIC_AUTHENTICATION | HTTP Basic Authentication |

+| SIEMENS_S_7_MEMORY_BLOCK_OPERATION | Siemens S7 Memory Block Operation |

+| SIEMENS_S_7_AUTHENTICATION | Siemens S7 Authentication |

+| REPORT_CREATED | Report Created |

+| SNMP_TRAP | SNMP Trap detected |

+| DATABASE_ACTION | Database Structure Manipulation |

+| PLC_MODULE_CHANGE | PLC Module Change |

+| FIRMWARE_UPDATE | Firmware Update |

+| PLC_START | PLC Start |

+| SRTP_PLC_RESET | PLC Reset |

+| SRTP_PLC_COPY_FIRMWARE | Firmware Update |

+| SRTP_LOGIN_PROGRAMMING | PLC Programming Mode Set |

+| SRTP_PLC_CHANGE_PASSWORD | PLC Password Change |

+| OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION | OPC Data Access Group Management Operation |

+| OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION | OPC Data Access Item Management Operation |

+| OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION | OPC Data Access IO Subscription Management Operation |

+| OPC_AE_EVENT_SUBSCRIPTION | OPC AE Event Subscription |

+| OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION | OPC AE Event Condition Management Operation |

+| OPC_AE_EVENT | OPC AE Event |

+| SRTP_CHANGE_PRIVILEGE | PLC Change access level |

+| SRTP_CHANGE_LEVEL_FAILED | PLC Change access level failed |

+| SUITELINK_INIT_CONNECTION | Wonderware session initialized |

+| USER_OPERATION | User Operation |

+| DIP_UPLOADED | Data Intelligence Package Uploaded |

+| FTP_AUTHENTICATION_FAILURE | FTP Authentication Failure |

+| PROFINET_DPC_VALUE_SET | Profinet SET operation |

+| S7PLUS_PLC_MODE_CHANGE | PLC Mode Change |

+| S7_PLC_MODE_CHANGE | PLC Mode Change |

+| DELETE_DEVICE | Device Deleted |

+| S7PLUS_PROGRAMMING | PLC Programming |

+| FIRMWARE_CHANGED | PLC Firmware Changed |

+| DELTAV_PROGRAMMING | DeltaV Install Script |

+| USER_DEFINED_RULE_CREATED | User Defined Rule Created |

+| USER_DEFINED_RULE_EDITED | User Defined Rule Edited |

+| USER_DEFINED_RULE_DELETED | User Defined Rule Deleted |

+| USER_DEFINED_RULE_OPERATION | User Defined Rule Operation |

+| REMOTE_PROCESS_EXECUTION | Remote Process Execution |

+| DEVICE_UNIFICATION | Device Updated |

+| NOTIFICATION | Notification was resolved manually |

+| ENIP_CONTROLLER_PROGRAM_DELETE | Controller Program Delete |

+| ENIP_CONTROLLER_PROGRAM_RESET | Controller Program Reset |

+| ENIP_CONTROLLER_GENERIC_RESET | Controller Reset |

+| ENIP_CONTROLLER_GENERIC_STOP | Controller Stop |

+| ENIP_CONTROLLER_GENERIC_START | Controller Start |

+| TELNET_AUTHENTICATION_FAILURE | Telnet Authentication Failure |

+| CONFIGURATION_OF_CLEARTEXT_PASSWORD | Configuration Of Cleartext Password |

+| CLEARTEXT_AUTHENTICATION | Cleartext Authentication |

+| PROGRAM_UPLOAD_DEVICE | PLC Program Upload |

+| CONFIGURATION_CHANGE | PLC Configuration Write |

+| CONFIGURATION_READ | PLC Configuration Read |

+| SYSLOG_MSG | Syslog Message |

+| INTERNET_ACCESS | Internet Access |

+| CAMP_MEMORY_WRITE_OPERATION | Common ASCII Message Protocol Memory Write Operation |

+| MUTED_ALERT | Event Detected and Muted |

+| DHCP_UPDATE | Address Update |

+| DIP_FAILURE | Data Intelligence Package Installation Failure |

+| DELETE_DEVICE_SCHEDULE | Inactive Devices Scheduled for deletion |

+| PLC_OPERATING_MODE_CHANGED | PLC Operating Mode Change Detected |

+| HARDWARE_UPDATE_BY_IDENTIFIER | Address Update |

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).

+ Title: Authentication and password management API reference for OT monitoring sensors - Microsoft Defender for IoT

+description: Learn about the authentication and password management REST APIs supported for Microsoft Defender for IoT OT monitoring sensors.

+# Authentication and password management API reference for OT monitoring sensors

+This article lists the authentication and password management APIs supported for Defender for IoT OT sensors.

+## set_password (Change your password)

+Use this API to let users change their own passwords.

+You don't need a Defender for IoT access token to use this API.

+**URI**: `/external/authentication/set_password`

+### POST

+# [Request](#tab/set-password-request)

+**Type**: JSON

+**Example**:

+```rest

+request:

+{

+ "username": "test",

+ "password": "Test12345\!",

+ "new_password": "Test54321\!"

+}

+```

+#### Request parameters

+| **Name** | **Type** | **Required / Optional** |

+|--|--|--|

+| **username** | String | Required |

+| **password** | String | Required |

+| **new_password** | String | Required |

+# [Response](#tab/set-password-response)

+**Type**: JSON

+Message string with the operation status details:

+|Message |Description |

+|||

+|**Success ΓÇô msg** | Password has been replaced |

+|**Failure ΓÇô error** | User authentication failure |

+|**Failure ΓÇô error** | Password does not match security policy |

+**Example**:

+```rest

+response:

+{

+ "error": {

+ "userDisplayErrorMessage": "User authentication failure"

+ }

+}

+```

+# [cURL command](#tab/set-password-curl)

+**Type**: POST

+**API**:

+```rest

+curl -k -X POST -d '{"username": "<USER_NAME>","password": "<CURRENT_PASSWORD>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/api/external/authentication/set_password

+```

+**Example**:

+```rest

+curl -k -X POST -d '{"username": "myUser","password": "1234@abcd","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/api/external/authentication/set_password

+```

+## set_password_by_admin (Update a user password by admin)

+Use this API to let system administrators change passwords for specified users. Defender for IoT administrator user roles can work with the API.

+You don't need a Defender for IoT access token to use this API.

+**URI**: `/external/authentication/set_password_by_admin`

+### POST

+# [Request](#tab/set-password-by-admin-request)

+**Type**: JSON

+#### Request example

+```rest

+request:

+{

+ "admin_username": "admin",

+ "admin_password: "Test0987"

+ "username": "test",

+ "new_password": "Test54321\!"

+}

+```

+#### Request parameters

+| **Name** | **Type** | **Required / Optional** |

+|--|--|--|

+| **admin_username** | String | Required |

+| **admin_password** | String | Required |

+| **username** | String | Required |

+| **new_password** | String | Required |

+# [Response](#tab/set-password-by-admin-response)

+**Type**: JSON

+Message string with the operation status details:

+|Message |Description |

+|||

+|**Success ΓÇô msg** | Password has been replaced |

+|**Failure ΓÇô error** | User authentication failure |

+|**Failure ΓÇô error** | User does not exist |

+|**Failure ΓÇô error** | Password doesn't match security policy |

+|**Failure ΓÇô error** | User does not have the permissions to change password |

+#### Response example

+```rest

+response:

+{

+ "error": {

+ "userDisplayErrorMessage": "The user 'test_user' doesn't exist",

+ "internalSystemErrorMessage": "The user 'test_user' doesn't exist"

+ }

+}

+```

+# [cURL command](#tab/set-password-by-admin-curl)

+**Type**: POST

+**API**:

+```rest

+curl -k -X POST -d '{"admin_username":"<ADMIN_USERNAME>","admin_password":"<ADMIN_PASSWORD>","username": "<USER_NAME>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/api/external/authentication/set_password_by_admin

+```

+**Example**:

+```rest

+curl -k -X POST -d '{"admin_user":"adminUser","admin_password": "1234@abcd","username": "myUser","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/api/external/authentication/set_password_by_admin

+```

+## validation (Validate user credentials)

+Use this API to validate a Defender for IoT username and password.

+You don't need a Defender for IoT access token to use this API.

+**URI**: `/api/external/authentication/validation`

+### POST

+# [Request](#tab/validation-request)

+**Request type**: JSON

+#### Query parameters

+| **Name** | **Type** | **Required/Optional** |

+|--|--|--|

+| **username** | String | Required |

+| **password** | String | Required |

+#### Request example:

+```rest

+request:

+{

+ "username": "test",

+ "password": "Test12345\!"

+}

+```

+# [Response](#tab/validation-response)

+**Type**: JSON

+Message string with the operation status details:

+|Message |Description |

+|||

+|**Success - msg** | Authentication succeeded |

+|**Failure - error** | Credentials validation failed |

+#### Response example

+```rest

+response:

+{

+ "msg": "Authentication succeeded."

+}

+```

+# [cURL command](#tab/validation-curl)

+**Type**: POST

+**API**:

+```rest

+curl -k -X POST -H "Authorization: <AUTH_TOKEN>" -H "Content-Type: application/json" -d '{"username": <USER NAME>, "password": <PASSWORD>}' https://<IP_ADDRESS>/api/external/authentication/validation

+```

+**Example**:

+```rest

+curl -k -X POST -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" -H "Content-Type: application/json" -d '{"username": "test", "password": "test"}' https://127.0.0.1/api/external/authentication/validation

+```

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).

+ Title: Inventory management API reference for OT monitoring sensors - Microsoft Defender for IoT

+description: Learn about the device management REST APIs supported for Microsoft Defender for IoT OT monitoring sensors.

+# Inventory management API reference for OT monitoring sensors

+This article lists the device inventory management APIs supported for Defender for IoT OT sensors.

+## connections (Retrieve device connection information)

+Use this API to request a list of all device connections.

+**URI**: `/api/v1/devices/connections`

+### GET

+# [Request](#tab/connections-request)

+#### Query parameters

+Define any of the following query parameters to filter the results returned. If you don't set query parameters, all device connections are returned.

+|Name |Description |Example | Required / Optional |

+|||||

+|**discoveredBefore** | Numeric. Filter results that were detected before a given time, where the given time is defined in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time), and in UTC timezone. | `/api/v1/devices/2/connections?discoveredBefore=<epoch>` | Optional |

+|**discoveredAfter** | Numeric. Filter results that were detected after a given time, where the given time is defined in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time), and in UTC timezone. | `/api/v1/devices/2/connections?discoveredAfter=<epoch>` | Optional |

+|**lastActiveInMinutes** | Numeric. Filter results by a given time frame during which connections were active. Defined backwards, in minutes, from the current time. | `/api/v1/devices/2/connections?lastActiveInMinutes=20` | Optional |

+# [Response](#tab/connections-response)

+**Response type**: JSON

+Array of JSON objects that represent device connections, or the following failure message:

+|Message |Description |

+|||

+|**Failure ΓÇô error** | Operation failed |

+#### Success response fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **firstDeviceId** | Numeric | Not nullable | - |

+| **secondDeviceId** | Numeric | Not nullable | - |

+| **lastSeen** | Numeric | Not nullable | Epoch (UTC) |

+| **discovered** | Numeric | Not nullable | Epoch (UTC) |

+| **ports** | Number array | Nullable | - |

+| **protocols** | JSON array | Nullable | Protocol field |

+#### Protocol fields

+| Name | Type | Nullable / Not nullable |

+|--|--|--|

+| **name** | String | Not nullable |

+| **commands** | String array | Nullable |

+#### Response example

+```rest

+[

+ {

+ "firstDeviceId": 171,

+ "secondDeviceId": 22,

+ "lastSeen": 1511281457933,

+ "discovered": 1511872830000,

+ "ports": [

+ 502

+ ],

+ "protocols": [

+ {

+ name: "modbus",

+ commands: [

+ "Read Coils"

+ ]

+ },

+ {

+ name: "ams",

+ commands: [

+ "AMS Write"

+ ]

+ },

+ {

+ name: "http",

+ commands: [

+ ]

+ }

+ ]

+ },

+ {

+ "firstDeviceId": 171,

+ "secondDeviceId": 23,

+ "lastSeen": 1511281457933,

+ "discovered": 1511872830000,

+ "ports": [

+ 502

+ ],

+ "protocols": [

+ {

+ name: "s7comm",

+ commands: [

+ "Download block",

+ "Upload"

+ ]

+ }

+ ]

+ }

+]

+```

+# [cURL command](#tab/connections-curl)

+**Type**: GET

+**APIs**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/connections

+```

+**Examples**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/connections

+```

+## connections per device (Retrieve specific device connection information )

+Use this API to request a list of all the connections per device.

+**URI**: `/api/v1/devices/<deviceID>/connections`

+### GET

+# [Request](#tab/connections-device-request)

+#### Path parameter

+|Name |Description |Example | Required / Optional |

+|||||

+|**deviceId** | Get connections for the given device. | `/api/v1/devices/<deviceId>/connections` | Required |

+#### Query parameters

+|Name |Description |Example | Required / Optional |

+|||||

+|**discoveredBefore** | Numeric. Filter results that were detected before a given time, where the given time is defined in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time), and in UTC timezone. | `/api/v1/devices/2/connections?discoveredBefore=<epoch>` | Optional |

+|**discoveredAfter** | Numeric. Filter results that were detected after a given time, where the given time is defined in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time), and in UTC timezone. | `/api/v1/devices/2/connections?discoveredAfter=<epoch>` | Optional |

+|**lastActiveInMinutes** | Numeric. Filter results by a given time frame during which connections were active. Defined backwards, in minutes, from the current time. | `/api/v1/devices/2/connections?lastActiveInMinutes=20` | Optional |

+# [Response](#tab/connections-device-response)

+**Response type**: JSON

+Array of JSON objects that represent device connections, or the following failure message:

+|Message |Description |

+|||

+|**Failure ΓÇô error** | Operation failed |

+#### Success response fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **firstDeviceId** | Numeric | Not nullable | - |

+| **secondDeviceId** | Numeric | Not nullable | - |

+| **lastSeen** | Numeric | Not nullable | Epoch (UTC) |

+| **discovered** | Numeric | Not nullable | Epoch (UTC) |

+| **ports** | Number array | Nullable | - |

+| **protocols** | JSON array | Nullable | Protocol field |

+#### Protocol fields

+| Name | Type | Nullable / Not nullable |

+|--|--|--|

+| **name** | String | Not nullable |

+| **commands** | String array | Nullable |

+#### Response example

+```rest

+[

+ {

+ "firstDeviceId": 171,

+ "secondDeviceId": 22,

+ "lastSeen": 1511281457933,

+ "discovered": 1511872830000,

+ "ports": [

+ 502

+ ],

+ "protocols": [

+ {

+ name: "modbus",

+ commands: [

+ "Read Coils"

+ ]

+ },

+ {

+ name: "ams",

+ commands: [

+ "AMS Write"

+ ]

+ },

+ {

+ name: "http",

+ commands: [

+ ]

+ }

+ ]

+ },

+ {

+ "firstDeviceId": 171,

+ "secondDeviceId": 23,

+ "lastSeen": 1511281457933,

+ "discovered": 1511872830000,

+ "ports": [

+ 502

+ ],

+ "protocols": [

+ {

+ name: "s7comm",

+ commands: [

+ "Download block",

+ "Upload"

+ ]

+ }

+ ]

+ }

+]

+```

+# [cURL command](#tab/connections-device-curl)

+**Type**: GET

+**APIs**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/<deviceId>/connections?lastActiveInMinutes=&discoveredBefore=&discoveredAfter=

+```

+**Examples**:

+With given query parameters:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/devices/2/connections?lastActiveInMinutes=20&discoveredBefore=1594550986000&discoveredAfter=1594550986000

+```

+## cves (Retrieve information on CVEs)

+Use this API to request a list of all known CVEs discovered on devices in the network, sorted by descending CVE score.

+**URI**: `/api/v1/devices/cves`

+### GET

+# [Request](#tab/cves-request)

+**Example**: `/api/v1/devices/cves`

+Define any of the following query parameters to filter the results returned.

+|Name |Description |Example | Required / Optional |

+|||||

+|**top** | Numeric. Determine how many top-scored CVEs to get for each device IP address. | `/api/v1/devices/cves?top=50` <br><br> `/api/v1/devices/<ipAddress>/cves?top=50` | Optional. Default = `100` |

+# [Response](#tab/cves-response)

+**Type**: JSON

+JSON array of device CVE objects, or the following failure message:

+|Message |Description |

+|||

+|**Failure ΓÇô error** | Operation failed |

+#### Success response fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **cveId** | String | Not nullable | A canonical, industry-standard ID for the given CVE. |

+| **ipAddress** | String | Not nullable | IP addresses |

+| **score** | String | Not nullable | A CVE score, between 0.0 - 10.0 |

+| **attackVector** | String | Not nullable | `Network`, `Adjacent Network`, `Local`, or `Physical` |

+| **description** | String | Not nullable | - |

+#### Response example

+```rest

+[

+ {

+ "cveId": "CVE-2007-0099",

+ "score": "9.3",

+ "ipAddress": "10.35.1.51",

+ "attackVector": "NETWORK",

+ "description": "Race condition in the msxml3 module in Microsoft XML Core

+ Services 3.0, as used in Internet Explorer 6 and other

+ applications, allows remote attackers to execute arbitrary

+ code or cause a denial of service (application crash) via many

+ nested tags in an XML document in an IFRAME, when synchronous

+ document rendering is frequently disrupted with asynchronous

+ events, as demonstrated using a JavaScript timer, which can

+ trigger NULL pointer dereferences or memory corruption, aka

+ \"MSXML Memory Corruption Vulnerability.\""

+ },

+ {

+ "cveId": "CVE-2009-1547",

+ "score": "9.3",

+ "ipAddress": "10.35.1.51",

+ "attackVector": "NETWORK",

+ "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01

+ SP4, 6, 6 SP1, and 7 allows remote attackers to execute

+ arbitrary code via a crafted data stream header that triggers

+ memory corruption, aka \"Data Stream Header Corruption

+ Vulnerability.\""

+ }

+]

+```

+# [cURL command](#tab/cves-curl)

+**Type**: GET

+**APIs**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/cves

+```

+**Examples**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/cves

+```

+## cves per IP address (Retrieve specific information on CVEs)

+Use this API to request a list of all known CVEs discovered on devices in the network for a specific IP address.

+**URI**: `/api/v1/devices/cves`

+### GET

+# [Request](#tab/cves-ip-request)

+**Example**: `/api/v1/devices/cves`

+#### Path parameter

+|Name |Description |Example | Required / Optional |

+|||||

+|**ipAddress** | Get CVEs for the given IP address. | `/api/v1/devices/<ipAddress>/cves` | Required |

+Define the following query parameter to filter the results returned.

+|Name |Description |Example | Required / Optional |

+|||||

+|**top** | Numeric. Determine how many top-scored CVEs to get for each device IP address. | `/api/v1/devices/cves?top=50` <br><br> `/api/v1/devices/<ipAddress>/cves?top=50` | Optional. Default = `100` |

+# [Response](#tab/cves-ip-response)

+**Type**: JSON

+JSON array of device CVE objects, or the following failure message:

+|Message |Description |

+|||

+|**Failure ΓÇô error** | Operation failed |

+#### Success response fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **cveId** | String | Not nullable | A canonical, industry-standard ID for the given CVE. |

+| **ipAddress** | String | Not nullable | IP addresses |

+| **score** | String | Not nullable | A CVE score, between 0.0 - 10.0 |

+| **attackVector** | String | Not nullable | `Network`, `Adjacent Network`, `Local`, or `Physical` |

+| **description** | String | Not nullable | - |

+#### Response example

+```rest

+[

+ {

+ "cveId": "CVE-2007-0099",

+ "score": "9.3",

+ "ipAddress": "10.35.1.51",

+ "attackVector": "NETWORK",

+ "description": "Race condition in the msxml3 module in Microsoft XML Core

+ Services 3.0, as used in Internet Explorer 6 and other

+ applications, allows remote attackers to execute arbitrary

+ code or cause a denial of service (application crash) via many

+ nested tags in an XML document in an IFRAME, when synchronous

+ document rendering is frequently disrupted with asynchronous

+ events, as demonstrated using a JavaScript timer, which can

+ trigger NULL pointer dereferences or memory corruption, aka

+ \"MSXML Memory Corruption Vulnerability.\""

+ },

+ {

+ "cveId": "CVE-2009-1547",

+ "score": "9.3",

+ "ipAddress": "10.35.1.51",

+ "attackVector": "NETWORK",

+ "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01

+ SP4, 6, 6 SP1, and 7 allows remote attackers to execute

+ arbitrary code via a crafted data stream header that triggers

+ memory corruption, aka \"Data Stream Header Corruption

+ Vulnerability.\""

+ }

+]

+```

+# [cURL command](#tab/cves-ip-curl)

+**Type**: GET

+**APIs**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/<deviceIpAddress>/cves?top=

+```

+**Examples**:

+With given query parameters:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/10.10.10.15/cves?top=50

+```

+## devices (Retrieve device information)

+Use this API to request a list of all devices detected by this sensor.

+**URI**: `api/v1/devices/`

+### GET

+# [Request](#tab/devices-request)

+#### Query parameter

+Define the following query parameter to filter the results returned. If you don't set query parameters, all device connections are returned.

+|Name |Description |Example | Required / Optional |

+|||||

+|**authorized** | Boolean: <br><br>- `true`: Filter for data on authorized devices only. <br>- `false`: Filter for data on unauthorized devices only. | `/api/v1/devices/` | Optional |

+# [Response](#tab/devices-response)

+**Response type**: JSON

+Array of JSON objects that represent device objects, or the following failure message:

+|Message |Description |

+|||

+|**Failure ΓÇô error** | Operation failed |

+#### Success response fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **id** | Numeric. Defines the device ID. | Not nullable | - |

+|**ipAddresses** | JSON array of strings. |Nullable | - |

+|**name** |String. Defines the device name. |Not nullable |- |

+|**vendor** |String. Defines the device's vendor. |Nullable |- |

+| **<a name="operatingsystem"></a>operatingSystem** | Enum. Defines the device's operating system. |Nullable | For more information, see [Supported operatingSystem values](#supported-operatingsystem-values). |

+| **macAddresses** | JSON array of strings. |Nullable | - |

+| <a name="type"></a>**type** |String. Defines the device type. |Not nullable |Can be `Unknown`. For more information, see [Supported type values](#supported-type-values). |

+| **engineeringStation** | Boolean. Defines whether the device is defined as an engineering station or not. |Not nullable | - `true`: Device is an engineering station <br>- `false`: Device is not an engineering station. |

+|**authorized** |Boolean. Defines whether the device is defined as an engineering station or not. |Not nullable | - `true`: Device is an engineering station <br>- `false`: Device is not an engineering station|

+|**scanner** |Boolean. Defines whether the device is authorized or not.|Not nullable | - `true`: Device is authorized <br>- `false`: Device is not authorized |

+| <a name="protocol"></a>**protocols** |Object that contains the device's protocol details. |Nullable | For more information, see [Microsoft Defender for IoT - supported IoT, OT, ICS, and SCADA protocols](../concept-supported-protocols.md). |

+|<a name="firmware"></a>**firmware** | JSON array of a `firmware` object that defies the device's firmware. |Not nullable | For more information, see [Supported firmware fields](#supported-firmware-fields).|

+|**hasDynamicAddress** | Boolean. Defines whether the device has a dynamic address or not. |Not nullable| - `true`: Device has a dynamic address <br>- `false`: Device does not have a dynamic address |

+#### Supported `operatingSystem` values

+This section lists the supported values for the [operatingSystem](#operatingsystem) response field.

+ :::column span="":::

+- `Windows 10`

+- `Windows 10 32`

+- `Windows 10 64`

+- `Windows 2000`

+- `Windows 7`

+- `Windows 7 32`

+- `Windows 7 64`

+- `Windows 8`

+- `Windows 8 32`

+- `Windows 8 64`

+- `Windows 8.1`

+- `Windows 8.1 32`

+ :::column-end:::

+ :::column span="":::

+- `Windows 8.1 64`

+- `Windows NT`

+- `Windows Server 2003`

+- `Windows Server 2003 R2`

+- `Windows Server 2008`

+- `Windows Server 2008 32`

+- `Windows Server 2008 64`

+- `Windows Server 2008 R2`

+- `Windows Server 2012`

+- `Windows Server 2012 R2`

+- `Windows Server 2016`

+- `Windows Vista`

+ :::column-end:::

+ :::column span="":::

+- `Windows Vista 32`

+- `Windows Vista 64`

+- `Windows XP`

+- `Mac OS`

+- `Mac OS X`

+- `Linux`

+- `Windows Server 2019`

+- `HP UX`

+- `Windows 11`

+- `Windows 11 32`

+- `Windows 11 64`

+ :::column-end:::

+#### Supported `type` values

+This section lists the supported values for the [type](#type) response field.

+ :::column span="":::

+- `Engineering Station`

+- `PLC`

+- `Historian`

+- `HMI`

+- `Domain Controller`

+- `DB Server`

+- `Wireless Access Point`

+- `Router`

+- `Switch`

+- `Workstation`

+- `Server`

+- `IP Camera`

+- `Printer`

+- `Multicast/Broadcast`

+- `Internet`

+- `Firewall`

+- `Terminal Station`

+- `VPN Gateway`

+- `Group`

+ :::column-end:::

+ :::column span="":::

+- `IED`

+- `DCS Controller`

+- `RTU`

+- `NTP Server`

+- `Storage`

+- `Industrial Packaging System`

+- `Industrial Scale`

+- `Industrial Robot`

+- `Slot`

+- `Punch Clock`

+- `ATM`

+- `Smart TV`

+- `Game console`

+- `DVR`

+- `Door Control Panel`

+- `HVAC`

+- `Thermostat`

+- `Fire Alarm`

+- `Smart Light`

+ :::column-end:::

+ :::column span="":::

+- `Smart Switch`

+- `Fire Detector`

+- `IP Telephone`

+- `Alarm System`

+- `Alarm Siren`

+- `Smart Phone`

+- `Tablet`

+- `Wifi Pineapple`

+- `Motion Detector`

+- `Elevator`

+- `Humidity Sensor`

+- `Physical Location`

+- `Backup Server`

+- `Meter`

+- `Barcode Scanner`

+- `Uninterruptable Power Supply`

+ :::column-end:::

+ :::column span="":::

+- `Variable Frequency Drive`

+- `Robot Controller`

+- `Servo Drive`

+- `Pneumatic Device`

+- `Marquee`

+- `People Counter System`

+- `Intercom`

+- `Turnstile`

+- `I/O Adapter`

+- `Protocol Converter`

+- `KVM`

+- `Web Guiding System`

+- `Turbine`

+- `External Management`

+- `Embedded Device`

+- `Unknown`

+ :::column-end:::

+#### Supported fields for the `protocols` object and protocol `name` values

+This section lists the supported fields for the [protocols](#protocol) object in the `protocols` response field.

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **id** | Numeric. Defines the protocol's internal ID. | Not nullable | - |

+|<a name="protocol-name"></a>**name** |String. Defines the device name. |Not nullable | For more information, see below. <br><br>**Note**: To extend Defender for IoT support to proprietary protocols, create a Horizon plugin. For more information, see [Extend support to proprietary protocols](../overview.md#extend-support-to-proprietary-protocols).|

+|**ipAddresses** | JSON array of strings of protocol IP addresses. |Not nullable | - |

+The following values are supported as [protocol names](#protocol-name) out-of-the-box:

+ :::column span="":::

+- `Unknown`

+- `DNP3`

+- `MODBUS`

+- `C37.118`

+- `SSH`

+- `HTTP`

+- `SYSLOG`

+- `GENERIC`

+- `ICMP`

+- `DNS`

+- `GOOSE`

+- `MMS`

+- `MALFORMED`

+- `IEC-60870`

+- `OPC UA`

+- `Siemens S7`

+- `ARP`

+- `Sampled Values`

+- `EtherNet/IP`

+ :::column-end:::

+ :::column span="":::

+- `Siemens S7 Plus`

+- `Motorola MDLC`

+- `Netbios Name Service`

+- `Netbios Datagram Service`

+- `Lightweight Access Point`

+- `CAPWAP`

+- `SNMP`

+- `DTLS`

+- `TNS`

+- `Database`

+- `SRTP`

+- `RPC`

+- `OPC`

+- `DF-1`

+- `DH-485`

+- `TDS`

+- `SMB`

+- `Suitelink`

+- `ControlNet`

+ :::column-end:::

+ :::column span="":::

+- `FTP`

+- `CDP`

+- `Profinet DCP`

+- `Profinet Real-Time`

+- `LLDP`

+- `Telnet`

+- `DeltaV`

+- `BACNet`

+- `AMS`

+- `TwinCAT`

+- `Ovation ADMD`

+- `Ovation SSRPC`

+- `Ovation DPUSTAT`

+- `Port Map`

+- `STP`

+- `Telvent OASyS Tags`

+- `Mitsubishi MELSEC`

+- `Honeywell Control Data Access`

+ :::column-end:::

+ :::column span="":::

+- `ARP`

+- `Yokogawa HIS Equalize`

+- `Emerson OpenBSI`

+- `Siemens SICAM`

+- `Omron FINS`

+- `Toshiba Computer Link`

+- `Foxboro I/A`

+- `Yokogawa VNet/IP`

+- `Emerson ROC`

+- `ABB Totalflow`

+- `Siemens Process Historian Discovery`

+- `Siemens WinCC Agent`

+- `LonTalk`

+- `Common ASCII Message`

+- `CodeSys`

+- `SAIA S-Bus`

+- `MDNS`

+- `Bently Nevada`

+ :::column-end:::

+#### Supported firmware fields

+This section lists the supported fields for the [firmware](#operatingsystem) object in the `firmware` response field.

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+|**address** |String. Defines the firmware IP address. |Not nullable | - |

+| **moduleAddress** |String. Defines the firmware's module address. | Not nullable. | - |

+| **serial** |String. Defines the firmware's serial number. | Nullable | - |

+|**model** | String. Defines the firmware model. | Nullable | - |

+| **firmwareVersion** |String. Defines the firmware version. | Nullable | - |

+|**additionalData** | String. Defines additional data for the firmware. | Nullable | - |

+|**rack** |String. Defines the firmware rack. | Nullable | - |

+|**slot** |String. Defines the firmware slot. | Nullable | - |

+# [cURL command](#tab/devices-curl)

+**Type**: GET

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/'

+```

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).

+ Title: Vulnerability management API reference for OT monitoring sensors - Microsoft Defender for IoT

+description: Learn about the vulnerability management REST APIs supported for Microsoft Defender for IoT OT monitoring sensors.

+# Vulnerability management API reference for OT monitoring sensors

+This article lists the vulnerability management REST APIs supported for Microsoft Defender for IoT OT monitoring sensors.

+The data included in the API responses includes the same information as if you generated a vulnerability report from the on-premises management console.

+## devices (Retrieve device vulnerability information)

+Use this API to request vulnerability assessment results for each device.

+**URI**: `/api/v1/reports/vulnerabilities/devices`

+### GET

+# [Request](#tab/devices-request)

+This API is called without any request parameters.

+# [Response](#tab/devices-response)

+**Type**: JSON

+Array of JSON objects that represent assessed devices and their reported vulnerabilities.

+Devices that are found to have no vulnerabilities are not included in the result response.

+#### Device fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **name** | String | Not nullable | - |

+| **ipAddresses** | JSON array | Not nullable | - |

+| **securityScore** | Numeric | Not nullable | - |

+| **vendor** | String | Nullable | |

+| **firmwareVersion** | String | Nullable | - |

+| **model** | String | Nullable | - |

+| **isWirelessAccessPoint** | Boolean | Not nullable | `True` or `False` |

+| **operatingSystem** | [Operating system object](#operating-system-fields) | Nullable | - |

+| **vulnerabilities** | [Vulnerabilities object](#vulnerabilities-fields) | Not nullable | - |

+#### Operating system fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **name** | String | Not nullable | - |

+| **type** | String | Not nullable | - |

+| **version** | String | Nullable | - |

+| **latestVersion** | String | Nullable | - |

+#### Vulnerabilities fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **antiViruses** | JSON array of strings | Nullable | Antivirus names |

+| **plainTextPasswords** | JSON array | Nullable | [Password](#password-fields) objects |

+| **remoteAccess** | JSON array | Nullable | [Remote access](#remote-access-fields) objects |

+| **isBackupServer** | Boolean | Not nullable | `True` or `False` |

+| **openedPorts** | JSON array | Nullable | [Opened port](#open-port-fields) objects |

+| **isEngineeringStation** | Boolean | Not nullable | `True` or `False` |

+| **isKnownScanner** | Boolean | Not nullable | `True` or `False` |

+| **cves** | JSON array | Nullable | [CVE](#cve-fields) objects |

+| **isUnauthorized** | Boolean | Not nullable | `True` or `False` |

+| **malwareIndicationsDetected** | Boolean | Not nullable | `True` or `False` |

+| **weakAuthentication** | JSON array of strings | Nullable | Detected applications that are using weak authentication |

+#### Password fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **password** | String | Not nullable | - |

+| **protocol** | String | Not nullable | - |

+| **strength** | String | Not nullable | `Very weak`, `Weak`, `Medium`, `Strong` |

+#### Remote access fields

+| Name | Type | Nullable | List of values |

+|--|--|--|--|

+| **port** | Numeric | Not nullable | - |

+| **transport** | String | Not nullable | `TCP`, `UDP` |

+| **client** | String | Not nullable | IP address |

+| **clientSoftware** | String | Not nullable | Name of the remote protocol, like `SSH`, `VNC`, `Remote desktop`, or `Team viewer` |

+#### Open port fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **port** | Numeric | Not nullable | - |

+| **transport** | String | Not nullable | `TCP` or `UDP` |

+| **protocol** | String | Nullable | - |

+| **isConflictingWithFirewall** | Boolean | Not nullable | `True` or `False` |

+#### CVE fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **id** | String | Not nullable | - |

+| **score** | Numeric, decimal value | Not nullable | - |

+| **description** | String | Not nullable | - |

+#### Response example

+```rest

+[

+ {

+ "name": "IED \#10",

+ "ipAddresses": ["10.2.1.10"],

+ "securityScore": 100,

+ "vendor": "ABB Switzerland Ltd, Power Systems",

+ "firmwareVersion": null,

+ "model": null,

+ "operatingSystem": {

+ "name": "ABB Switzerland Ltd, Power Systems",

+ "type": "abb",

+ "version": null,

+ "latestVersion": null

+ },

+ "vulnerabilities": {

+ "antiViruses": [

+ "McAfee"

+ ],

+ "plainTextPasswords": [

+ {

+ "password": "123456",

+ "protocol": "HTTP",

+ "strength": "Very Weak"

+ }

+ ],

+ "remoteAccess": [

+ {

+ "port": 5900,

+ "transport": "TCP",

+ "clientSoftware": "VNC",

+ "client": "10.2.1.20"

+ }

+ ],

+ "isBackupServer": true,

+ "openedPorts": [

+ {

+ "port": 445,

+ "transport": "TCP",

+ "protocol": "SMP Over IP",

+ "isConflictingWithFirewall": false

+ },

+ {

+ "port": 80,

+ "transport": "TCP",

+ "protocol": "HTTP",

+ "isConflictingWithFirewall": false

+ }

+ ],

+ "isEngineeringStation": false,

+ "isKnownScanner": false,

+ "cves": [

+ {

+ "id": "CVE-2015-6490",

+ "score": 10,

+ "description": "Frosty URL - Stack-based buffer overflow on Allen-Bradley MicroLogix 1100 devices before B FRN 15.000 and 1400 devices through B FRN 15.003 allows remote attackers to execute arbitrary code via unspecified vectors"

+ },

+ {

+ "id": "CVE-2012-6437",

+ "score": 10,

+ "description": "MicroLogix 1100 and 1400 do not properly perform authentication for Ethernet firmware updates, which allows remote attackers to execute arbitrary code via a Trojan horse update image"

+ },

+ {

+ "id": "CVE-2012-6440",

+ "score": 9.3,

+ "description": "MicroLogix 1100 and 1400 allows man-in-the-middle attackers to conduct replay attacks via HTTP traffic."

+ }

+ ],

+ "isUnauthorized": false,

+ "malwareIndicationsDetected": true

+ }

+ }

+]

+```

+# [cURL command](#tab/devices-curl)

+**Type**: GET

+**API**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/devices

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/devices

+```

+## security (Retrieve security vulnerabilities)

+Use this API to request results of a general vulnerability assessment report. This assessment provides insight into your system's security level.

+This assessment is based on general network and system information and not on a specific device evaluation.

+**URI**: `/api/v1/reports/vulnerabilities/security`

+### GET

+# [Request](#tab/security-request)

+This API is called without any request parameters.

+# [Response](#tab/security-response)

+**Type**: JSON representation of one or more data tables, each with specific and potentially different structures.

+The response is displayed in a map view, which maps table titles to table rows. Rows are represented as a list of objects with the same structures.

+#### unauthorizedDevices fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **address** | String | Nullable | IP or MAC address of the unauthorized device |

+| **name** | String |Nullable | Name of the unauthorized device |

+| **firstDetectionTime** | Numeric |Nullable | Timestamp the device was first detected, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone |

+| **lastSeen** | Numeric |Nullable | Timestamp that traffic was last detected as sent to or from the device, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone|

+#### illegalTrafficByFirewallRules fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **server** | String | Nullable | Server IP address |

+| **client** | String | Nullable | Client IP address |

+| **port** | Numeric |Nullable | The server port |

+| **transport** | String | Nullable | `TCP`, `UDP`, or `ICMP` |

+#### weakFirewallRules fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **sources** | JSON array of sources | Nullable | JSON array of sources in any of the following formats: <br>- `Any` <br>- `ip address (host)` <br>- `from ip-to ip (RANGE)` <br>- `ip address, subnet mask (NETWORK)` |

+| **destinations** | JSON array of destinations | Nullable | JSON array of destination objects, in any of the following formats: <br>- `Any` <br>- `ip address (host)` <br>- `from ip-to ip (RANGE)` <br>- `ip address, subnet mask (NETWORK)`|

+| **ports** | JSON array of ports | Nullable | JSON array of port objects, in any of the following formats: <br>- `Any` <br>- `port (protocol, if detected)` <br>- `from port-to port (protocol, if detected)`|

+#### accessPoints fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **macAddress** | String | Nullable | The access point's MAC address |

+| **vendor** | String | Nullable | The access point's vendor name |

+| **ipAddress** | String | Nullable | The access point's IP address, or N/A |

+| **name** | String | Nullable | The access point's device name, or N/A |

+| **wireless** | String | Nullable | Whether the access point is connected to a wireless network: `No`, `Suspected`, or `Yes` |

+#### connectionsBetweenSubnets fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **server** | String | Nullable | The server's IP address |

+| **client** | String | Nullable | The client's IP address |

+#### industrialMalwareIndicators fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **detectionTime** | Numeric | Nullable | Timestamp the malware was first detected, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone |

+| **alertMessage** | String | Nullable | The alert message sent |

+| **description** | String | Nullable | The alert message description |

+| **devices** | JSON array | Not nullable | A JSON array of strings representing device names |

+#### internetConnections fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **internalAddress** | String | Nullable | The connection's internal IP address |

+| **authorized** | Boolean | Nullable | `Yes` or `No` |

+| **externalAddresses** | JSON array | Not nullable | A JSON array of the connection's external IP addresses |

+#### Response example

+```rest

+{

+ "unauthorizedDevices": [

+ {

+ "address": "10.2.1.14",

+ "name": "PLC \#14",

+ "firstDetectionTime": 1462645483000,

+ "lastSeen": 1462645495000,

+ }

+ ],

+ "redundantFirewallRules": [

+ {

+ "sources": "170.39.3.0/255.255.255.0",

+ "destinations": "Any",

+ "ports": "102"

+ }

+ ],

+ "connectionsBetweenSubnets": [

+ {

+ "server": "10.2.1.22",

+ "client": "170.39.2.0"

+ }

+ ],

+ "industrialMalwareIndications": [

+ {

+ "detectionTime": 1462645483000,

+ "alertMessage": "Suspicion of Malicious Activity (Regin)",

+ "description": "Suspicious network activity was detected. Such behavior might be attributed to the Regin malware.",

+ "addresses": [

+ "10.2.1.4",

+ "10.2.1.5"

+ ]

+ }

+ ],

+ "illegalTrafficByFirewallRules": [

+ {

+ "server": "10.2.1.7",

+ "port": "20000",

+ "client": "10.2.1.4",

+ "transport": "TCP"

+ },

+ {

+ "server": "10.2.1.8",

+ "port": "20000",

+ "client": "10.2.1.4",

+ "transport": "TCP"

+ },

+ {

+ "server": "10.2.1.9",

+ "port": "20000",

+ "client": "10.2.1.4",

+ "transport": "TCP"

+ }

+ ],

+ "internetConnections": [

+ {

+ "internalAddress": "10.2.1.1",

+ "authorized": "Yes",

+ "externalAddresses": ["10.2.1.2",ΓÇ¥10.2.1.3ΓÇ¥]

+ }

+ ],

+ "accessPoints": [

+ {

+ "macAddress": "ec:08:6b:0f:1e:22",

+ "vendor": "TP-LINK TECHNOLOGIES",

+ "ipAddress": "173.194.112.22",

+ "name": "Enterprise AP",

+ "wireless": "Yes"

+ }

+ ],

+ "weakFirewallRules": [

+ {

+ "sources": "170.39.3.0/255.255.255.0",

+ "destinations": "Any",

+ "ports": "102"

+ }

+ ]

+}

+```

+# [cURL command](#tab/security-curl)

+**Type**: GET

+**APIs**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/security

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/security

+```

+## operational (Retrieve operational vulnerabilities)

+Use this API to request results of a general vulnerability assessment. This assessment provides insight into the operational status of your network. It's based on general network and system information and not on a specific device evaluation.

+**URI**: `/api/v1/reports/vulnerabilities/operational`

+### GET

+# [Request](#tab/operational-request)

+This API is called without any request parameters.

+# [Response](#tab/operational-response)

+**Type**: JSON representation of one or more data tables, each with specific and potentially different structures.

+The response is displayed in a map view, which maps table titles to table rows. Rows are represented as a list of objects with the same structures.

+#### backupServer result fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **source** | String | Nullable | The source IP address |

+| **destination** | String |Nullable | The destination IP address |

+| **port** | Numeric | Nullable| The backup server port |

+| **transport** | String |Nullable | The backup server transport protocol `TCP` or `UDP` |

+| **backupMaximalInterval** | String |Nullable | The maximum interval time between backups |

+| **lastSeenBackup** | Numeric | Nullable |Timestamp that a backup was last seen, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone|

+#### ipNetworks result fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **addresses** | Numeric |Not nullable | The number of IP addresses discovered in the subnet range.|

+| **network** | String |Not nullable | The subnet base IP address. |

+| **mask** | String |Not nullable | The subnet mask. |

+#### protocolProblems result fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **protocol** | String |Not nullable | A protocol for which a protocol violation alert was triggered |

+| **addresses** | JSON array of IP addresses |Not nullable | JSON array of IP addresses where the violation originated |

+| **alert** | String |Not nullable | The title of the alert triggered |

+| **reportTime** | Numeric |Not nullable | Timestamp that a report was last generated, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone |

+#### protocolDataVolumes result fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **protocol** | String |Nullable | A protocol that was detected on the network by the OT network sensor |

+| **volume** | String |Nullable | The volume of protocol packets captured by the OT network sensor, in MB |

+#### disconnections result fields

+| Name | Type | Nullable / Not nullable | List of values |

+|--|--|--|--|

+| **assetAddress** | String |Nullable | The IP address of the disconnected asset |

+| **assetName** | String | Nullable| The name of the disconnected asset |

+| **lastDetectionTime** | Numeric | Nullable| Timestamp that the disconnect was last detected, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone |

+| **backToNormalTime** | Numeric | Nullable| Timestamp that the connection returned, in milliseconds from [Epoch time](../references-work-with-defender-for-iot-apis.md#epoch-time) and in UTC timezone|

+#### Response example

+```rest

+{

+ "backupServer": [

+ {

+ "backupMaximalInterval": "1 Hour, 29 Minutes",

+ "source": "10.2.1.22",

+ "destination": "170.39.2.14",

+ "port": 10000,

+ "transport": "TCP",

+ "lastSeenBackup": 1462645483000

+ }

+ ],

+ "ipNetworks": [

+ {

+ "addresses": "21",

+ "network": "10.2.1.0",

+ "mask": "255.255.255.0"

+ },

+ {

+ "addresses": "3",

+ "network": "170.39.2.0",

+ "mask": "255.255.255.0"

+ }

+ ],

+ "protocolProblems": [

+ {

+ "protocol": "DNP3",

+ "addresses": [

+ "10.2.1.7",

+ "10.2.1.8"

+ ],

+ "alert": "Illegal DNP3 Operation",

+ "reportTime": 1462645483000

+ },

+ {

+ "protocol": "DNP3",

+ "addresses": [

+ "10.2.1.15"

+ ],

+ "alert": "Master Requested an Application Layer Confirmation",

+ "reportTime": 1462645483000

+ }

+ ],

+ "protocolDataVolumes": [

+ {

+ "protocol": "MODBUS (502)",

+ "volume": "21.07 MB"

+ },

+ {

+ "protocol": "SSH (22)",

+ "volume": "0.001 MB"

+ }

+ ],

+ "disconnections": [

+ {

+ "assetAddress": "10.2.1.3",

+ "assetName": "PLC \#3",

+ "lastDetectionTime": 1462645483000,

+ "backToNormalTime": 1462645484000

+ }

+ ]

+}

+```

+# [cURL command](#tab/operational-curl)

+**Type**: GET

+**APIs**:

+```rest

+curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/operational

+```

+**Example**:

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/operational

+```

+## mitigation (Retrieve mitigation steps)

+Use this API to request a mitigation assessment. This assessment provides recommended steps for mitigating detected vulnerabilities. It's based on general network and system information and not on a specific device evaluation.

+**URI**: `/api/v1/reports/vulnerabilities/mitigation`

+### GET

+# [Request](#tab/mitigation-request)

+This API is called without any request parameters.

+# [Response](#tab/mitigation-response)

+**Type**: JSON

+JSON object that represents recommended mitigation steps.

+#### Response fields

+| Field name | Type | Nullable | List of values |

+|--|--|--|

+| **notifications** | JSON array of strings | Not nullable | Recommended mitigation steps for detected vulnerabilities |

+| **mitigation** | JSON array | Not nullable | [mitigation](#mitigation-fields) objects |

+#### mitigation fields

+| Field name | Type | Nullable | List of values |

+|--|--|--|

+| **content** | String | Not nullable | Recommended mitigation steps for detected vulnerabilities |

+| **scoreImprovement** | Integer | Nullable | Expected percentage of security improvement after mitigation steps are taken. |

+| **details** | Table | Nullable | A table listing mitigation recommendations, such as would be generated in the **Risk assessment** report. Each recommendation includes details about possible security impact if the action is performed and more. For more information, see [Risk mitigation](../how-to-create-risk-assessment-reports.md#risk-mitigation). |

+> [!NOTE]

+> You might have multiple mitigation steps, with some returned in the `notifications` field, and others returned in the `mitigation` field. Items with `scoreImprovement` and `details` data is returned only in the `mitigation` field. Items without `scoreImprovement` and `details` data is returned only in the `notifications` field.

+>

+#### Response example

+```rest

+{

+ "notifications": ["Firewall policy import", "Marking \"important devices\"", "Further device information import"],

+ "mitigation": [{

+ "content": "Install an Antivirus solution to increase protection of the workstations",

+ "details": null,

+ "scoreImprovement": 10

+ }, {

+ "content": "Investigate all malware indicators (Contact your incident response team or support.microsoft.com). When assured the problem is solved, acknowledge the alert",

+ "details": {

+ "name": "",

+ "description": {

+ "name": "",

+ "important": false,

+ "warning": false

+ },

+ "headers": ["Detection Time", "Alert Message", "Description", "Devices"],

+ "rows": [

+ ["03/10/2022 07:10:24", "Address Scan Detected", "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.", ""],

+ ]

+ },

+ "scoreImprovement": 8

+ }, {

+ "content": "Install a backup server in the network",

+ "details": null,

+ "scoreImprovement": 5

+ }, {

+ "content": "Install latest security updates (Devices: 2)",

+ "details": {

+ "name": "",

+ "description": {

+ "name": "",

+ "important": false,

+ "warning": false

+ },

+ "headers": ["Name", "Address"],

+ "rows": [

+ ["10.13.10.5", "10.13.10.5"],

+ ["192.168.1.127", "192.168.1.127"]

+ ]

+ },

+ "scoreImprovement": 2

+ }, {

+ "content": "Increase password complexity for authentication (Devices: 53)",

+ "details": {

+ "name": "",

+ "description": {

+ "name": "",

+ "important": false,

+ "warning": false

+ },

+ "headers": ["Name", "Address"],

+ "rows": [

+ ["10.10.10.13", "10.10.10.13"],

+ ["10.10.10.14", "10.10.10.14"],

+ ["10.10.10.15", "10.10.10.15"],

+ ["10.13.10.3", "10.13.10.3"],

+ ["10.13.10.40", "10.13.10.40"],

+ ["10.13.10.5", "10.13.10.5"],

+ ["10.13.11.2", "10.13.11.2"],

+ ["10.13.11.3", "10.13.11.3"],

+ ["192.168.1.100", "192.168.1.100"],

+ ["192.168.1.242", "192.168.1.242"]

+ ]

+ },

+ "scoreImprovement": 2

+ }, {

+ "content": "Investigate and acknowledge all unacknowledge alerts",

+ "details": {

+ "name": "",

+ "description": {

+ "name": "",

+ "important": false,

+ "warning": false

+ },

+ "headers": ["Detection Time", "Alert Message", "Description"],

+ "rows": [

+ ["03/10/2022 07:10:24", "Address Scan Detected", "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident."],

+ ["03/10/2022 07:44:52", "No Traffic Detected on Sensor Interface", "The sensor stopped detecting network traffic on local_listener."]

+ ]

+ },

+ "scoreImprovement": 1

+ }]

+}

+```

+# [cURL command](#tab/mitigation-curl)

+```rest

+curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://<IP address>/api/v1/reports/vulnerabilities/mitigation"

+```

+## Next steps

+For more information, see the [Defender for IoT API reference overview](../references-work-with-defender-for-iot-apis.md).