From c991c1450d3571788965e46adec026f0e2ab549f Mon Sep 17 00:00:00 2001 From: Kai Hudalla Date: Thu, 25 Jun 2020 14:52:00 +0200 Subject: [PATCH] [#1367] Add examples for registry management endpoints Added example request/response body content for the management endpoint URI paths. Also replaced the examples in the file based registry user guide with a reference to the Registry Management API in order to reduce redundancy. Signed-off-by: Kai Hudalla --- .../file-based-device-registry-config.md | 2 +- .../mongodb-device-registry-config.md | 2 +- .../api/management/device-registry-v1.yaml | 253 ++++++++-- .../user-guide/file-based-device-registry.md | 443 +----------------- .../mongodb-based-device-registry.md | 10 +- 5 files changed, 228 insertions(+), 482 deletions(-) diff --git a/site/documentation/content/admin-guide/file-based-device-registry-config.md b/site/documentation/content/admin-guide/file-based-device-registry-config.md index d3aa371302..fb511d9ac3 100644 --- a/site/documentation/content/admin-guide/file-based-device-registry-config.md +++ b/site/documentation/content/admin-guide/file-based-device-registry-config.md @@ -1,6 +1,6 @@ +++ title = "File Based Device Registry Configuration" -weight = 315 +weight = 316 +++ The File based Device Registry component provides an exemplary implementation of Eclipse Hono™'s [Device Registration]({{< relref "/api/device-registration" >}}), [Credentials]({{< relref "/api/credentials" >}}), [Tenant]({{< relref "/api/tenant" >}}) and [Device Connection]({{< relref "/api/device-connection" >}}) APIs. diff --git a/site/documentation/content/admin-guide/mongodb-device-registry-config.md b/site/documentation/content/admin-guide/mongodb-device-registry-config.md index df09f89287..1da94dd5a1 100644 --- a/site/documentation/content/admin-guide/mongodb-device-registry-config.md +++ b/site/documentation/content/admin-guide/mongodb-device-registry-config.md @@ -1,6 +1,6 @@ +++ title = "MongoDB Based Device Registry Configuration" -weight = 316 +weight = 315 +++ The MongoDB based Device Registry component provides an implementation of Eclipse Hono™'s [Device Registration]({{< relref "/api/device-registration" >}}), diff --git a/site/documentation/content/api/management/device-registry-v1.yaml b/site/documentation/content/api/management/device-registry-v1.yaml index 840256e22f..214082e4a7 100644 --- a/site/documentation/content/api/management/device-registry-v1.yaml +++ b/site/documentation/content/api/management/device-registry-v1.yaml @@ -78,14 +78,22 @@ paths: post: tags: - tenants - summary: Create new tenant with auto-generated ID + summary: Create a new tenant with an auto-generated ID + description: | + Clients use this operation to register a new tenant with an identifier that + is generated by the registry. operationId: createTenant requestBody: - description: New tenant information + description: The configuration properties to register for the tenant. content: application/json: schema: $ref: '#/components/schemas/Tenant' + examples: + default: + $ref: '#/components/examples/TenantAllAdaptersExample' + mqtt-only: + $ref: '#/components/examples/TenantMqttAdapterOnlyExample' required: false responses: 201: @@ -116,14 +124,21 @@ paths: post: tags: - tenants - summary: Create new tenant + summary: Create a new tenant with a given ID + description: | + Clients use this operation to register a new tenant with a given identifier. operationId: createTenantWithId requestBody: - description: New tenant registration + description: The configuration properties to register for the tenant. content: application/json: schema: $ref: '#/components/schemas/Tenant' + examples: + default: + $ref: '#/components/examples/TenantAllAdaptersExample' + mqtt-only: + $ref: '#/components/examples/TenantMqttAdapterOnlyExample' required: false responses: 201: @@ -136,7 +151,7 @@ paths: $ref: '#/components/responses/NotAllowed' 409: description: | - Indicates that tenant with the given identifier already exists or that an existing tenant uses + Indicates that a tenant with the given identifier already exists or that an existing tenant uses a certificate authority with the same Subject DN. If the client has no read access to the conflicting tenant then `403` should be returned instead. content: @@ -150,6 +165,8 @@ paths: tags: - tenants summary: Get tenant information + description: | + Clients use this operation to retrieve the configuration properties of an existing tenant. operationId: getTenant responses: 200: @@ -158,6 +175,27 @@ paths: application/json: schema: $ref: '#/components/schemas/Tenant' + examples: + mqtt-only: + summary: Constrained tenant + description: | + The body contains the configuration properties of a tenant for which + some resource limits have been defined. + value: | + { + "enabled": true, + "resource-limits": { + "max-connections": 1000, + "max-ttl": 3600, + "data-volume": { + "effective-since": "2019-12-01T00:00:00Z", + "max-bytes": 10000000, + "period": { + "mode": "monthly" + } + } + } + } headers: ETag: description: Version of the resource @@ -174,15 +212,32 @@ paths: tags: - tenants summary: Update tenant information + description: | + Clients use this operation to replace an existing tenant's registration information + with the information contained in the request body. operationId: updateTenant parameters: - $ref: '#/components/parameters/resourceVersion' requestBody: - description: Tenant information + description: The configuration properties to replace the tenant's existing configuration with. content: application/json: schema: $ref: '#/components/schemas/Tenant' + examples: + disable-tenant: + summary: Disable a tenant + description: | + Disabling a tenant effectively prevents any devices of that tenant + to connect to any of the protocol adapters. Devices that are + already connected to an adapter can no longer upload any data + nor receive any commands. Note that the example payload does + not contain any other properties than *enabled* which means + that all other configuration will be removed. + value: | + { + "enabled": false + } required: true responses: 204: @@ -213,6 +268,10 @@ paths: tags: - tenants summary: Delete tenant + description: | + Clients use this operation to remove an existing tenant from the registry. + Registry implementations may optionally perform a *cascading* delete of all + the tenant's devices and credentials as well. operationId: deleteTenant parameters: - $ref: '#/components/parameters/resourceVersion' @@ -238,14 +297,22 @@ paths: post: tags: - devices - summary: Create new device registration with auto-generated ID + summary: Create a new device registration with auto-generated ID + description: | + Clients use this operation to register a new device for an existing tenant with + an identifier that is generated by the registry. operationId: createDeviceRegistration requestBody: - description: New device + description: The configuration properties to register for the device. content: application/json: schema: $ref: '#/components/schemas/Device' + examples: + default: + $ref: '#/components/examples/DeviceDefaultExample' + extensions: + $ref: '#/components/examples/DeviceExtExample' required: false responses: 201: @@ -266,14 +333,21 @@ paths: post: tags: - devices - summary: Create new device registration + summary: Create a new device registration + description: | + Clients use this operation to register a new device with a given identifier. operationId: createDeviceRegistrationWithId requestBody: - description: New device + description: The configuration properties to register for the device. content: application/json: schema: $ref: '#/components/schemas/Device' + examples: + default: + $ref: '#/components/examples/DeviceDefaultExample' + extensions: + $ref: '#/components/examples/DeviceExtExample' required: false responses: 201: @@ -291,6 +365,8 @@ paths: tags: - devices summary: Get device registration information + description: | + Clients use this operation to retrieve the configuration properties of an existing device. operationId: getRegistration responses: 200: @@ -299,6 +375,28 @@ paths: application/json: schema: $ref: '#/components/schemas/Device' + examples: + fully-configured: + summary: Fully configured device + description: | + The body contains the configuration properties of a device which + has been configured extensively. + value: | + { + "enabled": true, + "defaults": { + "ttl": 300, + "content-type": "application/vnd.acme+json" + }, + "via": [ + "gw-1", "gw-4" + ], + "ext": { + "manufacturer": "ACME", + "model-no": "TEMP-SEN", + "serial-no": "3435A-454" + } + } headers: ETag: description: Version of the resource @@ -314,16 +412,33 @@ paths: put: tags: - devices - summary: Update existing device registration + summary: Update an existing device registration + description: | + Clients use this operation to replace an existing device's registration information + with the information contained in the request body. operationId: updateRegistration parameters: - $ref: '#/components/parameters/resourceVersion' requestBody: - description: Updated device registration + description: The configuration properties to replace the device's existing configuration with. content: application/json: schema: $ref: '#/components/schemas/Device' + examples: + disable-device: + summary: Disable a device + description: | + Disabling a device effectively prevents the device + to connect to any of the protocol adapters. If the device is + already connected to an adapter then it can no longer upload + any data nor receive any commands. Note that the example payload does + not contain any other properties than *enabled* which means + that all other configuration will be removed. + value: | + { + "enabled": false + } required: true responses: 204: @@ -342,7 +457,11 @@ paths: delete: tags: - devices - summary: Delete device registration + summary: Delete an existing device registration + description: | + Clients use this operation to remove an existing device from the registry. + Registry implementations may optionally perform a *cascading* delete of all + the device's credentials as well. operationId: deleteRegistration parameters: - $ref: '#/components/parameters/resourceVersion' @@ -369,6 +488,7 @@ paths: - credentials summary: Gets a device's set of credentials. description: | + Clients use this operation to retrieve the set of credentials registered for an existing device. Hono's protocol adapters use the credentials registered for a device in order to authenticate the device when it connects to an adapter. Implementors may return all of the credentials' data including all @@ -389,8 +509,8 @@ paths: schema: $ref: '#/components/schemas/CredentialsSet' examples: - Credentials Metadata: - $ref: '#/components/examples/MetaPasswordExample' + meta-data: + $ref: '#/components/examples/CredentialsMetaDataExample' headers: ETag: description: Version of the resource @@ -454,10 +574,10 @@ paths: schema: $ref: '#/components/schemas/CredentialsSet' examples: - Hashed Password: - $ref: '#/components/examples/HashedPasswordExample' - Plain Password: - $ref: '#/components/examples/PlainPasswordExample' + set-password: + $ref: '#/components/examples/CredentialsSetPasswordExample' + change-password: + $ref: '#/components/examples/CredentialsChangePasswordExample' required: true responses: 204: @@ -1132,35 +1252,94 @@ components: scheme: basic examples: - HashedPasswordExample: + + TenantAllAdaptersExample: + summary: All adapters + description: | + An empty request body can be used to create a tenant + using default values. This means that the tenant will be + enabled and devices of the tenant may connect to all + protocol adapters. + value: + + TenantMqttAdapterOnlyExample: + summary: MQTT adapter only + description: | + Creates a tenant with only the MQTT adapter enabled. + Devices of the tenant will thus not be able to connect + to any adapter other than the MQTT adapter. + value: | + { + "adapters": [{ + "type": "hono-mqtt", + "enabled": true + }] + } + + DeviceDefaultExample: + summary: Default properties + description: | + An empty request body can be used to create an enabled device + with no additional configuration. + + DeviceExtExample: + summary: Extension properties + description: | + Creates a device with some (application specific) extension properties. + value: | + { + "ext": { + "ep": "IMEI4711" + } + } + + CredentialsSetPasswordExample: + summary: Set pre-hashed password + description: | + The secret does not refer to an existing secret (no *id* property). Thus, the + existing secrets (if any) will be replaced with the hashed password secret. value: [{ - auth-id: sensor1, - type: hashed-password, - secrets: [{ - "not-after": "2027-12-24T19:00:00Z", - "pwd-hash": "AQIDBAUGBwg=", - "salt": "Mq7wFw==", - "hash-function": "sha-512" - }] + "auth-id": "sensor1", + "type": "hashed-password", + "secrets": [{ + "pwd-hash": "AQIDBAUGBwg=", + "salt": "Mq7wFw==", + "hash-function": "sha-512", + "not-after": "2027-12-24T19:00:00Z" + }] }] - PlainPasswordExample: + CredentialsChangePasswordExample: + summary: Change password + description: | + The secret refers to an existing hashed password which will be updated + with the included values. The plaintext password will be hashed using + the registry's default hash algorithm. value: [{ auth-id: sensor1, type: hashed-password, secrets: [{ "id": "349556ea-4902-47c7-beb0-1009ab693fb4", - "not-after": "2027-12-24T19:00:00Z", - "pwd-plain": "hono-secret" + "pwd-plain": "newpassword", + "not-after": "2027-12-24T19:00:00Z" }] }] - MetaPasswordExample: + + CredentialsMetaDataExample: + summary: Meta data only + description: | + The secrets do not contain the confidential information like password hash + or salt. Instead, the secrets contain an identifier which can be + used to refer to the secret in a subsequent update operation. value: - auth-id: sensor1 - type: hashed-password - secrets: [{ - "id": "349556ea-4902-47c7-beb0-1009ab693fb4", - "not-after": "2027-12-24T19:00:00Z", + [{ + "enabled": true, + "auth-id": "sensor1", + "type": "hashed-password", + "secrets": [{ + "id": "349556ea-4902-47c7-beb0-1009ab693fb4", + "not-after": "2027-12-24T19:00:00Z", + }] }] diff --git a/site/documentation/content/user-guide/file-based-device-registry.md b/site/documentation/content/user-guide/file-based-device-registry.md index f2742e2cde..4f83c4c59b 100644 --- a/site/documentation/content/user-guide/file-based-device-registry.md +++ b/site/documentation/content/user-guide/file-based-device-registry.md @@ -1,6 +1,6 @@ +++ title = "File Based Device Registry" -weight = 205 +weight = 206 +++ The Device Registry component provides exemplary implementations of Hono's [Tenant API]({{< relref "/api/tenant" >}}), [Device Registration API]({{< relref "/api/device-registration" >}}) and [Credentials API]({{< relref "/api/credentials" >}}). @@ -18,445 +18,12 @@ The resources have been designed to provide convenient access to the registry's ## Managing Tenants -The following sections describe the resources representing the operations of the Tenant API and how they can be used to manage tenants. -Please refer to the [Device Registry HTTP API]({{< relref "/api/management" >}}) for the specific elements that are explained in detail there. +Please refer to the [Device Registry Management API]({{< relref "/api/management#tenants" >}}) for information about managing tenants. -### Add a Tenant +## Managing Devices -* URI: `/v1/tenants/${tenantId}` -* Method: `POST` -* Request Headers: - * (required) `Content-Type`: `application/json` (no other type supported) -* Request Body: - * (Optional) A JSON object as specified by [Tenant schema]({{< relref "/api/management" >}}) of the HTTP API specification. -* Status Codes: - * 201 (Created): Tenant has been added successfully under the resource indicated by `Location` header. - * 400 (Bad Request): The tenant has not been created because the request was malformed, e .g. because the payload was malformed. The response body may contain hints regarding the cause of the problem. - * 409 (Conflict): A tenant with the given `tenantId` already exists. The request has not been processed. -* Response Headers: - * `Location`: The URI under which the newly created resource can be accessed. - * `ETag`: Version of the resource +Please refer to the [Device Registry Management API]({{< relref "/api/management#devices" >}}) for information about managing devices. -**Example** - -The following commands add some tenants with different adapter configurations: - -Add a tenant that has all adapters set to enabled: - -~~~sh -curl -i -X POST http://localhost:28080/v1/tenants/tenantAllAdapters - -HTTP/1.1 201 Created -ETag: becc93d7-ab0f-48ec-ad26-debdf339cbf4 -Location: /v1/tenants/tenantAllAdapters -Content-Type: application/json; charset=utf-8 - -{"id": "tenantAllAdapters"} -~~~ - -Add a tenant that can only use the MQTT adapter: - -~~~sh -curl -i -X POST -H 'Content-Type: application/json' --data-binary '{ - "adapters": [ { - "type": "hono-mqtt", - "enabled": true - } ] - }' http://localhost:28080/v1/tenants/tenantMqttAdapter - -HTTP/1.1 201 Created -ETag: becc93d7-ab0f-48ec-ad26-debdf339cbf4 -Location: /v1/tenants/tenantMqttAdapter -Content-Type: application/json; charset=utf-8 - -{"id": "tenantMqttAdapter"} -~~~ - -### Get configuration details of a Tenant - -* URI: `/v1/tenants/${tenantId}` -* Method: `GET` -* Status Codes: - * 200 (OK): A tenant with the given identifier has been found. The response body contains the tenant data as specified by [Tenant schema]({{< relref "/api/management" >}}) of the HTTP API specification. - * 404 (Not Found): No tenant with the given identifier is registered. - -**Example** - -The following command retrieves the details for the tenant `tenantMqttAdapter`: - -~~~sh -curl -i http://localhost:28080/v1/tenants/tenantMqttAdapter - -HTTP/1.1 200 OK -ETag: becc93d7-ab0f-48ec-ad26-debdf339cbf4 -Content-Type: application/json; charset=utf-8 - -{ - "enabled": true, - "adapters": [ { - "type": "hono-mqtt", - "enabled": true - } ] -} -~~~ - -**NB** A tenant can be created without specifying a tenant identifier. The device registry will generate a tenant ID: -~~~sh -curl -i -X POST http://localhost:28080/v1/tenants/ - -HTTP/1.1 201 Created -Etag: edc93899-7838-4dd1-93c8-839748c2fa42 -location: /v1/tenants/0b2df55f-1a02-43f7-a1c0-f3dbd25041e0 -content-type: application/json; charset=utf-8 -content-length: 45 - -{"id":"0b2df55f-1a02-43f7-a1c0-f3dbd25041e0"} -~~~ - -### Update Tenant - -* URI: `/v1/tenants/${tenantId}` -* Method: `PUT` -* Request Headers: - * (required) `Content-Type`: `application/json` (no other type supported) -* Request Body: - * (required) A JSON object as specified by [Tenant schema]({{< relref "/api/management" >}}) of the HTTP API specification. -* Status Codes: - * 204 (No Content): The tenant has been updated successfully. - * 400 (Bad Request): The tenant has not been updated because the request was malformed, e .g. because the payload was malformed. The response body may contain hints regarding the cause of the problem. - * 404 (Not Found): The request could not be processed because no tenant with the given identifier exists. - -This resource can be used to change the configuration of a particular tenant. - -**Example** - -The following command disables the MQTT adapter for devices that belong to the tenant `tenantMqttAdapter`: - -~~~sh -curl -i -X PUT -H 'Content-Type: application/json' --data-binary '{ - "adapters": [ { - "type": "hono-mqtt", - "enabled": true - } ] - }' http://localhost:28080/v1/tenants/tenantMqttAdapter - -HTTP/1.1 204 No Content -ETag: 8919c736-30aa-40ce-a45a-830b90c4cd42 -Content-Length: 0 -~~~ - -### Delete Tenant - -* URI: `/v1/tenants/${tenantId}` -* Method: `DELETE` -* Status Codes: - * 204 (No Content): The tenant with the given identifier has been deleted. - * 404 (Not Found): The request could not be processed because no tenant with the given identifier exists. - -**Example** - -~~~sh -curl -i -X DELETE http://localhost:28080/v1/tenants/tenantMqttAdapter - -HTTP/1.1 204 No Content -Content-Length: 0 -~~~ - -## Managing Device Registration Information - -The following sections describe the resources representing the operations of the [Device Registration API]({{< relref "/api/device-registration" >}}) and how they can be used to manage device registration information. -Please refer to the [Device Registry HTTP API]({{< relref "/api/management" >}}) for the specific elements that are explained in detail there. - -### Register Device - -* URI: `/v1/devices/${tenantId}/${deviceId}` -* Method: `POST` -* Headers: - * (required) `Content-Type`: `application/json` -* Request Body: - * (Optional) A JSON object as specified by [Device schema]({{< relref "/api/management" >}}) of the HTTP API specification. -* Status Codes: - * 201 (Created): Device has been registered successfully under resource indicated by `Location` header. - * 400 (Bad Request): Device has not been registered because the request was malformed, e .g. a required header is missing (the body may contain hints regarding the problem). - * 409 (Conflict): There already exists a device with the given ID. The request has not been processed. - -**Example** - -The following command registers a device with ID `4711` for tenant `DEFAULT_TENANT` - -~~~sh -curl -i -X POST -H 'Content-Type: application/json' --data-binary '{ - "ext": { - "ep": "IMEI4711" - } -}' http://localhost:28080/v1/devices/DEFAULT_TENANT/4711 -~~~ - -The response will contain a `Location` header containing the resource path created for the device. In this example it will look -like this: - -~~~sh -HTTP/1.1 201 Created -Location: /v1/devices/DEFAULT_TENANT/4711 -ETag: becc93d7-ab0f-48ec-ad26-debdf339cbf4 -Content-Type: application/json; charset=utf-8 - -{"id": "4711"} -~~~ - -**NB** A device can be created without specifying a device identifier. The device registry will generate a device identifier: -~~~sh -curl -i -X POST http://localhost:28080/v1/devices/DEFAULT_TENANT - -HTTP/1.1 201 Created -Etag: 0d615bcd-0825-44d9-9ef5-54a7b12165d8 -location: /v1/devices/DEFAULT_TENANT/98d25103-d49d-44b0-bdd0-0de84743c522 -content-type: application/json; charset=utf-8 -content-length: 45 - -{"id":"98d25103-d49d-44b0-bdd0-0de84743c522"} -~~~ - -### Read Device - -* URI: `/v1/devices/${tenantId}/${deviceId}` -* Method: `GET` -* Status Codes: - * 200 (OK): A device with the given identifier has been found. The response body contains the registration information as specified by [Device schema]({{< relref "/api/management" >}}) of the HTTP API specification. - * 404 (Not Found): No device with the given identifier is registered for the given tenant. - -**Example** - -The following command retrieves registration data for device `4711`: - -~~~sh -curl -i http://localhost:28080/v1/devices/DEFAULT_TENANT/4711 - -HTTP/1.1 200 OK -Content-Type: application/json; charset=utf-8 - -{ - "enabled": true, - "ext": { - "ep": "IMEI4711" - } -} -~~~ - -### Update Device - -* URI: `/devices/v1/${tenantId}/${deviceId}` -* Method: `PUT` -* Headers: - * (required) `Content-Type`: `application/json` -* Parameters (encoded as a JSON object in the request body): -* Request Body: - * (required) A JSON object as specified by [Device schema]({{< relref "/api/management" >}}) of the HTTP API specification. All existing registration information will be replaced by the data provided in the object. -* Status Codes: - * 204 (No Content): Device registration data has been updated. - * 400 (Bad Request): Device registration has not been updated because the request was malformed, e .g. a required header is missing (the body may contain hints regarding the problem). - * 404 (Not Found): No device with the given identifier is registered for the given tenant. - -**Example** - -~~~sh -curl -i -X PUT -H 'Content-Type: application/json' --data-binary '{ - "ext": { - "ep": "IMEI4711", - "psk-id": "psk4711" - } -}' http://localhost:28080/v1/devices/DEFAULT_TENANT/4711 - -HTTP/1.1 204 No Content -Content-Length: 0 -~~~ - -### Delete Device - -* URI: `/v1/devices/${tenantId}/${deviceId}` -* Method: `DELETE` -* Status Codes: - * 204 (No Content): Device registration has been deleted. - * 404 (Not Found): No device with the given identifier is registered for the given tenant. - -**Example** - -~~~sh -curl -i -X DELETE http://localhost:28080/v1/devices/DEFAULT_TENANT/4711 - -HTTP/1.1 204 No Content -Content-Length: 0 -~~~ - ## Managing Credentials -The following sections describe the resources representing the operations of the Credentials API and how they can be used to manage credentials for devices. -Please refer to the [Device Registry HTTP API]({{< relref "/api/management" >}}) for the specific elements that are explained in detail there. - -### Update Credentials for a Device - -* URI: `/v1/credentials/${tenantId}/${deviceId}` -* Method: `PUT` -* Request Headers: - * (required) `Content-Type`: `application/json` (no other type supported) -* Request Body: - * (required) A JSON object as specified by [Credentials schema]({{< relref "/api/management" >}}) of the HTTP API specification. -* Status Codes: - * 204 (No Content): Credentials have been updated successfully. - * 400 (Bad Request): The credentials have not been added because the request was malformed, e .g. because the payload did not contain required values. The response body may contain hints regarding the cause of the problem. -* Response Headers: - * `ETag`: Version of the resource - -**Example** - -The following command adds some `hashed-password` credentials from a given plain text password for device `4710` using authentication identifier `sensor10`: - -~~~sh -curl -i -X PUT -H 'Content-Type: application/json' --data-binary '[{ - "type": "hashed-password", - "auth-id": "sensor10", - "secrets": [{ - "pwd-plain": "mylittlesecret" - }] -}]' http://localhost:28080/v1/credentials/DEFAULT_TENANT/4710 - -HTTP/1.1 204 No Content -ETag: becc93d7-ab0f-48ec-ad26-debdf339cbf4x -~~~ - -This uses a convenient option which lets the Device Registry do the hashing of the password. The following command retrieves the credentials that are stored by the Device Registry as a result of the command above: - -~~~sh -curl -i http://localhost:28080/v1/credentials/DEFAULT_TENANT/4710 - -HTTP/1.1 200 OK -Content-Type: application/json; charset=utf-8 -ETag: becc93d7-ab0f-48ec-ad26-debdf339cbf4x - -[{ - "type": "hashed-password", - "auth-id": "sensor10", - "enabled": true, - "secrets": [ - { - "id": "349556ea-4902-47c7-beb0-1009ab693fb4" - } - ] -}] -~~~ -The above result does not contain `pwd_hash` and `hash_function` of the secret, as these values are confidential. - -The following commands set some `hashed-password` credentials for device `4720` using authentication identifier `sensor20`: - -~~~sh -curl -i -X PUT -H 'Content-Type: application/json' --data-binary '[{ - "type": "hashed-password", - "auth-id": "sensor20", - "secrets": [{ - "pwd-plain": "mylittlesecret" - }] - }]' http://localhost:28080/v1/credentials/DEFAULT_TENANT/4720 - -HTTP/1.1 204 No Content -ETag: 02c99fb5-af8c-409f-8520-b405e224b27f -~~~ - -The following command adds an expiration date to the `hashed-password` credentials for authentication identifier `sensor20`: - -~~~sh -curl -i -X PUT -H 'Content-Type: application/json' --data-binary '{ - "device-id": "4720", - "type": "hashed-password", - "auth-id": "sensor20", - "secrets": [{ - "pwd-plain": "mylittlesecret", - "not-after": "2018-01-01T00:00:00+01:00" - }] -}' http://localhost:28080/v1/credentials/DEFAULT_TENANT/4720 - -HTTP/1.1 204 No Content -ETag: becc93d7-ab0f-48ec-ad26-debdf339cbf4x -~~~ - -Multiple credentials of different type can be registered for the same authentication identifier. -The following commands add `psk` credentials for the same device `4720` using authentication identifier `sensor20`: - -~~~sh -SHARED_KEY=$(echo -n "TheSharedKey" | base64 -w 0) -curl -i -X PUT -H 'Content-Type: application/json' --data-binary '[ -{ - "type": "hashed-password", - "auth-id": "sensor20", - "secrets": [{ - "pwd-plain": "mylittlesecret" - }] -}, -{ - "device-id": "4720", - "type": "psk", - "auth-id": "sensor20", - "secrets": [{ - "key": "'$SHARED_KEY'" - }] - }]' http://localhost:28080/v1/credentials/DEFAULT_TENANT/4720 - -HTTP/1.1 204 No Content -ETag: 122c971a-505a-4336-8f7d-640360e909bc -~~~ - -The following command deletes all credentials for device `4710`: - -~~~sh -curl -i -X PUT -H 'Content-Type: application/json' --data-binary '[]' http://localhost:28080/v1/credentials/DEFAULT_TENANT/4710 - -HTTP/1.1 204 No Content -ETag: d383ba4d-1853-4d03-b322-b7ff5af05ae2 -~~~ - -### Get all Credentials for a Device - -* URI: `/v1/credentials/${tenantId}/${deviceId}` -* Method: `GET` -* Status Codes: - * 200 (OK): Credentials for the device have been found, body contains the credentials. The response body contains the registration information as specified by [Credentials schema]({{< relref "/api/management" >}}) of the HTTP API specification. - * 404 (Not Found): No credentials for the device are registered. - -**Example** - -The following command retrieves credentials metadata for device `4720`: - -~~~sh -curl -i http://localhost:28080/v1/credentials/DEFAULT_TENANT/4720 - -HTTP/1.1 200 OK -Content-Type: application/json; charset=utf-8 -ETag: f3449b77-2c84-4b09-8d04-2b305876e0cb - -{[ - { - "auth-id": "sensor20", - "enabled": true, - "secrets": [ - { - "id": "d383ba4d-1853-4d03-b322-b7ff5af05ae2" - "not-after": "2020-02-1T00:00:00+01:00" - }, - { - "id": "46810d5c-133e-4c1c-994d-ed7745516b8e" - "not-before": "2020-01-01T00:00:00+01:00" - } - ], - "type": "hashed-password" - }, - { - "auth-id": "sensor20", - "enabled": true, - "secrets": [ - { - "key": "VGhlU2hhcmVkS2V5" - } - ], - "type": "psk" - } -]} -~~~ +Please refer to the [Device Registry Management API]({{< relref "/api/management#credentials" >}}) for information about managing credentials. diff --git a/site/documentation/content/user-guide/mongodb-based-device-registry.md b/site/documentation/content/user-guide/mongodb-based-device-registry.md index b18239ae24..2344b0be27 100644 --- a/site/documentation/content/user-guide/mongodb-based-device-registry.md +++ b/site/documentation/content/user-guide/mongodb-based-device-registry.md @@ -1,6 +1,6 @@ +++ title = "MongoDB Based Device Registry" -weight = 206 +weight = 205 +++ The MongoDB based Device Registry component provides implementations of Hono's [Tenant API]({{< relref "/api/tenant" >}}), [Device Registration API]({{< relref "/api/device-registration" >}}) and [Credentials API]({{< relref "/api/credentials" >}}). As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information. Protocol adapters use these APIs to determine a device's registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it. @@ -13,12 +13,12 @@ This Device Registry secures its HTTP Endpoints using basic authentication mecha ## Managing Tenants -Please refer to the tenants section of the [Device Registry management API]({{< relref "/api/management" >}}) for how to manage tenants. +Please refer to the [Device Registry Management API]({{< relref "/api/management#tenants" >}}) for information about managing tenants. -## Managing Device Registration +## Managing Devices -Please refer to the devices section of the [Device Registry management API]({{< relref "/api/management" >}}) for how to manage registration information of devices. +Please refer to the [Device Registry Management API]({{< relref "/api/management#devices" >}}) for information about managing devices. ## Managing Credentials -Please refer to the credentials section of the [Device Registry management API]({{< relref "/api/management" >}}) for how to manage credentials of devices. +Please refer to the [Device Registry Management API]({{< relref "/api/management#credentials" >}}) for information about managing credentials.