Skip to content

Commit d2e68f3

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #241468 from gourdsay/main
key vault and credentials
2 parents d9bcc61 + ad0528c commit d2e68f3

17 files changed

+440
-32
lines changed

‎articles/data-manager-for-agri/concepts-byol-and-credentials.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Storing your license keys in Azure Data Manager for Agriculture
3+
description: Provides information on using third party keys
4+
author: gourdsay
5+
ms.author: angour
6+
ms.service: data-manager-for-agri
7+
ms.topic: conceptual
8+
ms.date: 06/23/2023
9+
ms.custom: template-concept
10+
---
11+
12+
# Store and use your license keys.
13+
14+
Azure Data Manager for Agriculture supports a range of data ingress connectors to centralize your fragmented accounts. These connections require the customer to populate their credentials in a Bring Your Own License (BYOL) model, so that the data manager may retrieve data on behalf of the customer.
15+
16+
17+
> [!NOTE]
18+
> Microsoft Azure Data Manager for Agriculture is currently in preview. For legal terms that apply to features that are in beta, in preview, or otherwise not yet released into general availability, see the [**Supplemental Terms of Use for Microsoft Azure Previews**](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
19+
> Microsoft Azure Data Manager for Agriculture requires registration and is available to only approved customers and partners during the preview period. To request access to Microsoft Data Manager for Agriculture during the preview period, use this [**form**](https://aka.ms/agridatamanager).
20+
21+
## Prerequisites
22+
23+
To access Azure Key Vault, you need an Azure subscription. If you don't already have a subscription, create a [free account](https://azure.microsoft.com/free/) before you begin.
24+
25+
26+
## Overview
27+
28+
In BYOL model, you're responsible for providing your own licenses for satellite imagery and weather connector. In the vault reference model, you store your credentials as secret in a customer managed Azure Key Vault. The URI of the secret must be shared and read permissions granted to Azure Data Manager for Agriculture so that the APIs can work seamlessly. This process is a one-time setup for each connector. Our Data Manager then refers to and reads the secret from the customers’ key vault as part of the API call with no exposure of the secret.
29+
30+
Flow diagram showing creation and sharing of credentials.
31+
:::image type="content" source="./media/concepts-byol-and-credentials/vault-usage-flow.png" alt-text="Screenshot showing credential sharing flow.":::
32+
33+
The steps to use Azure Key Vault in Data Manager for Agriculture are as follows:
34+
35+
## Step 1: Create Key Vault
36+
Customers can create a key vault or use an existing key vault to share license credentials for satellite (Sentinel Hub) and weather (IBM Weather). Customer [creates Azure Key Vault](/azure/key-vault/general/quick-create-portal) or reuses existing an existing key vault. The following properties are recommended:
37+
38+
:::image type="content" source="./media/concepts-byol-and-credentials/create-key-vault.png" alt-text="Screenshot showing key vault properties.":::
39+
40+
Data Manager for Agriculture is a Microsoft trusted service and supports private network key vaults in addition to publicly available key vaults. If you put your key vault behind a VNET, then you need to select the `“Allow trusted Microsoft services to bypass this firewall."`
41+
42+
:::image type="content" source="./media/concepts-byol-and-credentials/enable-access-to-keys.png" alt-text="Screenshot showing key vault access.":::
43+
44+
## Step 2: Store secret in Azure Key Vault
45+
For sharing your satellite or weather service credentials, store client secrets in a key vault, for example `ClientSecret` for `SatelliteSentinelHub` and `APIKey` for `WeatherIBM`. Customers are in control of secret name and rotation.
46+
47+
Refer to [this guidance](/azure/key-vault/secrets/quick-create-portal#add-a-secret-to-key-vault) to store and retrieve your secret from the vault.
48+
49+
:::image type="content" source="./media/concepts-byol-and-credentials/store-your-credential-keys.png" alt-text="Screenshot showing storage of key values.":::
50+
51+
## Step 3: Enable system identity
52+
As a customer you have to enable system identity for your Data Manager for Agriculture instance. There are two options:
53+
54+
1. Via UI
55+
56+
:::image type="content" source="./media/concepts-byol-and-credentials/enable-system-via-ui.png" alt-text="Screenshot showing usage of UI to enable key.":::
57+
58+
2. Via Azure Resource Manager client
59+
60+
```cmd
61+
armclient patch /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AgFoodPlatform/farmBeats/{ADMA_instance_name}?api-version=2023-04-01-preview "{identity: { type: 'systemAssigned' }}
62+
```
63+
64+
## Step 4: Access policy
65+
Add an access policy in key vault for your Data Manager for Agriculture instance.
66+
67+
1. Go to access policies tab in the created key vault.
68+
69+
:::image type="content" source="./media/concepts-byol-and-credentials/select-access-policies.png" alt-text="Screenshot showing selection of access policy.":::
70+
71+
2. Choose Secret GET and LIST permissions.
72+
73+
:::image type="content" source="./media/concepts-byol-and-credentials/select-permissions.png" alt-text="Screenshot showing selection of permissions.":::
74+
75+
3. Select the next tab, and then select Data Manager for Agriculture instance name and then select the review + create tab to create the access policy.
76+
77+
:::image type="content" source="./media/concepts-byol-and-credentials/access-policy-creation.png" alt-text="Screenshot showing selection create and review tab.":::
78+
79+
## Step 5: Invoke control plane API call
80+
Use the [API call](/rest/api/data-manager-for-agri/controlplane-version2021-09-01-preview/farm-beats-models/create-or-update?tabs=HTTP) to specify credentials. Key vault URI/ key name/ key version can be found after creating secret as shown in the following figure.
81+
82+
:::image type="content" source="./media/concepts-byol-and-credentials/details-key-vault.png" alt-text="Screenshot showing where key name and key version is available.":::
83+
84+
Flow showing how Azure Data Manager for Agriculture accesses secret.
85+
:::image type="content" source="./media/concepts-byol-and-credentials/key-access-flow.png" alt-text="Screenshot showing how the data manager accesses credentials.":::
86+
87+
If you disable and then re-enable system identity, then you have to delete the access policy in key vault and add it again.
88+
89+
## Conclusion
90+
You can use your license keys safely by storing your secrets in the Azure Key Vault, enabling system identity and providing read access to our Data Manager. ISV solutions available with our Data Manager also use these credentials.
91+
92+
You can use our data plane APIs and reference license keys in your key vault. You can also choose to override default license credentials dynamically in our data plane API calls. Our Data Manager does basic validations including checking if it can access the secret specified in credentials object or not.
93+
94+
## Next steps
95+
96+
* Test our APIs [here](/rest/api/data-manager-for-agri).

‎articles/data-manager-for-agri/concepts-ingest-sensor-data.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ author: gourdsay
55
ms.author: angour
66
ms.service: data-manager-for-agri
77
ms.topic: conceptual
8-
ms.date: 02/14/2023
8+
ms.date: 06/19/2023
99
ms.custom: template-concept
1010
---
1111

@@ -44,6 +44,8 @@ The following diagram depicts the topology of a sensor in Azure Data Manager for
4444

4545
## Next steps
4646

47-
How to [get started as a customer](./how-to-set-up-sensors-customer.md) to consume sensor data from the supported sensor partners.
47+
How to [get started when you push and consume sensor data](./how-to-set-up-sensor-as-customer-and-partner.md).
48+
49+
How to [get started as a customer](./how-to-set-up-sensors-customer.md) to consume sensor data from a supported sensor partner like Davis Instruments.
4850

4951
How to [get started as a sensor partner](./how-to-set-up-sensors-partner.md) to push sensor data into Data Manager for Agriculture Service.

‎articles/data-manager-for-agri/how-to-set-up-sensor-as-customer-and-partner.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
title: Push and consume sensor data in Data Manager for Agriculture
3+
description: Learn how to push sensor data as a provider and egress it as a customer
4+
author: lbethapudi
5+
ms.author: lbethapudi
6+
ms.service: data-manager-for-agri
7+
ms.topic: how-to
8+
ms.date: 06/19/2023
9+
ms.custom: template-how-to
10+
---
11+
# Sensor Integration as both partner and customer in Azure Data Manager for Agriculture
12+
13+
Follow the below steps to register as a sensor partner so that you can start pushing your data into your Data Manager for Agriculture instance.
14+
15+
## Step 1: Enable sensor integration
16+
17+
1. Sensor integration should be enabled before it can be initiated. This step provisions required internal Azure resources for sensor integration for Data Manager for Agriculture instance. This can be done by running following <a href="https://github.com/projectkudu/ARMClient" target=" blank">armclient</a> command.
18+
19+
```armclient
20+
armclient patch /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<datamanager-instance-name>?api-version=2023-04-01-preview "{properties:{sensorIntegration:{enabled:'true'}}}"
21+
```
22+
23+
Sample output:
24+
25+
```json
26+
{
27+
"id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<datamanager-instance-name>",
28+
"type": "Microsoft.AgFoodPlatform/farmBeats",
29+
"sku": {
30+
"name": "A0"
31+
},
32+
"systemData": {
33+
"createdBy": "<customer-id>",
34+
"createdByType": "User",
35+
"createdAt": "2022-03-11T03:36:32Z",
36+
"lastModifiedBy": "<customer-id>",
37+
"lastModifiedByType": "User",
38+
"lastModifiedAt": "2022-03-11T03:40:06Z"
39+
},
40+
"properties": {
41+
"instanceUri": "https://<datamanager-instance-name>.farmbeats.azure.net/",
42+
"provisioningState": "Succeeded",
43+
"sensorIntegration": {
44+
"enabled": "True",
45+
"provisioningState": "**Creating**"
46+
},
47+
"publicNetworkAccess": "Enabled"
48+
},
49+
"location": "eastus",
50+
"name": "myfarmbeats"
51+
}
52+
```
53+
54+
2. The above job might take a few minutes to complete. To know the status of job, the following armclient command should be run:
55+
56+
```armclient
57+
armclient get /subscriptions/<subscription-id>/resourceGroups/<resource-group-name> /providers/Microsoft.AgFoodPlatform/farmBeats/<datamanager-instance-name>?api-version=2023-04-01-preview
58+
```
59+
60+
3. To verify whether it's completed, look at the highlighted attribute. It should be updated as “Succeeded” from “Creating” in the earlier step. The attribute that indicates that the sensor integration is enabled is indicated by **provisioningState inside the sensorIntegration object**.
61+
62+
Sample output:
63+
```json
64+
{
65+
"id": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.AgFoodPlatform/farmBeats/<datamanager-instance-name>",
66+
"type": "Microsoft.AgFoodPlatform/farmBeats",
67+
"sku": {
68+
"name": "A0"
69+
},
70+
"systemData": {
71+
"createdBy": "<customer-id>",
72+
"createdByType": "User",
73+
"createdAt": "2022-03-11T03:36:32Z",
74+
"lastModifiedBy": "<customer-id>",
75+
"lastModifiedByType": "User",
76+
"lastModifiedAt": "2022-03-11T03:40:06Z"
77+
},
78+
"properties": {
79+
"instanceUri": "https://<customer-host-name>.farmbeats.azure.net/",
80+
"provisioningState": "Succeeded",
81+
"sensorIntegration": {
82+
"enabled": "True",
83+
"provisioningState": "**Succeeded**"
84+
},
85+
"publicNetworkAccess": "Enabled"
86+
},
87+
"tags": {
88+
"usage": "<sensor-partner-id>"
89+
},
90+
"location": "eastus",
91+
"name": "<customer-id>"
92+
}
93+
```
94+
Once the provisioning status for sensor integration is completed, sensor integration objects can be created.
95+
96+
## Step 2: Create sensor partner integration
97+
Create sensor partner integration step should be executed to connect customer with provider.
98+
The integrationId is later used in sensor creation.
99+
100+
API documentation: [Sensor Partner Integrations - Create Or Update](/rest/api/data-manager-for-agri/dataplane-version2022-11-01-preview/sensor-partner-integrations/create-or-update)
101+
102+
## Step 3: Create sensor data model
103+
Use sensor data model to define the model of telemetry being sent. All the telemetry sent by the sensor is validated as per this data model.
104+
105+
API documentation: [Sensor Data Models - Create Or Update](/rest/api/data-manager-for-agri/dataplane-version2022-11-01-preview/sensor-data-models/create-or-update)
106+
107+
Sample telemetry
108+
```json
109+
{
110+
"pressure": 30.45,
111+
"temperature": 28,
112+
"name": "sensor-1"
113+
}
114+
```
115+
116+
Corresponding sensor data model
117+
```json
118+
{
119+
"type": "Sensor",
120+
"manufacturer": "Some sensor manufacturer",
121+
"productCode": "soil m",
122+
"measures": {
123+
"pressure": {
124+
"description": "measures soil moisture",
125+
"dataType": "Double",
126+
"type": "sm",
127+
"unit": "Bar",
128+
"properties": {
129+
"abc": "def",
130+
"elevation": 5
131+
}
132+
},
133+
"temperature": {
134+
"description": "measures soil temperature",
135+
"dataType": "Long",
136+
"type": "sm",
137+
"unit": "Celsius",
138+
"properties": {
139+
"abc": "def",
140+
"elevation": 5
141+
}
142+
},
143+
"name": {
144+
"description": "Sensor name",
145+
"dataType": "String",
146+
"type": "sm",
147+
"unit": "none",
148+
"properties": {
149+
"abc": "def",
150+
"elevation": 5
151+
}
152+
}
153+
},
154+
"sensorPartnerId": "sensor-partner-1",
155+
"id": "sdm124",
156+
"status": "new",
157+
"createdDateTime": "2022-01-24T06:12:15Z",
158+
"modifiedDateTime": "2022-01-24T06:12:15Z",
159+
"eTag": "040158a0-0000-0700-0000-61ee433f0000",
160+
"name": "my sdm for soil moisture",
161+
"description": "description goes here",
162+
"properties": {
163+
"key1": "value1",
164+
"key2": 123.45
165+
}
166+
}
167+
```
168+
169+
## Step 4: Create sensor
170+
Create sensor using the corresponding integration ID and sensor data model ID. DeviceId and HardwareId are optional parameters, if needed, you can use the [Devices - Create Or Update](/rest/api/data-manager-for-agri/dataplane-version2022-11-01-preview/devices/create-or-update?tabs=HTTP) to create the device.
171+
172+
API documentation: [Sensors - Create Or Update](/rest/api/data-manager-for-agri/dataplane-version2022-11-01-preview/sensors/create-or-update?tabs=HTTP)
173+
174+
## Step 5: Get IoTHub connection string
175+
Get IoTHub connection string to push sensor telemetry to the platform for the Sensor created.
176+
177+
API Documentation: [Sensors - Get Connection String](/rest/api/data-manager-for-agri/dataplane-version2022-11-01-preview/sensors/get-connection-string?tabs=HTTP)
178+
179+
## Step 6: Push data using IoT Hub
180+
Use [IoT Hub Device SDKs](/azure/iot-hub/iot-hub-devguide-sdks#azure-iot-hub-device-sdks) to push the telemetry using the connection string.
181+
182+
For all sensor telemetry events, "timestamp" is a mandatory property and has to be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
183+
184+
You're now all set to start pushing sensor data for all sensors using the respective connection string provided for each sensor. However, sensor data should be sent in a JSON format as defined by Data Manager for Agriculture. Refer to the telemetry schema that follows:
185+
186+
```json
187+
{
188+
"timestamp": "2022-02-11T03:15:00Z",
189+
"bar": 30.181,
190+
"bar_absolute": 29.748,
191+
"bar_trend": 0,
192+
"et_day": 0.081,
193+
"humidity": 55,
194+
"rain_15_min": 0,
195+
"rain_60_min": 0,
196+
"rain_24_hr": 0,
197+
"rain_day": 0,
198+
"rain_rate": 0,
199+
"rain_storm": 0,
200+
"solar_rad": 0,
201+
"temp_out": 58.8,
202+
"uv_index": 0,
203+
"wind_dir": 131,
204+
"wind_dir_of_gust_10_min": 134,
205+
"wind_gust_10_min": 0,
206+
"wind_speed": 0,
207+
"wind_speed_2_min": 0,
208+
"wind_speed_10_min": 0
209+
}
210+
```
211+
212+
## Next steps
213+
214+
* Test our APIs [here](/rest/api/data-manager-for-agri).

‎articles/data-manager-for-agri/how-to-set-up-sensors-customer.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ author: gourdsay
55
ms.author: angour
66
ms.service: data-manager-for-agri
77
ms.topic: how-to
8-
ms.date: 02/14/2023
8+
ms.date: 06/19/2023
99
ms.custom: template-how-to
1010
---
1111

@@ -15,7 +15,7 @@ Follow the steps to integrate with a sensor partner to enable the partner to sta
1515

1616
## Step 1: Identify the sensor partner app and provide consent
1717

18-
Each sensor partner has their own multi-tenant Azure Active Directory app created and published on the Data Manager for Agriculture platform. The sensor partner supported by default on the platform is Davis Instruments(sensorPartnerId: `DavisInstruments`). However, you're free to add your own sensors by being a sensor partner yourself. Follow [these steps](./how-to-set-up-sensors-partner.md) to sign up being a sensor partner on the platform.
18+
Each sensor partner has their own multi-tenant Azure Active Directory app created and published on the Data Manager for Agriculture platform. The sensor partner supported by default on the platform is Davis Instruments (sensorPartnerId: `DavisInstruments`).
1919

2020
To start using the on-boarded sensor partners, you need to give consent to the sensor partner so that they start showing up in `App Registrations`. The steps for you to follow:
2121

0 commit comments

Comments
 (0)