Skip to content

Commit

Permalink
Merge pull request MicrosoftDocs#67418 from wesmc7777/master
Browse files Browse the repository at this point in the history 
fixes MicrosoftDocs/azure-docs#25347
  • Loading branch information
@GitHubber17
GitHubber17 authored Feb 24, 2019
2 parents 8cf5c9f + 3e902b2 commit e67ecba
Showing 1 changed file with 86 additions and 42 deletions.
128 changes: 86 additions & 42 deletions articles/iot-dps/tutorial-group-enrollments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,21 @@ Make sure to complete the steps in the [Setup IoT Hub Device Provisioning Servic

1. Make sure `git` is installed on your machine and is added to the environment variables accessible to the command window. See [Software Freedom Conservancy's Git client tools](https://git-scm.com/download/) for the latest version of `git` tools to install, which includes the **Git Bash**, the command-line app that you can use to interact with your local Git repository.

1. Use the following [Certifcate Overview](https://github.com/Azure/azure-iot-sdk-c/blob/master/tools/CACertificates/CACertificateOverview.md) to create your test certificates.
1. Use the following [Certificate Overview](https://github.com/Azure/azure-iot-sdk-c/blob/master/tools/CACertificates/CACertificateOverview.md) to create your test certificates.

> [!NOTE]
> This step requires [OpenSSL](https://www.openssl.org/), which can either be built and installed from source or downloaded and installed from a [3rd party](https://wiki.openssl.org/index.php/Binaries) such as [this](https://sourceforge.net/projects/openssl/). If you have already created your _root_, _intermediate_ and _device_ certificates you may skip this step.
> This step requires [OpenSSL](https://www.openssl.org/), which can either be built and installed from source or downloaded and installed from a [3rd-party](https://wiki.openssl.org/index.php/Binaries) such as [this](https://sourceforge.net/projects/openssl/). If you have already created your _root_, _intermediate_ and _device_ certificates you may skip this step.
>
1. Run through the first two steps to create your _root_ and _intermediate_ certificates.

1. Log in to the Azure portal, click on the **All resources** button on the left-hand menu and open your provisioning service.
1. Sign in to the Azure portal, click on the **All resources** button on the left-hand menu and open your provisioning service.

1. On the Device Provisioning Service summary blade, select **Certificates** and click the **Add** button at the top.

1. Under the **Add Certificate**, enter the following information:
- Enter a unique certificate name.
- Select the **_RootCA.pem_** file you just created.
- Select the **_RootCA.pem_** file you created.
- Once complete, click the **Save** button.

![Add certificate](./media/tutorial-group-enrollments/add-certificate.png)
Expand All @@ -63,7 +63,7 @@ Make sure to complete the steps in the [Setup IoT Hub Device Provisioning Servic
## Create a device enrollment entry

1. Open a command prompt. Clone the GitHub repo for Java SDK code samples:

```cmd/sh
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```
Expand All @@ -72,11 +72,11 @@ Make sure to complete the steps in the [Setup IoT Hub Device Provisioning Servic
1. Add the `[Provisioning Connection String]` for your provisioning service, from the portal as following:
1. Navigate to your provisioning service in the [Azure portal](https://portal.azure.com).
1. Navigate to your provisioning service in the [Azure portal](https://portal.azure.com).
1. Open the **Shared access policies**, and select a policy that has the *EnrollmentWrite* permission.
1. Open the **Shared access policies**, and select a policy which has the *EnrollmentWrite* permission.
1. Copy the **Primary key connection string**.
1. Copy the **Primary key connection string**.
![Get the provisioning connection string from portal](./media/tutorial-group-enrollments/provisioning-string.png)
Expand All @@ -86,7 +86,9 @@ Make sure to complete the steps in the [Setup IoT Hub Device Provisioning Servic
private static final String PROVISIONING_CONNECTION_STRING = "[Provisioning Connection String]";
```
1. Open the **_RootCA.pem_** file in a text editor. Assign the value of the **Root Cert** to the parameter **PUBLIC_KEY_CERTIFICATE_STRING** as shown below:
1. Open your intermediate signing certificate file in a text editor. Update the `PUBLIC_KEY_CERTIFICATE_STRING` value with the value of your intermediate signing certificate.
If you generated your device certificates with Bash shell, *./certs/azure-iot-test-only.intermediate.cert.pem* contains the intermediate certificate key. If your certs were generated with PowerShell, *./Intermediate1.pem* will be your intermediate certificate file.
```java
private static final String PUBLIC_KEY_CERTIFICATE_STRING =
Expand All @@ -103,22 +105,22 @@ Make sure to complete the steps in the [Setup IoT Hub Device Provisioning Servic
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END CERTIFICATE-----\n";
```
1. Navigate to the IoT hub linked to your provisioning service in the [Azure portal](https://portal.azure.com). Open the **Overview** tab for the hub, and copy the **Hostname**. Assign this **Hostname** to the *IOTHUB_HOST_NAME* parameter.
```java
private static final String IOTHUB_HOST_NAME = "[Host name].azure-devices.net";
```
1. Study the sample code. It creates, updates, queries and deletes a group enrollment for X.509 devices. To verify successful enrollment in portal, temporarily comment out the following lines of code at the end of the _ServiceEnrollmentGroupSample.java_ file:
1. Study the sample code. It creates, updates, queries, and deletes a group enrollment for X.509 devices. To verify successful enrollment in portal, temporarily comment out the following lines of code at the end of the _ServiceEnrollmentGroupSample.java_ file:
```java
// ************************************** Delete info of enrollmentGroup ***************************************
System.out.println("\nDelete the enrollmentGroup...");
provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);
```
1. Save the file _ServiceEnrollmentGroupSample.java_.
1. Save the file _ServiceEnrollmentGroupSample.java_.
1. Open a command window, and navigate to the folder **_azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample_**.
Expand All @@ -139,12 +141,11 @@ Make sure to complete the steps in the [Setup IoT Hub Device Provisioning Servic
![Successful enrollment](./media/tutorial-group-enrollments/enrollment.png)
1. Navigate to your provisioning service in the Azure portal. Click **Manage enrollments**. Notice that your group of X.509 devices appears under the **Enrollment Groups** tab, with an auto-generated *GROUP NAME*.
1. Navigate to your provisioning service in the Azure portal. Click **Manage enrollments**. Notice that your group of X.509 devices appears under the **Enrollment Groups** tab, with an auto-generated *GROUP NAME*.
## Simulate the device
1. On the Device Provisioning Service summary blade, select **Overview** and note your _Id Scope_ and _Provisioning Service Global Endpoint_.
1. On the Device Provisioning Service summary blade, select **Overview** and note your _ID Scope_ and _Provisioning Service Global Endpoint_.
![Service information](./media/tutorial-group-enrollments/extract-dps-endpoints.png)
Expand All @@ -154,36 +155,79 @@ Make sure to complete the steps in the [Setup IoT Hub Device Provisioning Servic
cd azure-iot-sdk-java/provisioning/provisioning-samples/provisioning-X509-sample
```
1. Enter the enrollment group information in the following way:
1. Edit `/src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningX509Sample.java` to include your _ID Scope_ and _Provisioning Service Global Endpoint_ that you noted previously.
- Edit `/src/main/java/samples/com/microsoft/azure/sdk/iot/ProvisioningX509Sample.java` to include your _Id Scope_ and _Provisioning Service Global Endpoint_ as noted before. Open your **_{deviceName}-public.pem_** file and include this value as your _Client Cert_. Open your **_{deviceName}-all.pem_** file and copy the text from _-----BEGIN PRIVATE KEY-----_ to _-----END PRIVATE KEY-----_. Use this as your _Client Cert Private Key_.
```java
private static final String idScope = "[Your ID scope here]";
private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;
private static final int MAX_TIME_TO_WAIT_FOR_REGISTRATION = 10000; // in milli seconds
private static final String leafPublicPem = "<Your Public PEM Certificate here>";
private static final String leafPrivateKey = "<Your Private PEM Key here>";
```
```java
private static final String idScope = "[Your ID scope here]";
private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;
private static final String leafPublicPem = "<Your Public PEM Certificate here>";
private static final String leafPrivateKey = "<Your Private PEM Key here>";
```
1. Update the `leafPublicPem` and `leafPrivateKey` variables with your public and private device certificates.
- Use the following format for including your certificate and key:
```java
private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END CERTIFICATE-----\n";
private static final String leafPrivateKey = "-----BEGIN PRIVATE KEY-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXX\n" +
"-----END PRIVATE KEY-----\n";
```
If you generated your device certificates with PowerShell, the files mydevice* contain the public key, private key, and PFX for the device.
If you generated your device certificates with Bash shell, ./certs/new-device.cert.pem contains the public key. The device's private key will be in the ./private/new-device.key.pem file.
Open your public key file and update the `leafPublicPem` variable with that value. Copy the text from _-----BEGIN PRIVATE KEY-----_ to _-----END PRIVATE KEY-----_.
```java
private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END CERTIFICATE-----\n";
```
Open your private key file and update the `leafPrivatePem` variable with that value. Copy the text from _-----BEGIN RSA PRIVATE KEY-----_ to _-----END RSA PRIVATE KEY-----_.
```java
private static final String leafPrivateKey = "-----BEGIN RSA PRIVATE KEY-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END RSA PRIVATE KEY-----\n";
```
1. Add a new variable just below `leafPrivateKey` for your intermediate certificate. Name this new variable `intermediateKey`. Give it the value of your intermediate signing certificate.
If you generated your device certificates with Bash shell, *./certs/azure-iot-test-only.intermediate.cert.pem* contains the intermediate certificate key. If your certs were generated with PowerShell, *./Intermediate1.pem* will be your intermediate certificate file.
```java
private static final String intermediateKey = "-----BEGIN CERTIFICATE-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END CERTIFICATE-----\n";
```
1. In the `main` function, add the `intermediateKey` to the `signerCertificates` collection before the initialization of `securityProviderX509`.
```java
public static void main(String[] args) throws Exception
{
...
try
{
ProvisioningStatus provisioningStatus = new ProvisioningStatus();
// Add intermediate certificate as part of the certificate key chain.
signerCertificates.add(intermediateKey);
SecurityProvider securityProviderX509 = new SecurityProviderX509Cert(leafPublicPem, leafPrivateKey, signerCertificates);
```
1. Build the sample. Navigate to the target folder and execute the created jar file.
1. Save your changes and build the sample. Navigate to the target folder and execute the created jar file.
```cmd/sh
mvn clean install
Expand Down

0 comments on commit e67ecba

Please sign in to comment.