-description: Learn how Azure App Service helps you host your RESTful APIs with CORS support. App Service can host both front-end web apps and back end APIs.

-[Azure App Service](overview.md) provides a highly scalable, self-patching web hosting service. In addition, App Service has built-in support for [Cross-Origin Resource Sharing (CORS)](https://wikipedia.org/wiki/Cross-Origin_Resource_Sharing) for RESTful APIs. This tutorial shows how to deploy an ASP.NET Core API app to App Service with CORS support. You configure the app using command-line tools and deploy the app using Git.

-> * Create App Service resources using Azure CLI

-> * Deploy a RESTful API to Azure using Git

-> * Enable App Service CORS support

-You can follow the steps in this tutorial on macOS, Linux, Windows.

-To complete this tutorial:

-* <a href="https://git-scm.com/" target="_blank">Install Git</a>

- * <a href="https://dotnet.microsoft.com/download/dotnet-core/3.1" target="_blank">Install the latest .NET Core 3.1 SDK</a>

-## Create local ASP.NET Core app

-1. In the terminal window, `cd` to a working directory.

-1. Clone the sample repository and change to the repository root.

- This repository contains an app that's created based on the following tutorial: [ASP.NET Core Web API help pages using Swagger](/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio). It uses a Swagger generator to serve the [Swagger UI](https://swagger.io/swagger-ui/) and the Swagger JSON endpoint.

- > The branch name change isn't required by App Service. However, since many repositories are changing their default branch to `main` (see [Change deployment branch](deploy-local-git.md#change-deployment-branch)), this tutorial also shows you how to deploy a repository from `main`.

-1. Navigate to `http://localhost:5000/swagger` in a browser to play with the Swagger UI.

- 

-1. Navigate to `http://localhost:5000/api/todo` and see a list of ToDo JSON items.

-1. Navigate to `http://localhost:5000` and play with the browser app. Later, you will point the browser app to a remote API in App Service to test CORS functionality. Code for the browser app is found in the repository's _wwwroot_ directory.

-1. To stop ASP.NET Core at any time, press `Ctrl+C` in the terminal.

-## Deploy app to Azure

-### Configure local git deployment

- <pre>

- </pre>

-1. Navigate to `http://<app_name>.azurewebsites.net/swagger` in a browser and play with the Swagger UI.

- 

-### Test CORS in sample app

-1. In Line 51, set the `apiEndpoint` variable to the URL of your deployed API (`http://<app_name>.azurewebsites.net`). Replace _\<appname>_ with your app name in App Service.

-1. Navigate to the browser app at `http://localhost:5000`. Open the developer tools window in your browser (`Ctrl`+`Shift`+`i` in Chrome for Windows) and inspect the **Console** tab. You should now see the error message, `No 'Access-Control-Allow-Origin' header is present on the requested resource`.

- 

- The domain mismatch between the browser app (`http://localhost:5000`) and remote resource (`http://<app_name>.azurewebsites.net`) is recognized by your browser as a cross-origin resource request. Also, the fact that your REST API the App Service app is not sending the `Access-Control-Allow-Origin` header, the browser has prevented cross-domain content from loading.

- In production, your browser app would have a public URL instead of the localhost URL, but the way to enable CORS to a localhost URL is the same as a public URL.

-In the Cloud Shell, enable CORS to your client's URL by using the [`az webapp cors add`](/cli/azure/webapp/cors#az-webapp-cors-add) command. Replace the _&lt;app-name>_ placeholder.

-You can add multiple allowed origins by running the command multiple times or by adding a comma-separate list in `--allowed-origins`. To allow all origins, use `--allowed-origins '*'`.

-

-You can use your own CORS utilities instead of App Service CORS for more flexibility. For example, you may want to specify different allowed origins for different routes or methods. Since App Service CORS lets you specify one set of accepted origins for all API routes and methods, you would want to use your own CORS code. See how ASP.NET Core does it at [Enabling Cross-Origin Requests (CORS)](/aspnet/core/security/cors).

-The built-in App Service CORS feature does not have options to allow only specific HTTP methods or verbs for each origin that you specify. It will automatically allow all methods and headers for each origin defined. This behavior is similar to [ASP.NET Core CORS](/aspnet/core/security/cors) policies when you use the options `.AllowAnyHeader()` and `.AllowAnyMethod()` in the code.

-> Don't try to use App Service CORS and your own CORS code together. When used together, App Service CORS takes precedence and your own CORS code has no effect.

-A wildcard subdomain like `*.contoso.com` is more restrictive than the wildcard origin `*`. However, the app's CORS management page in the Azure portal doesn't let you set a wildcard subdomain as an allowed origin. However, you can do it using the Azure CLI, like so:

-If your app requires credentials such as cookies or authentication tokens to be sent, the browser may require the `ACCESS-CONTROL-ALLOW-CREDENTIALS` header on the response. To enable this in App Service, set `properties.cors.supportCredentials` to `true`.

-This operation is not allowed when allowed origins include the wildcard origin `'*'`. Specifying `AllowAnyOrigin` and `AllowCredentials` is an insecure configuration and can result in cross-site request forgery. To allow credentials, try replacing the wildcard origin with [wildcard subdomains](#how-do-i-set-allowed-origins-to-a-wildcard-subdomain).

-> * Create App Service resources using Azure CLI

-> * Deploy a RESTful API to Azure using Git

-> * Enable App Service CORS support

-Advance to the next tutorial to learn how to authenticate and authorize users.

-# Monitor App Service instances using Health check

-This article uses Health check in the Azure portal to monitor App Service instances. Health check increases your application's availability by rerouting requests away from unhealthy instances and replacing instances if they remain unhealthy. It does that by pinging every minute a path of your web application of your choice.

-![Health check failure][1]

-Note that _/api/health_ is just an example added for illustration purposes. We don't create a Health Check path by default. You should make sure that the path you are selecting is a valid path that exists within your application

-## What App Service does with Health checks

->- At most one instance will be replaced per hour, with a maximum of three instances per day per App Service Plan.

->- If your health check is giving the status `Waiting for health check response` then the check is likely failing due to an HTTP status code of 307, which can happen if you have HTTPS redirect enabled but have `HTTPS Only` disabled.

-![Health check navigation in Azure portal][3]

-2. Under **Monitoring**, select **Health check**.

-3. Select **Enable** and provide a valid URL path on your application, such as `/health` or `/api/health`.

-4. Select **Save**.

-> - The Health check path should check critical components of your application. For example, if your application depends on a database and a messaging system, the Health check endpoint should connect to those components. If the application can't connect to a critical component, then the path should return a 500-level response code to indicate the app is unhealthy. Also, if the path does not return a response within 1 minute, the health check ping is considered unhealthy.

-> - When selecting the Health check path, make sure you're selecting a path that returns a 200 status code, only when the app is fully warmed up.

-> - In order to use Health check on your Function App, you must use a [premium or dedicated hosting plan](../azure-functions/functions-scale.md#overview-of-plans).

-> - Details about Health check on Function Apps can be found here: [Monitor function apps using Health check](../azure-functions/configure-monitoring.md?#monitor-function-apps-using-health-check).

-|`WEBSITE_HEALTHCHECK_MAXPINGFAILURES` | 2 - 10 | The required number of failed requests for an instance to be deemed unhealthy and removed from the load balancer. For example, when set to `2`, your instances are removed after `2` failed pings. (Default value is `10`) |

-|`WEBSITE_HEALTHCHECK_MAXUNHEALTHYWORKERPERCENT` | 1 - 100 | By default, no more than half of the instances will be excluded from the load balancer at one time to avoid overwhelming the remaining healthy instances. For example, if an App Service Plan is scaled to four instances and three are unhealthy, two are excluded. The other two instances (one healthy and one unhealthy) continue to receive requests. In the worst-case scenario where all instances are unhealthy, none are excluded. <br /> To override this behavior, set app setting to a value between `1` and `100`. A higher value means more unhealthy instances are removed (default value is `50`). |

-Health check integrates with App Service's [authentication and authorization features](overview-authentication-authorization.md). No other settings are required if these security features are enabled.

-If you're using your own authentication system, the Health check path must allow anonymous access. To secure the Health check endpoint, you should first use features such as [IP restrictions](app-service-ip-restrictions.md#set-an-ip-address-based-rule), [client certificates](app-service-ip-restrictions.md#set-an-ip-address-based-rule), or a Virtual Network to restrict application access. Once you have those features in-place, you can authenticate the health check request by inspecting the header, `x-ms-auth-internal-token`, and validating that it matches the SHA256 hash of the environment variable `WEBSITE_AUTH_ENCRYPTION_KEY`. If they match, then the health check request is valid and originating from App Service.

-> Specifically for [Azure Functions authentication](/azure/azure-functions/security-concepts?tabs=v4#function-access-keys), the function that serves as Health check endpoint needs to allow anonymous access.

-> The `x-ms-auth-internal-token` header is only available on Windows App Service.

-Once Health Check is enabled, you can restart and monitor the status of your application instances through the instances tab. The instances tab shows your instance's name, the status of that application's instance and gives you the option to manually restart the instance.

-If the status of your application instance is unhealthy, you can restart the instance manually using the restart button in the table. Keep in mind that any other applications hosted on the same App Service Plan as the instance will also be affected by the restart. If there are other applications using the same App Service Plan as the instance, they're listed on the opening blade from the restart button.

-If you restart the instance and the restart process fails, you'll then be given the option to replace the worker (only one instance can be replaced per hour). This will also affect any applications using the same App Service Plan.

-Windows applications will also have the option to view processes via the Process Explorer. This gives you further insight on the instance's processes including thread count, private memory, and total CPU time.

-For Windows applications, you have the option to collect diagnostic information in the Health Check tab. Enabling diagnostic collection adds an auto-heal rule that creates memory dumps for unhealthy instances and saves it to a designated storage account. Enabling this option changes auto-heal configurations. If there are existing auto-heal rules, we recommend setting this up through App Service diagnostics.

-Once diagnostic collection is enabled, you can create or choose an existing storage account for your files. You can only select storage accounts in the same region as your application. Keep in mind that saving restarts your application. After saving, if your site instances are found to be unhealthy after continuous pings, you can go to your storage account resource and view the memory dumps.

-After providing your application's Health check path, you can monitor the health of your site using Azure Monitor. From the **Health check** blade in the Portal, select the **Metrics** in the top toolbar. This opens a new blade where you can see the site's historical health status and option to create a new alert rule. Health check metrics aggregate the successful pings & display failures only when the instance was deemed unhealthy based on the health check configuration. For more information on monitoring your sites, [see the guide on Azure Monitor](web-sites-monitor.md).

-## Frequently Asked Questions

-If your app is only scaled to one instance and becomes unhealthy, it will not be removed from the load balancer because that would take down your application entirely. However, after one hour of continuous unhealthy pings, the instance is replaced. Scale out to two or more instances to get the rerouting benefit of Health check. If your app is running on a single instance, you can still use Health check's [monitoring](#monitoring) feature to keep track of your application's health.

-### Are the Health check requests sent over HTTP or HTTPS?

-On Windows and Linux App Service, the Health check requests are sent via HTTPS when [HTTPS Only](configure-ssl-bindings.md#enforce-https) is enabled on the site. Otherwise, they're sent over HTTP.

-### Is Health check following the application code configured redirects between the default domain and the custom domain?

-No, the Health check feature is pinging the path of the default domain of the web application. If there's a redirect from the default domain to a custom domain, then the status code that Health check is returning is not going to be a 200 but a redirect (301), which is going to mark the worker unhealthy.

-### What if I have multiple apps on the same App Service Plan?

-Unhealthy instances will always be removed from the load balancer rotation regardless of other apps on the App Service Plan (up to the percentage specified in [`WEBSITE_HEALTHCHECK_MAXUNHEALTHYWORKERPERCENT`](#configuration)). When an app on an instance remains unhealthy for over one hour, the instance will only be replaced if all other apps with Health check enabled are also unhealthy. Apps that don't have Health check enabled won't be taken into account.

-Imagine you have two applications (or one app with a slot) with Health check enabled, called App A and App B. They're on the same App Service Plan and that the Plan is scaled out to four instances. If App A becomes unhealthy on two instances, the load balancer stops sending requests to App A on those two instances. Requests are still routed to App B on those instances assuming App B is healthy. If App A remains unhealthy for over an hour on those two instances, those instances are only replaced if App B is **also** unhealthy on those instances. If App B is healthy, the instance isn't replaced.

-![Visual diagram explaining the example scenario above.][2]

-> If there were another site or slot on the Plan (Site C) without Health check enabled, it would not be taken into consideration for the instance replacement.

-In the scenario where all instances of your application are unhealthy, App Service will not remove instances from the load balancer. In this scenario, taking all unhealthy app instances out of the load balancer rotation would effectively cause an outage for your application; however, the instances replacement will still be honored.

-Yes, health check is available for the App Service Environment v3, but not for versions 1 or 2. If you are using the older versions of the App Service Environment, you can use the [migration feature](environment/migrate.md) to migrate your App Service Environment to version 3.

-[3]: ./media/app-service-monitor-instances-health-check/azure-portal-navigation-health-check.png

-## 1 - Sample application

-## 2 - Create a web app in Azure

-To host your application in Azure, you need to create Azure App Service web app in Azure. You can create a web app using the Azure CLI, [VS Code](https://code.visualstudio.com/), [Azure Tools extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack), or [Azure portal](https://portal.azure.com/).

-| [!INCLUDE [Create app service step 6](./includes/quickstart-python/create-app-service-visual-studio-code-6.md)] | :::image type="content" source="./media/quickstart-python/create-app-service-visual-studio-code-7-240-px.png" alt-text="A screenshot of the dialog box in VS Code used to a pricing tier for the new web app." lightbox="./media/quickstart-python/create-app-service-visual-studio-code-7.png"::: |

-| [!INCLUDE [Create app service step 7](./includes/quickstart-python/create-app-service-visual-studio-code-7.md)] | :::image type="content" source="./media/quickstart-python/create-app-service-visual-studio-code-7b-240-px.png" alt-text="A screenshot of the dialog box in VS Code used to start deploy to new web app." lightbox="./media/quickstart-python/create-app-service-visual-studio-code-7b.png"::: |

-## 3 - Deploy your application code to Azure

-Azure App service supports multiple methods to deploy your application code to Azure including support for GitHub Actions and all major CI/CD tools. This article focuses on how to deploy your code from your local workstation to Azure.

-Having issues? Refer first to the [Troubleshooting guide](./configure-language-python.md#troubleshooting), otherwise, [let us know](https://aka.ms/PythonAppServiceQuickstartFeedback).

-## 4 - Configure startup script

-## 5 - Browse to the app

-Browse to the deployed application in your web browser at the URL `http://<app-name>.azurewebsites.net`. If you see a default app page, wait a minute and refresh the browser.

-Having issues? Refer first to the [Troubleshooting guide](./configure-language-python.md#troubleshooting), otherwise, [let us know](https://aka.ms/PythonAppServiceQuickstartFeedback).

-## 6 - Stream logs

-Azure App Service captures all messages output to the console to assist you in diagnosing issues with your application. The sample apps include `print()` statements to demonstrate this capability.

-The contents of the App Service diagnostic logs can be reviewed using the Azure CLI, VS Code, or Azure portal.

-First, you need to configure Azure App Service to output logs to the App Service filesystem using the [az webapp log config](/cli/azure/webapp/log#az-webapp-log-config) command.

-| [!INCLUDE [Stream logs from Azure portal 1](./includes/quickstart-python/stream-logs-azure-portal-1.md)] | :::image type="content" source="./media/quickstart-python/stream-logs-azure-portal-1-240px.png" alt-text="A screenshot of the location in the Azure portal where to enable streaming logs." lightbox="./media/quickstart-python/stream-logs-azure-portal-1.png"::: |

-Having issues? Refer first to the [Troubleshooting guide](./configure-language-python.md#troubleshooting), otherwise, [let us know](https://aka.ms/PythonAppServiceQuickstartFeedback).

-When you're finished with the sample app, you can remove all of the resources for the app from Azure. It will not incur extra charges and keep your Azure subscription uncluttered. Removing the resource group also removes all resources in the resource group and is the fastest way to remove all Azure resources for your app.

-### [VS Code](#tab/vscode-aztools)

-> [Configure Python app](./configure-language-python.md)

-> [Tutorial: Run Python app in custom container](./tutorial-custom-container.md)

-> [Secure with custom domain and certificate](tutorial-secure-domain-certificate.md)

-[Azure App Service](overview.md) provides pre-defined application stacks on Windows like ASP.NET or Node.js, running on IIS. The preconfigured Windows environment locks down the operating system from:

-You can deploy a custom-configured Windows image from Visual Studio to make OS changes that your app needs. So it's easy to migrate on-premises app that requires custom OS and software configuration. This tutorial demonstrates how to migrate to App Service an ASP.NET app that uses custom fonts installed in the Windows font library. You deploy a custom-configured Windows image from Visual Studio to [Azure Container Registry](../container-registry/index.yml), and then run it in App Service.

-The sample project contains a simple ASP.NET application that uses a custom font that is installed into the Windows font library. It's not necessary to install fonts. However, the sample is an example of an app that is integrated with the underlying OS. To migrate such an app to App Service, you either rearchitect your code to remove the integration, or migrate it as-is in a custom Windows container.

-Type `Ctrl+F5` to run the app without debugging. The app is displayed in your default browser.

-[Azure Container Registry](../container-registry/index.yml) can store your images for container deployments. You can configure App Service to use images hosted in Azure Container Registry.

-### Open publish wizard

-### Create registry and publish

-### Sign in with Azure account

-In the **Create a new Azure Container Registry** dialog, select **Add an account**, and sign in to your Azure subscription. If you're already signed in, select the account containing the desired subscription from the dropdown.

-Configure the new container registry based on the suggested values in the following table. When finished, select **Create**.

-| Setting | Suggested value | For more information |

-| -- | | -|

-|**DNS Prefix**| Keep the generated registry name, or change it to another unique name. | |

-|**Resource Group**| Select **New**, type **myResourceGroup**, and select **OK**. | |

-|**SKU**| Basic | [Pricing tiers](https://azure.microsoft.com/pricing/details/container-registry/)|

-|**Registry Location**| West Europe | |

-A terminal window is opened and displays the image deployment progress. Wait for the deployment to complete.

-In the **Basics** tab, configure the settings according to the following table, then select **Next: Docker**.

-| Setting | Suggested value | For more information |

-| -- | | -|

-|**Subscription**| Make sure the correct subscription is selected. | |

-|**Resource Group**| Select **Create new**, type **myResourceGroup**, and select **OK**. | |

-|**Name**| Type a unique name. | The URL of the web app is `https://<app-name>.azurewebsites.net`, where `<app-name>` is your app name. |

-|**Publish**| Docker container | |

-|**Operating System**| Windows | |

-|**Region**| West Europe | |

-|**Windows Plan**| Select **Create new**, type **myAppServicePlan**, and select **OK**. | |

-### Configure Windows container

-In the **Docker** tab, configure your custom Windows container as shown in the following table, and select **Review + create**.

-When the Azure operation is complete, a notification box is displayed.

-Wait a few minutes and try again, until you get the homepage with the beautiful font you expect:

-## See container start-up logs

-It might take some time for the Windows container to load. To see the progress, go to the following URL by replacing *\<app-name>* with the name of your app.

-> Container should target x86-x64 architecture, ARM64 is not supported.

-> - Push a custom Docker image to Azure Container Registry

-> - Deploy the custom image to App Service

-> - Configure environment variables

-> - Pull image into App Service using a managed identity

-> - Access diagnostic logs

-> - Enable CI/CD from Azure Container Registry to App Service

-> - Connect to the container using SSH

-Completing this tutorial incurs a small charge in your Azure account for the container registry and can incur more costs for hosting the container for longer than a month.

-### Clone with git

-Ensure that you include the `--config core.autocrlf=input` argument to guarantee proper line endings in files that are used inside the Linux container:

-Then, navigate to the folder:

-Instead of using git clone, you can visit [https://github.com/Azure-Samples/docker-django-webapp-linux](https://github.com/Azure-Samples/docker-django-webapp-linux), select **Clone**, and then select **Download ZIP**.

-Then, open a terminal window in the*docker-django-webapp-linux* folder.

-The file in the sample named *Dockerfile* that describes the docker image and contains configuration instructions:

-> Docker Hub has [quotas on the number of anonymous pulls per IP and the number of authenticated pulls per free user (see **Data transfer**)](https://www.docker.com/pricing). If you notice your pulls from Docker Hub are being limited, try `docker login` if you're not already logged in.

- This [`docker run`](https://docs.docker.com/engine/reference/commandline/run/) command specifies the port with the `-p` argument followed by the name of the image. `-it` lets you stop it with `Ctrl+C`.

- > If you're running on Windows and see the error, *standard_init_linux.go:211: exec user process caused "no such file or directory"*, the *init.sh* file contains CR-LF line endings instead of the expected LF endings. This error happens if you used git to clone the sample repository but omitted the `--config core.autocrlf=input` parameter. In this case, clone the repository again with the `--config`` argument. You might also see the error if you edited *init.sh* and saved it with CRLF endings. In this case, save the file again with LF endings only.

-1. Browse to `http://localhost:8000` to verify the web app and container are functioning correctly.

- :::image type="content" source="./media/app-service-linux-using-custom-docker-image/app-service-linux-browse-local.png" alt-text="Test web app locally.":::

-App Service can either use a default managed identity or a user-assigned managed identity to authenticate with a container registry. In this tutorial, you'll use a user-assigned managed identity.

-1. Create a managed identity in the resource group.

- 1. In **Resource group**, select **Create new**, type the name *msdocs-custom-container-tutorial* for the resource group, then type **OK**.

- :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-managed-identity-3.png" alt-text="A screenshot showing how to complete managed identity create in the creation wizard." lightbox="./media/tutorial-custom-container/azure-portal-create-managed-identity-3.png":::

-1. Create a container registry with the [`az acr create`](/cli/azure/acr#az-acr-create) command and replace `<registry-name>` with a unique name for your registry. The name must contain only letters and numbers, and must be unique across all of Azure.

- The `--admin-enabled` parameter lets you push images to the registry using a set of administrative credentials.

-1. Retrieve the administrative credentials by running the [`az acr show`](/cli/azure/acr#az-acr-show) command:

- **II.B.** In the create wizard:

- 1. Copy the values of **Login server**, **Username**, and **password**. You'll use them in the next step to sign into the registry and push a docker image.

- Replace `<registry-name>` and `<registry-username>` with values from the previous steps. When prompted, type in one of the passwords from the previous step.

- For more information about these permissions, see [What is Azure role-based access control](../role-based-access-control/overview.md).

- 1. In the left navigation menu, select **Access control**.

- **IV.B.** Select **AcrPull** in the list.

- :::image type="content" source="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-2.png" alt-text="A screenshot showing how to enable pull permission on container registry." lightbox="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-2.png":::

- **IV.C.**:

- An App Service plan corresponds to the virtual machine that hosts the web app. By default, the previous command uses an inexpensive [B1 pricing tier](https://azure.microsoft.com/pricing/details/app-service/linux/) that is free for the first month. You can control the tier with the `--sku` parameter.

- Replace `<app-name>` with a name for the web app, which must be unique across all of Azure. Also replace `<registry-name>` with the name of your registry from the previous section.

- **V.D.** Back in the Create Web App wizard:

- :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-app-service-4.png" alt-text="A screenshot showing how to configure docker settings in the creation wizard." lightbox="./media/tutorial-custom-container/azure-portal-create-app-service-4.png":::

- For more information on this environment variable, see the [readme in the sample's GitHub repository](https://github.com/Azure-Samples/docker-django-webapp-linux).

-1. To test if your webhook is configured properly, ping the webhook, and see if you get a 200 OK response.

- > If you're streaming the container log, you should see the message after the webhook ping: `Starting container for site`, because the webhook triggers the app to restart.

- **VI.A.** In your web app's management page, select **Configuration**.

- **VI.B.** In the Configuration page:

- 1. In **Name**, type *WEBSITES_PORT*.

- 1. In **Value**, type *8000*.

- **VI.C.** In the left navigation menu, select **Identity**. Then do the following in the Identity page:

- **VI.E.** In the left navigation menu, select **Deployment Center**. Then do the following in the Deployment Center page:

- :::image type="content" source="./media/tutorial-custom-container/azure-portal-configure-app-service-5.png" alt-text="A screenshot showing a user-assigned managed identity selected for registry authentication and continuous deployment enabled." lightbox="./media/tutorial-custom-container/azure-portal-configure-app-service-5.png":::

- **VI.F.** In the Deployment Center page, select the **Logs** tab. Here, you can see log messages for pulling the image and starting the container. Later, you'll learn how to see console message generated from within the container.

-To test the app, browse to `https://<app-name>.azurewebsites.net`, replacing `<app-name>` with the name of your web app.

- **VII.A.** In the App Service page:

-On first access, it might take some time for the app to respond because App Service must pull the entire image from the registry. If the browser times out, just refresh the page. Once the initial image is pulled, subsequent tests will run much faster.

-1. To stop log streaming at any time, type `Ctrl+C`.

-In the Deployment Center page, you can already see the log messages for pulling and starting the container. In this step, you can enable logging of the console output from within the container.

- **VIII.A.** In the App Service page:

- :::image type="content" source="./media/tutorial-custom-container/azure-portal-stream-diagnostic-logs-1.png" alt-text="A screenshot showing how to enable diagnostic logging for custom container." lightbox="./media/tutorial-custom-container/azure-portal-stream-diagnostic-logs-1.png":::

-1. Update the image's tag to latest:

-1. When the image push is complete, the webhook notifies the App Service about the push, and App Service tries to pull in the updated image. Wait a few minutes, and then verify that the update has been deployed by browsing to `https://<app-name>.azurewebsites.net`.

-SSH enables secure communication between a container and a client. To enable SSH connection to your container, your custom image must be configured for it. When the container is running, you can open an SSH connection.

-> root:Docker! should not be altered SSH. SCM/KUDU will use your Azure Portal credentials. Changing this value will result in an error when using SSH.

-### Open SSH connection to container

- For example, you can examine the processes running within it using the `top` command.

- **X.A.** In the App Service page:

- **X.B.** The SSH session is opened in a new browser tab. Wait for the status bar at the bottom to show a green `SSH CONNECTION ESTABLISHED`. You can then run commands from within the container. Configuration changes made to your container aren't persisted across app restarts.

- **XI.B.** In the resource group page, select **Delete resource group**.

- :::image type="content" source="./media/tutorial-custom-container/azure-portal-delete-resource-group-2.png" alt-text="A screenshot showing the location of the Delete Resource Group button in the Azure portal." lightbox="./media/tutorial-custom-container/azure-portal-delete-resource-group-2.png":::

- :::image type="content" source="./media/tutorial-custom-container/azure-portal-delete-resource-group-3.png" alt-text="A screenshot of the confirmation dialog for deleting a resource group in the Azure portal." lightbox="./media/tutorial-custom-container/azure-portal-delete-resource-group-3.png"::::

-> - Deploy a custom image to a private container registry

-> - Deploy and the custom image in App Service

-> - Update and redeploy the image

-> - Access diagnostic logs

-> - Connect to the container using SSH

-> - Push a custom Docker image to Azure Container Registry

-> - Deploy the custom image to App Service

-> - Configure environment variables

-> - Pull image into App Service using a managed identity

-> - Access diagnostic logs

-> - Enable CI/CD from Azure Container Registry to App Service

-> - Connect to the container using SSH

-In the next tutorial, you learn how to secure your app with a custom domain and certificate.

-> [Secure with custom domain and certificate](tutorial-secure-domain-certificate.md)

-> [Configure custom container](configure-custom-container.md)

-> [!div class="nextstepaction"]

-> [Configure sidecar](configure-custom-container.md)

-## 1. Create App Service, database, and cache

- **Step 1:** In the App Service page,

- **Step 8:** To verify that your changes:

-## 3. Deploy sample code

-## 4. Generate database schema

-## 5. Browse to the app

-## 6. Stream diagnostic logs

-## 7. Clean up resources

- The `azd up` command takes about 15 minutes to complete (the Redis cache take the most time). It also compiles and deploys your application code, but you'll modify your code later to work with App Service. While it's running, the command provides messages about the provisioning and deployment process, including a link to the deployment in Azure. When it finishes, the command also displays a link to the deploy application.

-## 4. Generate database schema

- **Step 1:** In the App Service page,

- **Step 7:** To verify that you secured the secrets:

- 1. Ask, "*@workspace why do i get the error in GitHub actions: The string 'java21' is not valid SemVer notation for a Java version.*" Copilot might give you an explanation and even give you the link to the workflow file that you need to fix.

- The `azd up` command takes about 15 minutes to complete (the Redis cache take the most time). It also compiles and deploys your application code, but you'll modify your code later to work with App Service. While it's running, the command provides messages about the provisioning and deployment process, including a link to the deployment in Azure. When it finishes, the command also displays a link to the deploy application.

-* The **Name** for the web app. It's the name used as part of the DNS name for your app in the form of `https://<app-name>.azurewebsites.net`.

- - **Azure Database for MySQL flexible server**: Accessible only from behind its private endpoint. A database and a user are created for you on the server.

- - **Private DNS zones**: Enable DNS resolution of the database server and the Redis cache in the virtual network.

-## 3. Verify connection settings

-The creation wizard generated the connectivity string for you already as [app settings](configure-common.md#configure-app-settings). In this step, you learn where to find the app settings, and how you can create your own.

-App settings are one way to keep connection secrets out of your code repository. When you're ready to move your secrets to a more secure location, you can use [Key Vault references](app-service-key-vault-references.md) instead.

- **Step 1:** In the App Service page, in the left menu, select **Configuration**.

- :::image type="content" source="./media/tutorial-java-tomcat-mysql-app/azure-portal-get-connection-string-1.png" alt-text="A screenshot showing how to open the configuration page in App Service." lightbox="./media/tutorial-java-tomcat-mysql-app/azure-portal-get-connection-string-1.png":::

- **Step 2:**

- 1. In the **Application settings** tab of the **Configuration** page, find the app setting `AZURE_MYSQL_CONNECTIONSTRING`. The creation wizard created it for you.

- 1. If you want, you can select the **Edit** button to the right of each setting and see or copy its value, or select Add to add a variable to inject into your Tomcat container. If you add an app setting that contains a valid Oracle, SQL Server, PostgreSQL, or MySQL connection string, App Service adds it as a Java Naming and Directory Interface (JNDI) data source in the Tomcat server's *context.xml* file.

- :::image type="content" source="./media/tutorial-java-tomcat-mysql-app/azure-portal-get-connection-string-2.png" alt-text="A screenshot showing how to see the autogenerated connection string." lightbox="./media/tutorial-java-tomcat-mysql-app/azure-portal-get-connection-string-2.png":::

-In this step, you use the SSH connection to the app container to verify the JNDI data source in the Tomcat server. In the process, you learn how to access the SSH shell for the Tomcat container.

- **Step 1:** Back in the App Service page,

- 1. Select the URL of your app. You can also navigate directly to `https://<app-name>.azurewebsites.net`.

- |Enter a new environment name | Type a unique name. The AZD template uses this name as part of the DNS name of your web app in Azure (`<app-name>.azurewebsites.net`). Alphanumeric characters and hyphens are allowed. |

- The `azd up` command takes about 15 minutes to complete (the Redis cache take the most time). It also compiles and deploys your application code, but you'll modify your code later to work with App Service. While it's running, the command provides messages about the provisioning and deployment process, including a link to the deployment in Azure. When it finishes, the command also displays a link to the deploy application.

- - **Azure Database for MySQL flexible server**: Accessible only from behind its private endpoint. A database is created for you on the server.

- - **Private DNS zones**: Enable DNS resolution of the database server and the Redis cache in the virtual network.

-1. In the AZD output, find the app setting `AZURE_MYSQL_CONNECTIONSTRING`. To keep secrets safe, only the setting names are displayed. They look like this in the AZD output:

-

- Open SSH session to App Service container at: https://&lt;app-name>.scm.azurewebsites.net/webssh/host

- - Endpoint: https://&lt;app-name>.azurewebsites.net/

-> - Azure Automation Update Management has retired on **31 August 2024**. Follow the guidelines for [migration to Azure Update Manager](../../update-manager/guidance-migration-automation-update-management-azure-update-manager.md).

-> - Azure Log Analytics agent, also known as the Microsoft Monitoring Agent (MMA) has [retired in August 2024](https://azure.microsoft.com/updates/were-retiring-the-log-analytics-agent-in-azure-monitor-on-31-august-2024/). Azure Automation Update Management solution relies on this agent and may encounter issues once the agent is retired as it does not work with Azure Monitoring Agent (AMA). Therefore, if you are using the Azure Automation Update Management solution, we recommend that you move to Azure Update Manager for your software update needs. All the capabilities of Azure Automation Update management solution will be available on Azure Update Manager before the retirement date. Follow the [guidance](../../update-center/guidance-migration-automation-update-management-azure-update-manager.md) to move your machines and schedules from Automation Update Management to Azure Update Manager.

-# Passing Contextual Information

-## Prerequisites

-Application developers who build apps that send email using the SMTP protocol need to implement secure, modern authentication. Azure Communication Services does this by leveraging Entra application service principals. Combining the Azure Communication Services Resource and the Entra application service principal's information, the SMTP services undertakes authentication with Entra on the user's behalf to ensure a secure and seamless email transmission.

-### Creating a custom email role for the Entra application

-The Entra application must be assigned a role with both the **Microsoft.Communication/CommunicationServices/Read** and the **Microsoft.Communication/EmailServices/write** permissions on the Azure Communication Service Resource. This can be done either by using the **Contributor** role, or by creating a **custom role**. Follow these steps to create a custom role by cloning an existing role.

-1. Select the **Microsoft.Communication/CommunicationServices** **Read** and the **Microsoft.Communication/EmailServices** **Write*** permissions. Click **Add**.

-When assigning the Entra application a role for the Azure Communication Services Resource, the new custom role will be available. For more information on creating custom roles, see [Create or update Azure custom roles using the Azure portal](../../../../role-based-access-control/custom-roles-portal.md)

-### Assigning the custom email role to the Entra application

-1. Use the search box to find the **Entra** application that you'll use for authentication and select it. Then click **Select**.

- :::image type="content" source="../media/email-smtp-select-entra.png" alt-text="Screenshot that shows selecting the Entra application.":::

-### Creating the SMTP credentials from the Entra application information.

-Azure Communication Services allows the credentials for an Entra application to be used as the SMTP username and password. The username consists of the following three parts and can be pipe or dot delimited.

-1. The Entra Application ID.

- :::image type="content" source="../media/email-smtp-entra-details.png" alt-text="Screenshot that shows finding the Entra Application ID.":::

-1. The Entra Tenant ID.

- :::image type="content" source="../media/email-smtp-entra-tenant.png" alt-text="Screenshot that shows finding the Entra Tenant ID.":::

-username: <Azure Communication Services Resource name>.<Entra Application ID>.<Entra Tenant ID>

-username: <Azure Communication Services Resource name>|<Entra Application ID>|<Entra Tenant ID>

-The password is one of the Entra application's client secrets.

- :::image type="content" source="../media/email-smtp-entra-secret.png" alt-text="Screenshot that shows finding the Entra client secret.":::

-|Username and password | Enter the Entra application credentials from an application with access to the Azure Communication Services Resource |

-description: Learn how to set up an automated process to provision and retire IoT devices in Azure Digital Twins using Device Provisioning Service (DPS).

-# Optional fields. Don't forget to remove # if you need a field.

-#

-#

-# Automanage devices in Azure Digital Twins using Device Provisioning Service (DPS)

-In this article, you'll learn how to integrate Azure Digital Twins with [Device Provisioning Service (DPS)](../iot-dps/about-iot-dps.md).

-The solution described in this article will allow you to automate the process to provision and retire IoT Hub devices in Azure Digital Twins, using Device Provisioning Service.

-For more information about the provision and retire stages, and to better understand the set of general device management stages that are common to all enterprise IoT projects, see the [Device lifecycle section](../iot-hub/iot-hub-device-management-overview.md#device-lifecycle) of IoT Hub's device management documentation.

-## Prerequisites

-Before you can set up the provisioning, you'll need to set up the following resources:

-* An Azure Digital Twins instance. Follow the instructions in [Set up an instance and authentication](how-to-set-up-instance-portal.md) to create an Azure digital twins instance. Gather the instance's **host name** in the Azure portal ([instructions](how-to-set-up-instance-portal.md#verify-success-and-collect-important-values)).

-* An IoT hub. For instructions, see the "Create an IoT Hub" section of [the IoT Hub quickstart](../iot-hub/quickstart-send-telemetry-cli.md).

-* An [Azure function](../azure-functions/functions-overview.md) that updates digital twin information based on IoT Hub data. Follow the instructions in [Ingest IoT hub data](how-to-ingest-iot-hub-data.md) to create this Azure function. Gather the function **name** to use it in this article.

-This sample also uses a *device simulator* that includes provisioning using the Device Provisioning Service. The device simulator is located here: [Azure Digital Twins and IoT Hub Integration Sample](https://github.com/Azure-Samples/digital-twins-iothub-integration). Get the sample project on your machine by navigating to the GitHub repo for the sample, which you can download as a .zip file by selecting the **Code** button and **Download ZIP**.

-Unzip the downloaded folder.

-You'll need [Node.js](https://nodejs.org) installed on your machine. The device simulator is based on Node.js, version 10.0.x or later.

-## Solution architecture

-This solution includes steps for provisioning and retiring a device in Azure Digital Twins, using Device Provisioning Service.

-To allocate devices in the solution, data flows between a thermostat device and DPS. The data then flows from DPS into IoT Hub, and to Azure Digital Twins through an Azure function.

-To retire a device, data from a manual device deletion flows into Azure Digital Twins through IoT Hub, Event Hubs, and an Azure function.

-The image below illustrates this architecture.

-This article is divided into two sections, each focused on a portion of this full architecture:

-* [Autoprovision device using Device Provisioning Service](#autoprovision-device-using-device-provisioning-service)

-* [Autoretire device using IoT Hub lifecycle events](#autoretire-device-using-iot-hub-lifecycle-events)

-## Autoprovision device using Device Provisioning Service

-In this section, you'll be attaching Device Provisioning Service to Azure Digital Twins to autoprovision devices through the path below. This diagram is an excerpt from the full architecture shown [earlier](#solution-architecture).

-Here's a description of the process flow:

-1. Device contacts the DPS endpoint, passing identifying information to prove its identity.

-2. DPS validates device identity by validating the registration ID and key against the enrollment list, and calls an [Azure function](../azure-functions/functions-overview.md) to do the allocation.

-3. The Azure function creates a new [twin](concepts-twins-graph.md) in Azure Digital Twins for the device. The twin will have the same name as the device's **registration ID**.

-4. DPS registers the device with an IoT hub, and populates the device's chosen twin state.

-5. The IoT hub returns device ID information and the IoT hub connection information to the device. The device can now connect to the IoT hub.

-The following sections walk through the steps to set up this autoprovision device flow.

-### Create a Device Provisioning Service

-When a new device is provisioned using Device Provisioning Service, a new twin for that device can be created in Azure Digital Twins with the same name as the registration ID.

-Create a Device Provisioning Service instance, which will be used to provision IoT devices. You can either use the Azure CLI instructions below, or use the Azure portal by following [Set up the IoT Hub Device Provisioning Service with the Azure portal](../iot-dps/quick-setup-auto-provision.md).

-The following Azure CLI command will create a Device Provisioning Service. You'll need to specify a Device Provisioning Service name, resource group, and region. To see what regions support Device Provisioning Service, visit [Azure products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=iot-hub).

-The command can be run in [Cloud Shell](https://shell.azure.com), or locally if you have the [Azure CLI installed on your machine](/cli/azure/install-azure-cli).

-```azurecli-interactive

-az iot dps create --name <Device-Provisioning-Service-name> --resource-group <resource-group-name> --location <region>

-```

-### Add a function to use with Device Provisioning Service

-Inside your function app project that you created in the [Prerequisites section](#prerequisites), you'll create a new function to use with the Device Provisioning Service. This function will be used by the Device Provisioning Service in a [Custom Allocation Policy](../iot-dps/how-to-use-custom-allocation-policies.md) to provision a new device.

-Navigate to the function app project on your machine and follow the steps below.

-1. First, create a new function of type **HTTP-trigger** in the function app project.

-2. Add a new NuGet package to the project: [Microsoft.Azure.Devices.Provisioning.Service](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Service/). You might need to add more packages to your project as well, if the packages used in the code aren't part of the project already.

-3. In the newly created function code file, paste in the following code, name the function *DpsAdtAllocationFunc.cs*, and save the file.

- :::code language="csharp" source="~/digital-twins-docs-samples-dps/functions/DpsAdtAllocationFunc.cs":::

-4. Publish the project with the *DpsAdtAllocationFunc.cs* function to a function app in Azure.

- For instructions on how to publish the function using **Visual Studio**, see [Develop Azure Functions using Visual Studio](../azure-functions/functions-develop-vs.md#publish-to-azure). For instructions on how to publish the function using **Visual Studio Code**, see [Create a C# function in Azure using Visual Studio Code](../azure-functions/create-first-function-vs-code-csharp.md?tabs=in-process#publish-the-project-to-azure). For instructions on how to publish the function using the **Azure CLI**, see [Create a C# function in Azure from the command line](../azure-functions/create-first-function-cli-csharp.md?tabs=azure-cli%2Cin-process#deploy-the-function-project-to-azure).

-> [!IMPORTANT]

-> When creating the function app for the first time in the [Prerequisites section](#prerequisites), you may have already assigned an access role for the function and configured the application settings for it to access your Azure Digital Twins instance. These need to be done once for the entire function app, so verify they've been completed in your app before continuing. You can find instructions in the [Configure published app](how-to-authenticate-client.md#configure-published-app) section of the *Write app authentication code* article.

-### Create Device Provisioning enrollment

-Next, you'll need to create an enrollment in Device Provisioning Service using a *custom allocation function*. To create an enrollment, follow the instructions in the [Create the enrollment](../iot-dps/how-to-use-custom-allocation-policies.md#create-the-enrollment) section of the custom allocation policies article in the Device Provisioning Service documentation.

-While going through that flow, make sure you select the following options to link the enrollment to the function you created.

-* **Select how you want to assign devices to hubs**: Custom (Use Azure Function).

-* **Select the IoT hubs this group can be assigned to:** Choose your IoT hub name or select the **Link a new IoT hub** button, and choose your IoT hub from the options.

-Next, choose the **Select a new function** button to link your function app to the enrollment group. Then, fill in the following values:

-* **Subscription**: Your Azure subscription is autopopulated. Make sure it's the right subscription.

-* **Function App**: Choose your function app name.

-* **Function**: Choose *DpsAdtAllocationFunc*.

-Save your details.

-After creating the enrollment, select it to view its settings. Copy the **Primary Key** for the enrollment, which will be used later in this article to configure the device simulator.

-### Set up the device simulator

-This sample uses a device simulator that includes provisioning using the Device Provisioning Service. The device simulator is located in the [Azure Digital Twins and IoT Hub Integration Sample](https://github.com/Azure-Samples/digital-twins-iothub-integration) that you downloaded in the [Prerequisites section](#prerequisites).

-#### Upload the model

-The device simulator is a thermostat-type device that uses the model with this ID: `dtmi:contosocom:DigitalTwins:Thermostat;1`. You'll need to upload this model to Azure Digital Twins before you can create a twin of this type for the device.

-The model looks like this:

-To upload this model to your twins instance, run the following Azure CLI command, which uploads the above model as inline JSON. You can run the command in [Azure Cloud Shell](../cloud-shell/overview.md) in your browser (use the Bash environment), or on your machine if you have the [CLI installed locally](/cli/azure/install-azure-cli). There's one placeholder for the instance's host name (you can also use the instance's friendly name with a slight decrease in performance).

-```azurecli-interactive

-az dt model create --dt-name <instance-hostname-or-name> --models '{ "@id": "dtmi:contosocom:DigitalTwins:Thermostat;1", "@type": "Interface", "@context": "dtmi:dtdl:context;2", "contents": [ { "@type": "Property", "name": "Temperature", "schema": "double" } ]}'

-```

->[!NOTE]

->If you're using anything other than Cloud Shell in the Bash environment, you may need to escape certain characters in the inline JSON so that it's parsed correctly. For more information, see [Use special characters in different shells](concepts-cli.md#use-special-characters-in-different-shells).

-For more information about models, see [Manage models](how-to-manage-model.md#upload-models).

-#### Configure and run the simulator

-In a command window on your local machine, navigate to the downloaded sample *Azure Digital Twins and IoT Hub Integration* that you unzipped earlier, and then into the *device-simulator* directory. Next, install the dependencies for the project using the following command:

-```cmd

-npm install

-```

-Next, in your device simulator directory, copy the *.env.template* file to a new file called *.env*, and gather the following values to fill in the settings:

-* PROVISIONING_IDSCOPE: To get this value, navigate to your device provisioning service in the [Azure portal](https://portal.azure.com/), then select **Overview** in the menu options and look for the field **ID Scope**.

- :::image type="content" source="media/how-to-provision-using-device-provisioning-service/id-scope.png" alt-text="Screenshot of the Azure portal view of the device provisioning overview page highlighting the ID Scope value." lightbox="media/how-to-provision-using-device-provisioning-service/id-scope.png":::

-* PROVISIONING_REGISTRATION_ID: You can choose a registration ID for your device.

-* ADT_MODEL_ID: `dtmi:contosocom:DigitalTwins:Thermostat;1`

-* PROVISIONING_SYMMETRIC_KEY: This environment variable is the primary key for the enrollment you set up earlier. To get this value again, navigate to your device provisioning service in the Azure portal, select **Manage enrollments**, then select the enrollment group that you created earlier and copy the **Primary Key**.

- :::image type="content" source="media/how-to-provision-using-device-provisioning-service/sas-primary-key.png" alt-text="Screenshot of the Azure portal view of the device provisioning service manage enrollments page highlighting the SAS primary key value." lightbox="media/how-to-provision-using-device-provisioning-service/sas-primary-key.png":::

-Now, use the values above to update the *.env* file settings.

-```cmd

-PROVISIONING_HOST = "global.azure-devices-provisioning.net"

-PROVISIONING_IDSCOPE = "<Device-Provisioning-Service-Scope-ID>"

-PROVISIONING_REGISTRATION_ID = "<Device-Registration-ID>"

-ADT_MODEL_ID = "dtmi:contosocom:DigitalTwins:Thermostat;1"

-PROVISIONING_SYMMETRIC_KEY = "<Device-Provisioning-Service-enrollment-primary-SAS-key>"

-```

-Save and close the file.

-### Start running the device simulator

-Still in the *device-simulator* directory in your command window, start the device simulator using the following command:

-```cmd

-node .\adt_custom_register.js

-```

-You should see the device being registered and connected to IoT Hub, and then starting to send messages.

-### Validate

-The flow you've set up in this article will result in the device automatically being registered in Azure Digital Twins. Use the following [Azure Digital Twins CLI](/cli/azure/dt/twin#az-dt-twin-show) command to find the twin of the device in the Azure Digital Twins instance you created. There's a placeholder for the instance's host name (you can also use the instance's friendly name with a slight decrease in performance), and a placeholder for the device registration ID.

-```azurecli-interactive

-az dt twin show --dt-name <instance-hostname-or-name> --twin-id "<device-registration-ID>"

-```

-You should see the twin of the device being found in the Azure Digital Twins instance.

-## Autoretire device using IoT Hub lifecycle events

-In this section, you'll be attaching IoT Hub lifecycle events to Azure Digital Twins to autoretire devices through the path below. This diagram is an excerpt from the full architecture shown [earlier](#solution-architecture).

-Here's a description of the process flow:

-1. An external or manual process triggers the deletion of a device in IoT Hub.

-2. IoT Hub deletes the device and generates a [device lifecycle](../iot-hub/iot-hub-device-management-overview.md#device-lifecycle) event that will be routed to an [event hub](../event-hubs/event-hubs-about.md).

-3. An Azure function deletes the twin of the device in Azure Digital Twins.

-The following sections walk through the steps to set up this autoretire device flow.

-### Create an event hub

-Next, you'll create an Azure [event hub](../event-hubs/event-hubs-about.md) to receive IoT Hub lifecycle events.

-Follow the steps described in the [Create an event hub](../event-hubs/event-hubs-create.md) quickstart. Name your event hub *lifecycleevents*. You'll use this event hub name when you set up IoT Hub route and an Azure function in the next sections.

-The screenshot below illustrates the creation of the event hub.

-#### Create SAS policy for your event hub

-Next, you'll need to create a [shared access signature (SAS) policy](../event-hubs/authorize-access-shared-access-signature.md) to configure the event hub with your function app.

-To create the SAS policy:

-1. Navigate to the event hub you created in the Azure portal and select **Shared access policies** in the menu options on the left.

-2. Select **Add**. In the **Add SAS Policy** window that opens, enter a policy name of your choice and select the **Listen** checkbox.

-3. Select **Create**.

-

-#### Configure event hub with function app

-Next, configure the Azure function app that you set up in the [Prerequisites section](#prerequisites) to work with your new event hub. You'll configure the function by setting an environment variable inside the function app with the event hub's connection string.

-1. Open the policy that you created and copy the **Connection string-primary key** value.

- :::image type="content" source="media/how-to-provision-using-device-provisioning-service/event-hub-sas-policy-connection-string.png" alt-text="Screenshot of the Azure portal showing how to copy the connection string-primary key." lightbox="media/how-to-provision-using-device-provisioning-service/event-hub-sas-policy-connection-string.png":::

-2. Add the connection string as a variable in the function app settings with the following Azure CLI command. The command can be run in [Cloud Shell](https://shell.azure.com), or locally if you have the [Azure CLI installed on your machine](/cli/azure/install-azure-cli).

- ```azurecli-interactive

- az functionapp config appsettings set --settings "EVENTHUB_CONNECTIONSTRING=<Event-Hubs-SAS-connection-string-Listen>" --resource-group <resource-group> --name <your-function-app-name>

- ```

-### Add a function to retire with IoT Hub lifecycle events

-Inside your function app project that you created in the [Prerequisites section](#prerequisites), you'll create a new function to retire an existing device using IoT Hub lifecycle events.

-For more about lifecycle events, see [IoT Hub Non-telemetry events](../iot-hub/iot-hub-devguide-messages-d2c.md#non-telemetry-events). For more information about using Event Hubs with Azure functions, see [Azure Event Hubs trigger for Azure Functions](../azure-functions/functions-bindings-event-hubs-trigger.md).

-Navigate to the function app project on your machine and follow the steps below.

-1. First, create a new function of type **Event Hub Trigger** in the function app project.

-2. Add a new NuGet package to the project: [Microsoft.Azure.Devices.Provisioning.Service](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Service/). You might need to add more packages to your project as well, if the packages used in the code aren't part of the project already.

-3. In the newly created function code file, paste in the following code, name the function *DeleteDeviceInTwinFunc.cs*, and save the file.

- :::code language="csharp" source="~/digital-twins-docs-samples-dps/functions/DeleteDeviceInTwinFunc.cs":::

-4. Publish the project with the *DeleteDeviceInTwinFunc.cs* function to a function app in Azure.

- For instructions on how to publish the function using **Visual Studio**, see [Develop Azure Functions using Visual Studio](../azure-functions/functions-develop-vs.md#publish-to-azure). For instructions on how to publish the function using **Visual Studio Code**, see [Create a C# function in Azure using Visual Studio Code](../azure-functions/create-first-function-vs-code-csharp.md?tabs=in-process#publish-the-project-to-azure). For instructions on how to publish the function using the **Azure CLI**, see [Create a C# function in Azure from the command line](../azure-functions/create-first-function-cli-csharp.md?tabs=azure-cli%2Cin-process#deploy-the-function-project-to-azure).

-> [!IMPORTANT]

-> When creating the function app for the first time in the [Prerequisites section](#prerequisites), you may have already assigned an access role for the function and configured the application settings for it to access your Azure Digital Twins instance. These need to be done once for the entire function app, so verify they've been completed in your app before continuing. You can find instructions in the [Configure published app](how-to-authenticate-client.md#configure-published-app) section of the *Write app authentication code* article.

-### Create an IoT Hub route for lifecycle events

-Now you'll set up an IoT Hub route, to route device lifecycle events. In this case, you'll specifically listen to device delete events, identified by `if (opType == "deleteDeviceIdentity")`. This event will trigger the delete of the digital twin item, completing the retirement process of a device and its digital twin.

-First, you'll need to create an event hub endpoint in your IoT hub. Then, you'll add a route in IoT hub to send lifecycle events to this event hub endpoint.

-Follow these steps to create an event hub endpoint:

-1. In the [Azure portal](https://portal.azure.com/), navigate to the IoT hub you created in the [Prerequisites section](#prerequisites) and select **Message routing** in the menu options on the left.

-2. Select the **Custom endpoints** tab.

-3. Select **+ Add** and choose **Event hubs** to add an Event Hubs type endpoint.

- :::image type="content" source="media/how-to-provision-using-device-provisioning-service/event-hub-custom-endpoint.png" alt-text="Screenshot of the Azure portal showing how to add an Event Hubs custom endpoint." lightbox="media/how-to-provision-using-device-provisioning-service/event-hub-custom-endpoint.png":::

-4. In the window **Add an event hub endpoint** that opens, choose the following values:

- * **Endpoint name**: Choose an endpoint name.

- * **Event hub namespace**: Select your event hub namespace from the dropdown list.

- * **Event hub instance**: Choose the event hub name that you created in the previous step.

-5. Select **Create**. Keep this window open to add a route in the next step.

- :::image type="content" source="media/how-to-provision-using-device-provisioning-service/add-event-hub-endpoint.png" alt-text="Screenshot of the Azure portal showing how to add an event hub endpoint." lightbox="media/how-to-provision-using-device-provisioning-service/add-event-hub-endpoint.png":::

-Next, you'll add a route that connects to the endpoint you created in the above step, with a routing query that sends the delete events. Follow these steps to create a route:

-1. Navigate to the **Routes** tab and select **Add** to add a route.

- :::image type="content" source="media/how-to-provision-using-device-provisioning-service/add-message-route.png" alt-text="Screenshot of the Azure portal showing how to add a route to send events." lightbox="media/how-to-provision-using-device-provisioning-service/add-message-route.png":::

-2. In the **Add a route** page that opens, choose the following values:

- * **Name**: Choose a name for your route.

- * **Endpoint**: Choose the Event Hubs endpoint you created earlier from the dropdown.

- * **Data source**: Choose **Device Lifecycle Events**.

- * **Routing query**: Enter `opType='deleteDeviceIdentity'`. This query limits the device lifecycle events to only send the delete events.

-3. Select **Save**.

- :::image type="content" source="media/how-to-provision-using-device-provisioning-service/lifecycle-route.png" alt-text="Screenshot of the Azure portal showing how to add a route to send lifecycle events." lightbox="media/how-to-provision-using-device-provisioning-service/lifecycle-route.png":::

-Once you've gone through this flow, everything is set to retire devices end-to-end.

-### Validate

-To trigger the process of retirement, you need to manually delete the device from IoT Hub.

-You can manually delete the device from IoT Hub with an [Azure CLI command](/cli/azure/iot/hub/module-identity#az-iot-hub-module-identity-delete) or in the Azure portal.

-Follow the steps below to delete the device in the Azure portal:

-1. Navigate to your IoT hub, and choose **IoT devices** in the menu options on the left.

-2. You'll see a device with the device registration ID you chose in the [first half of this article](#autoprovision-device-using-device-provisioning-service). You can also choose any other device to delete, as long as it has a twin in Azure Digital Twins so you can verify that the twin is automatically deleted after the device is deleted.

-3. Select the device and choose **Delete**.

-It might take a few minutes to see the changes reflected in Azure Digital Twins.

-Use the following [Azure Digital Twins CLI](/cli/azure/dt/twin#az-dt-twin-show) command to verify the twin of the device in the Azure Digital Twins instance was deleted. There's a placeholder for the instance's host name (you can also use the instance's friendly name with a slight decrease in performance), and a placeholder for the device registration ID.

-```azurecli-interactive

-az dt twin show --dt-name <instance-hostname-or-name> --twin-id "<device-registration-ID>"

-```

-You should see that the twin of the device cannot be found in the Azure Digital Twins instance anymore.

-## Clean up resources

-If you no longer need the resources created in this article, follow these steps to delete them.

-Using the Azure Cloud Shell or local Azure CLI, you can delete all Azure resources in a resource group with the [az group delete](/cli/azure/group#az-group-delete) command. This command removes the resource group; the Azure Digital Twins instance; the IoT hub and the hub device registration; the Event Grid topic and associated subscriptions; the Event Hubs namespace and both Azure Functions apps, including associated resources like storage.

-> [!IMPORTANT]

-> Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you do not accidentally delete the wrong resource group or resources.

-```azurecli-interactive

-az group delete --name <your-resource-group>

-```

-Then, delete the project sample folder you downloaded from your local machine.

-## Next steps

-The digital twins created for the devices are stored as a flat hierarchy in Azure Digital Twins, but they can be enriched with model information and a multi-level hierarchy for organization. To learn more about this concept, read:

-* [Digital twins and the twin graph](concepts-twins-graph.md)

-For more information about using HTTP requests with Azure functions, see:

-* [Azure Http request trigger for Azure Functions](../azure-functions/functions-bindings-http-webhook-trigger.md)

-You can write custom logic to automatically provide this information using the model and graph data already stored in Azure Digital Twins. To read more about managing, upgrading, and retrieving information from the twins graph, see the following how-to guides:

-* [Manage a digital twin](how-to-manage-twin.md)

-* [Query the twin graph](how-to-query-graph.md)

-| **clientid** | Application client registration ID | - |

-| **clientsecret** | Application client registration secret | - |

-Enter `{{fhirurl}}/metadata` in the `GET`request, and then choose `Send`. You should see the capability statement of the FHIR service.

-Get a Microsoft Entra access token by using a service principal or a Microsoft Entra user account. Choose one of the two methods.

-3. Select the **Test** tab and enter in the text section: `pm.environment.set("bearerToken", pm.response.json().access_token);` To make the value available to the collection, use the pm.collectionVariables.set method. For more information on the set method and its scope level, see [Using variables in scripts](https://learning.postman.com/docs/sending-requests/variables/#defining-variables-in-scripts).

-5. Select **Send**. You should see a response with the Microsoft Entra access token, which is saved to the variable `bearerToken` automatically. You can then use it in all FHIR service API requests.

-You can get the Microsoft Entra access token by using your Entra account credentials and following the listed steps.

-1. In the Postman, select the **Authorization** tab of either a collection or a specific REST Call, select **Type** as OAuth 2.0 and under **Configure New Token** section, set these values:

-1. You're asked for User credentials for sign-in.

-1. You receive the token. Choose **Use Token.**

-To perform health check on FHIR service, enter `{{fhirurl}}/health/check` in the GET request, and then choose **Send**. You should be able to see the `Status of FHIR service - HTTP Status` code response with 200 and OverallStatus as **Healthy** in response, which means your health check is successful.

-Create a new request, change the method to **Post**, and then enter the value in the request section.

-Select **Bearer Token** as the authorization type. Enter `{{bearerToken}}` in the **Token** section. Select the **Body** tab. Select the **raw** option and **JSON** as body text format. Copy and paste the text to the body section.

-Select **Send**. You should notice a `202 Accepted` response. Select the **Headers** tab of the response and make a note of the value in the **Content-Location**. You can use the value to query the export job status.

-In this article, you'll learn how to access Azure Health Data Services with cURL.

-* If you want to run the code locally, install [PowerShell](/powershell/module/powershellget/) and [Azure Az PowerShell](/powershell/azure/install-azure-powershell).

-* Optionally, install a Bash shell, such as Git Bash, which it's included in [Git for Windows](https://gitforwindows.org/).

-> In the scenarios where the FHIR service audience parameter is not mapped to the FHIR service endpoint url. The resource parameter value should be mapped to Audience value under FHIR Service Authentication blade.

-FHIR&#174; is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

-In this article, you'll learn how to access Azure Health Data Services using [REST Client extension in Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=humao.rest-client).

-[  ](media/rest-install.png#lightbox)

-[  ](media/rest-send-request.png#lightbox)

-> Before calling the FHIR server REST API (other than getting the metadata), you must complete [application registration](../register-application.md). Make a note of your Azure **tenant ID**, **client ID**, **client secret** and the **service URL**.

-In your `test.http` file, include the following information obtained from registering your application:

-After including the information below in your `test.http` file, hit `Send Request`. You'll see an HTTP response that contains your access token.

-> In the scenarios where the FHIR service audience parameter is not mapped to the FHIR service endpoint url. The resource parameter value should be mapped to Audience value under FHIR Service Authentication blade.

-## `GET` FHIR Patient data

-You can now get a list of patients or a specific patient with the `GET` request. The line with `Authorization` is the header info for the `GET` request. You can also send `PUT` or `POST` requests to create/update FHIR resources.

-If you're unable to get the metadata, which doesn't require access token based on the HL7 specification, check that your FHIR server is running properly.

-In this article, you learned how to access Azure Health Data Services data using the using the REST Client extension in Visual Studio Code.

-FHIR&#174; is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

-In the [store profiles in the FHIR service](store-profiles-in-fhir.md) article, you walked through the basics of FHIR profiles and storing them. The FHIR service in Azure Health Data Services (hereby called the FHIR service) allows validating resources against profiles to see if the resources conform to the profiles. This article will guide you through how to use `$validate` for validating resources against profiles.

-`$validate` is an operation in Fast Healthcare Interoperability Resources (FHIR&#174;) that allows you to ensure that a FHIR resource conforms to the base resource requirements or a specified profile. This operation ensures that the data in FHIR service has the expected attributes and values. For information on validate operation, visit [HL7 FHIR Specification](https://www.hl7.org/fhir/resource-operation-validate.html).

-On the successful validation of an existing/ new resource with the validate operation, resource is not persisted into the FHIR service. Use Option 3: Validate on resource CREATE/ UPDATE using header, to persist successfully validated resource to the FHIR service.

-FHIR Service will always return an `OperationOutcome` as the validation results for $validate operation. FHIR service does two step validation, once a resource is passed into $validate endpoint - the first step is a basic validation to ensure resource can be parsed. During resource parsing, individual errors need to be fixed before proceeding further to next step. Once resource is successfully parsed, full validation is conducted as second step.

-> Any valuesets that are to be used for validation must be uploaded to the FHIR server. This includes any Valuesets which are part of the FHIR specification, as well as any ValueSets defined in Implementation Guides. Only fully expanded Valuesets which contain a full list of all codes are supported. Any ValueSet definitions which reference external sources are not supported.

-To validate an existing resource, use `$validate` in a `GET` request:

-In this example, you're validating the existing Patient resource `a6e11662-def8-4dde-9ebc-4429e68d130e` against the base Patient resource. If it's valid, you'll get an `OperationOutcome` such as the following code example:

-If the resource isn't valid, you'll get an error code and an error message with details on why the resource is invalid. An example `OperationOutcome` gets returned with error messages and could look like the following code example:

-If you'd like to specify a profile as a parameter, you can specify the canonical URL for the profile to validate against, such as the following example for the HL7 base profile for `heartrate`:

-If you'd like to validate a new resource that you're uploading to the server, you can do a `POST` request:

-This request will first validate the resource. New resource you're specifying in the request will be created after validation.

-The server will always return an `OperationOutcome` as the result.

-## Option 3: Validate on resource CREATE/UPDATE using header

-You can choose when you'd like to validate your resource, such as on resource `CREATE` or `UPDATE`. By default, the FHIR service is configured to opt out of validation on resource `Create/Update`. This capability allows to validate on `Create/Update`, using the `x-ms-profile-validation` header. Set `x-ms-profile-validation' to true for validation.

-To enable strict validation, use 'Prefer: handling' header with value strict. By setting this header, validation warning will be reported as an error.

-FHIR&#174; is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

-After Health Check removes the unhealthy instance, the feature continues to ping the instance. If the instance responds with a healthy status code, inclusively ranging from 200 to 299, Health Check returns the instance to the load balancer. However, if the instance remains unhealthy for one hour, Health Check replaces the instance with a new one. For more information, see [What App Service does with health checks](../app-service/monitor-instances-health-check.md#what-app-service-does-with-health-checks).

-2. On the **Settings** page of your Service Bus namespace, select **Encryption**.

-3. Select the **Customer-managed key encryption at rest** as shown in the following image.

- 

- ```azurecli-interactive

- az keyvault create --name contoso-SB-BYOK-keyvault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true

- ```

- ```azurecli-interactive

- az keyvault update --name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true

- ```

- ```azurecli-interactive

- az keyvault create --hsm-name contoso-SB-BYOK-keyvault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true

- ```

- ```azurecli-interactive

- az keyvault update --hsm-name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true

- ```

-4. Create keys by following these steps:

- 1. To create a new key, select **Generate/Import** from the **Keys** menu under **Settings**.

- 

- 1. Set **Options** to **Generate** and give the key a name.

- 

- 1. You can now select this key to associate with the Service Bus namespace for encrypting from the drop-down list.

- 

- > [!NOTE]

- > For redundancy, you can add up to 3 keys. In the event that one of the keys has expired, or is not accessible, the other keys will be used for encryption.

- 1. Fill in the details for the key and click **Select**. This enables the encryption of the Microsoft-managed key with your key (customer-managed key).

- For more information, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md).

-This section shows how to do the following tasks:

-1. Create a **premium** Service Bus namespace with a **managed service identity**.

-2. Create a **key vault** and grant the service identity access to the key vault.

-3. Update the Service Bus namespace with the key vault information (key/value).

-### Geo-Disaster Recovery - encryption with system-assigned identities

-### Geo-Disaster Recovery - encryption with user-assigned identities

-1. Create managed identity and assign Key Vault permissions to your managed identity.

-2. Add the identity as a user assigned identity, and enable encryption with the identity on both namespaces.

-3. Pair namespaces together

-1. Secondary namespace must already have Encryption enabled with a User-Assigned identity if it's to be paired with a primary namespace that has Encryption enabled.

-2. It isn't possible to enable Encryption on an already paired primary, even if the secondary has a User-Assigned identity associated with the namespace.