Merge pull request #291864 from kgremban/dec11-dpsfunctions

Function keys in custom allocation enrollments

Author: prmerger-automator[bot]

articles/iot-dps/concepts-custom-allocation.md

@@ -34,10 +34,30 @@ The following steps describe how custom allocation polices work:
 
 1. DPS assigns the device to the IoT hub indicated in the response, and, if an initial twin is returned, sets the initial twin for the device accordingly. If a custom payload is returned by the webhook, it's passed to the device along with the assigned IoT hub and authentication details in the [registration response](/rest/api/iot-dps/device/runtime-registration/device-registration-status-lookup) from DPS.
 
-1. The device connects to the assigned IoT hub and downloads its initial twin state. If a custom payload is returned in the registration response, the device uses it according to its own client-side logic.  
+1. The device connects to the assigned IoT hub and downloads its initial twin state. If a custom payload is 00000000000000000000000000000000000000000000000000000000returned in the registration response, the device uses it according to its own client-side logic.  
 
 The following sections provide more detail about the custom allocation request and response, custom payloads, and policy implementation. For a complete end-to-end example of a custom allocation policy, see [Use custom allocation policies](tutorial-custom-allocation-policies.md).
 
+## Manage function keys
+
+Custom allocation policies use function keys to authenticate calls to Azure Functions where the authorization level is set to `Function`. The behavior of key management differs based on whether you configure the custom allocation policy through the Azure portal or programmatically.
+
+### Function keys in the portal
+
+When you create an enrollment in the Azure portal and specify a custom allocation policy, the portal automatically handles retrieving and embedding the function key.
+
+After selecting the function for the custom allocation policy, the portal retrieves the function key. This step is not visible to users through the portal interface. Then, the function key is stored as part of the encrypted webhook URL used by DPS to call the function. The key is not displayed in the portal.
+
+You can verify that the key is embedded in the webhook URL by running a GET command to retrieve the enrollment details. In the enrollment configuration, the function key is included in the **webhookUrl** field.
+
+### Function keys with APIs
+
+When you create an enrollment programmatically using the DPS API, you need to manually provide the key during creation of the enrollment. If the key isn't provided, the Azure Functions call fails authentication.
+
+Before you create the individual or group enrollment, retrieve the function key from your function. For more information, see [Get your function access keys](../azure-functions/function-keys-how-to.md#get-your-function-access-keys). Then, include the function key in the **webhookUrl** field of the **CustomAllocationDefinition**.
+
+For more information, see [Azure Functions HTTP trigger > Access key authorization](../azure-functions/functions-bindings-http-webhook-trigger.md#api-key-authorization).
+
 ## Custom allocation policy request
 
 DPS sends a POST request to your webhook on the following endpoint: `https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}`

articles/iot-dps/tutorial-custom-allocation-policies.md

@@ -360,6 +360,9 @@ In this section, you create a new enrollment group that uses the custom allocati
 
 After saving the enrollment, reopen it and make a note of the **Primary key**. You must save the enrollment first to have the keys generated. This key is used to generate unique device keys for simulated devices in the next section.
 
+>[!TIP]
+>When you create an enrollment group in the Azure portal and select a custom allocation policy, the Azure portal automatically retrieves and embeds the function key on your behalf. If you create an enrollment programmatically, you need to provide the key as part of the creation step.
+
 ## Derive unique device keys
 
 Devices don't use the enrollment group's primary symmetric key directly. Instead, you use the primary key to derive a device key for each device. In this section, you create two unique device keys. One key is used for a simulated toaster device. The other key is used for a simulated heat pump device.