Skip to content

Commit af0b4a6

Browse files
19BMG0019BMG00
authored
Merge pull request #210479 from v-krishnag/enroll
add enrollment api
2 parents 6e68909 + 807bc32 commit af0b4a6

File tree

1 file changed

+392
-0
lines changed

1 file changed

+392
-0
lines changed

‎articles/iot-central/core/howto-manage-devices-with-rest-api.md

Lines changed: 392 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -547,6 +547,398 @@ The response to this request looks like the following example:
547547
}
548548
```
549549

550+
## Enrollment groups
551+
552+
Enrollment groups are used to manage the device authentication options in your IoT Central application. To learn more, see [Device authentication concepts in IoT Central](concepts-device-authentication.md).
553+
554+
To learn how to create and manage enrollment groups in the UI, see [How to connect devices with X.509 certificates to IoT Central Application](how-to-connect-devices-x509.md).
555+
556+
## Create an enrollment group
557+
558+
### [X509](#tab/X509)
559+
560+
When you create an enrollment group for devices that use X.509 certificates, you first need to upload the root or intermediate certificate to your IoT Central application.
561+
562+
### Generate root and device certificates
563+
564+
In this section, you generate the X.509 certificates you need to connect a device to IoT Central.
565+
566+
> [!WARNING]
567+
> This way of generating X.509 certs is for testing only. For a production environment you should use your official, secure mechanism for certificate generation.
568+
569+
1. Navigate to the certificate generator script in the Microsoft Azure IoT SDK for Node.js you downloaded. Install the required packages:
570+
571+
```cmd/sh
572+
cd azure-iot-sdk-node/provisioning/tools
573+
npm install
574+
```
575+
576+
1. Create a root certificate and then derive a device certificate by running the script:
577+
578+
```cmd/sh
579+
node create_test_cert.js root mytestrootcert
580+
node create_test_cert.js device sample-device-01 mytestrootcert
581+
```
582+
583+
> [!TIP]
584+
> A device ID can contain letters, numbers, and the `-` character.
585+
586+
These commands produce the following root and the device certificate
587+
588+
| filename | contents |
589+
| -------- | -------- |
590+
| mytestrootcert_cert.pem | The public portion of the root X.509 certificate |
591+
| mytestrootcert_key.pem | The private key for the root X.509 certificate |
592+
| mytestrootcert_fullchain.pem | The entire keychain for the root X.509 certificate. |
593+
| mytestrootcert.pfx | The PFX file for the root X.509 certificate. |
594+
| sampleDevice01_cert.pem | The public portion of the device X.509 certificate |
595+
| sampleDevice01_key.pem | The private key for the device X.509 certificate |
596+
| sampleDevice01_fullchain.pem | The entire keychain for the device X.509 certificate. |
597+
| sampleDevice01.pfx | The PFX file for the device X.509 certificate. |
598+
599+
Make a note of the location of these files. You need it later.
600+
601+
### Generate the base-64 encoded version of the root certificate
602+
603+
In the folder on your local machine that contains the certificates you generated, create a file called convert.js and add the following JavaScript content:
604+
605+
```javascript
606+
const fs = require('fs')
607+
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
608+
console.log(fileContents);
609+
```
610+
611+
Run the following command to generate a base-64 encode version of the certificate:
612+
613+
```cmd/sh
614+
node convert.js mytestrootcert_cert.pem
615+
```
616+
617+
Make a note of the base-64 encoded version of the certificate. You need it later.
618+
619+
### Add an X.509 enrollment group
620+
621+
Use the following request to create a new enrollment group with `myx509eg` as the ID:
622+
623+
```http
624+
PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31
625+
```
626+
627+
The following example shows a request body that adds a new X.509 enrollment group:
628+
629+
```json
630+
{
631+
"displayName": "My group",
632+
"enabled": true,
633+
"type": "iot",
634+
"attestation": {
635+
"type": "x509"
636+
}
637+
}
638+
639+
```
640+
641+
The request body has some required fields:
642+
643+
* `@displayName`: Display name of the enrollment group.
644+
* `@enabled`: Whether the devices using the group are allowed to connect to IoT Central.
645+
* `@type`: Type of devices that connect through the group, either `iot` or `iotEdge`.
646+
* `attestation`: The attestation mechanism for the enrollment group, either `symmetricKey` or `x509`.
647+
648+
The response to this request looks like the following example:
649+
650+
```json
651+
{
652+
"id": "myEnrollmentGroupId",
653+
"displayName": "My group",
654+
"enabled": true,
655+
"type": "iot",
656+
"attestation": {
657+
"type": "x509",
658+
"x509": {
659+
"signingCertificates": {}
660+
}
661+
},
662+
"etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
663+
}
664+
```
665+
666+
### Add an X.509 certificate to an enrollment group
667+
668+
Use the following request to set the primary X.509 certificate of the myx509eg enrollment group:
669+
670+
```http
671+
PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31
672+
```
673+
674+
entry - Entry of certificate, either `primary` or `secondary`
675+
676+
Use this request to add either a primary or secondary X.509 certificate to the enrollment group.
677+
678+
The following example shows a request body that adds an X.509 certificate to an enrollment group:
679+
680+
```json
681+
{
682+
"verified": false,
683+
"certificate": "<base64-certificate>"
684+
}
685+
```
686+
687+
* certificate - The base-64 version of the certificate you made a note of previously.
688+
* verified - `true` if you attest that the certificate is valid, `false` if you need to prove the validity of the certificate.
689+
690+
The response to this request looks like the following example:
691+
692+
```json
693+
{
694+
"verified": false,
695+
"info": {
696+
"sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
697+
},
698+
"etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
699+
}
700+
```
701+
702+
### Generate verification code for an X.509 certificate
703+
704+
Use the following request to generate a verification code for the primary or secondary X.509 certificate of an enrollment group.
705+
706+
If you set `verified` to `false` in the previous request, use the following request to generate a verification code for the primary X.509 certificate in the `myx509eg` enrollment group:
707+
708+
```http
709+
POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31
710+
```
711+
712+
The response to this request looks like the following example:
713+
714+
```json
715+
{
716+
"verificationCode": "<certificate-verification-code>"
717+
}
718+
```
719+
720+
Make a note of the verification code, you need it in the next step.
721+
722+
### Generate the verification certificate
723+
724+
Use the following command to generate a verification certificate from the verification code in the previous step:
725+
726+
```cmd/sh
727+
node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce {verification-code}
728+
```
729+
730+
Run the following command to generate a base-64 encoded version of the certificate:
731+
732+
```cmd/sh
733+
node convert.js verification_cert.pem
734+
```
735+
736+
Make a note of the base-64 encoded version of the certificate. You need it later.
737+
738+
### Verify X.509 certificate of an enrollment group
739+
740+
Use the following request to verify the primary X.509 certificate of the `myx509eg` enrollment group by providing the certificate with the signed verification code:
741+
742+
```http
743+
POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31
744+
```
745+
746+
The following example shows a request body that verifies an X.509 certificate:
747+
748+
```json
749+
{
750+
"certificate": "base64-verification-certificate"
751+
}
752+
```
753+
754+
### Get X.509 certificate of an enrollment group
755+
756+
Use the following request to retrieve details of X.509 certificate of an enrollment group from your application:
757+
758+
```http
759+
GET https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31
760+
```
761+
762+
The response to this request looks like the following example:
763+
764+
```json
765+
{
766+
"verified": true,
767+
"info": {
768+
"sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
769+
},
770+
"etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
771+
}
772+
```
773+
774+
### Delete an X.509 certificate from an enrollment group
775+
776+
Use the following request to delete the primary X.509 certificate from an enrollment group with ID `myx509eg`:
777+
778+
```http
779+
DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31
780+
```
781+
782+
### [Symmetric key](#tab/symmetric-key)
783+
784+
### Add a symmetric key enrollment group
785+
786+
Use the following request to create a new enrollment group with `mysymmetric` as the ID:
787+
788+
```http
789+
PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/mysymmetric?api-version=2022-07-31
790+
```
791+
792+
The following example shows a request body that adds a new enrollment group:
793+
794+
```json
795+
{
796+
"displayName": "My group",
797+
"enabled": true,
798+
"type": "iot",
799+
"attestation": {
800+
"type": "symmetricKey"
801+
}
802+
}
803+
```
804+
805+
The response to this request looks like the following example:
806+
807+
```json
808+
{
809+
"id": "mysymmetric",
810+
"displayName": "My group",
811+
"enabled": true,
812+
"type": "iot",
813+
"attestation": {
814+
"type": "symmetricKey",
815+
"symmetricKey": {
816+
"primaryKey": "<primary-symmetric-key>",
817+
"secondaryKey": "<secondary-symmetric-key>"
818+
}
819+
},
820+
"etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
821+
}
822+
```
823+
824+
IoT Central generates the primary and secondary symmetric keys when you make this API call.
825+
826+
---
827+
828+
### Get an enrollment group
829+
830+
Use the following request to retrieve details of an enrollment group with `mysymmetric` as the ID:
831+
832+
```http
833+
GET https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/mysymmetric?api-version=2022-07-31
834+
```
835+
836+
The response to this request looks like the following example:
837+
838+
```json
839+
{
840+
"id": "mysymmetric",
841+
"displayName": "My group",
842+
"enabled": true,
843+
"type": "iot",
844+
"attestation": {
845+
"type": "symmetricKey",
846+
"symmetricKey": {
847+
"primaryKey": "<primary-symmetric-key>",
848+
"secondaryKey": "<secondary-symmetric-key>"
849+
}
850+
},
851+
"etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
852+
}
853+
```
854+
855+
### Update an enrollment group
856+
857+
Use the following request to update an enrollment group.
858+
859+
```http
860+
PATCH https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31
861+
```
862+
863+
The following example shows a request body that updates the display name of a enrollment group:
864+
865+
```json
866+
{
867+
"displayName": "My new group name",
868+
}
869+
```
870+
871+
The response to this request looks like the following example:
872+
873+
```json
874+
{
875+
"id": "myEnrollmentGroupId",
876+
"displayName": "My new group name",
877+
"enabled": true,
878+
"type": "iot",
879+
"attestation": {
880+
"type": "symmetricKey",
881+
"symmetricKey": {
882+
"primaryKey": "<primary-symmetric-key>",
883+
"secondaryKey": "<secondary-symmetric-key>"
884+
}
885+
},
886+
"etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
887+
}
888+
```
889+
890+
### Delete an enrollment group
891+
892+
Use the following request to delete an enrollment group with ID `myx509eg`:
893+
894+
```http
895+
DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31
896+
```
897+
898+
### List enrollment groups
899+
900+
Use the following request to retrieve a list of enrollment groups from your application:
901+
902+
```http
903+
GET https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups?api-version=2022-07-31
904+
```
905+
906+
The response to this request looks like the following example:
907+
908+
```json
909+
{
910+
"value": [
911+
{
912+
"id": "myEnrollmentGroupId",
913+
"displayName": "My group",
914+
"enabled": true,
915+
"type": "iot",
916+
"attestation": {
917+
"type": "symmetricKey",
918+
"symmetricKey": {
919+
"primaryKey": "primaryKey",
920+
"secondaryKey": "secondarykey"
921+
}
922+
},
923+
"etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
924+
},
925+
{
926+
"id": "enrollmentGroupId2",
927+
"displayName": "My group",
928+
"enabled": true,
929+
"type": "iot",
930+
"attestation": {
931+
"type": "x509",
932+
"x509": {
933+
"signingCertificates": {}
934+
}
935+
},
936+
"etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
937+
}
938+
]
939+
}
940+
```
941+
550942
## Next steps
551943

552944
Now that you've learned how to manage devices with the REST API, a suggested next step is to [How to control devices with rest api.](howto-control-devices-with-rest-api.md)

0 commit comments

Comments
 (0)