hawkbit/docs/device-provisioning.md

Device Provisioning

Device provisioning is the process of registering a device with the hawkBit update server so it can receive software updates. hawkBit supports two main provisioning scenarios:

• Provisioning and Registration via Management API: An administrator or backend system register devices in hawkBit before they connect by providing device identification and description. This approach provides centralized control and is ideal for pre-planned deployments.
• Direct Registration via DDI API: Devices register themselves automatically when they first connect to hawkBit. This is called auto-registration and is ideal for dynamic environments.

Provisioning and Registration via Management API

In this scenario, an administrator or backend system first provision the device using the Management UI or the Management API. This is the step where the device identification and description is provided.

When to Use

• Devices are provisioned during manufacturing or warehouse setup
• You need to assign software updates before devices are deployed
• You require strict inventory control
• You want to pre-configure security tokens
• Bulk provisioning of many devices

Prerequisites

• Management API access with appropriate permissions:
  • CREATE_TARGET - to create targets
  • UPDATE_TARGET - to modify targets
  • READ_TARGET - to view targets
• Valid credentials (username/password) for Basic Authentication
• Target Security Token authentication enabled on the server - see Configuration Properties below

Workflow

 %%{init: {'theme':'base', 'themeVariables': {
    'primaryColor':'#6BAF4A',
    'primaryTextColor':'#000',
    'primaryBorderColor':'#6BAF4A',
    'lineColor':'#4A2C5C',
    'secondaryColor':'#E8D5F2',
    'tertiaryColor':'#6BAF4A',
    'noteBkgColor':'#F5F5F5',
    'noteTextColor':'#000',
    'noteBorderColor':'#6BAF4A',
    'actorBorder':'#4A2C5C',
    'actorBkg':'#6BAF4A',
    'actorTextColor':'#000',
    'actorLineColor':'#4A2C5C',
    'signalColor':'#4A2C5C',
    'signalTextColor':'#000',
    'labelBoxBkgColor':'#E8D5F2',
    'labelBoxBorderColor':'#6BAF4A',
    'labelTextColor':'#000',
    'loopTextColor':'#000',
    'activationBorderColor':'#4A2C5C',
    'activationBkgColor':'#F5F5F5',
    'sequenceNumberColor':'#FFF'
  }}}%%
sequenceDiagram
    participant Admin as Admin/Backend System
    participant MgmtAPI as Management API<br/>(REST)
    participant Server as hawkBit Server
    participant DDIAPI as DDI API<br/>(REST)
    participant Device as Device

    Note over Admin,Device: Phase 1: Provisioning (Before Device Deployment)

    Admin->>MgmtAPI: POST /rest/v1/targets
    Note right of Admin: Create device with:<br/>- controllerId<br/>- name, description<br/>- securityToken (optional)<br/>- requestAttributes
    activate MgmtAPI
    MgmtAPI->>Server: Create Target Entity
    activate Server
    Server->>Server: Generate securityToken<br/>(if not provided)
    Server->>Server: Set updateStatus:<br/>"registered"
    Server-->>MgmtAPI: 201 Created
    deactivate Server
    MgmtAPI-->>Admin: Target created with<br/>securityToken
    deactivate MgmtAPI

    Note over Admin,Device: Phase 2: Device Registration (First Connection)

    Device->>DDIAPI: GET /{tenant}/controller/v1/{controllerId}
    Note right of DDIAPI: Authorization:<br/>TargetToken {securityToken}
    activate DDIAPI
    DDIAPI->>Server: Authenticate & Retrieve Target
    activate Server
    Server->>Server: Validate securityToken<br/>Update lastControllerRequestAt
    Server-->>DDIAPI: Target Configuration
    deactivate Server
    DDIAPI-->>Device: 200 OK<br/>Polling interval + links
    deactivate DDIAPI
    Note left of Device: config.polling.sleep<br/>_links.configData

    Note over Admin,Device: Phase 3: Add Device Attributes (Optional)

    Device->>DDIAPI: PUT /{tenant}/controller/v1/{controllerId}/configData
    Note right of DDIAPI: Send attributes:<br/>- hwRevision<br/>- VIN<br/>- OS version<br/>mode: "merge"
    activate DDIAPI
    DDIAPI->>Server: Update Target Attributes
    activate Server
    Server->>Server: Merge/Replace/Remove<br/>attributes
    Server-->>DDIAPI: 200 OK
    deactivate Server
    DDIAPI-->>Device: Configuration updated
    deactivate DDIAPI

Provisioning

Endpoint:

POST /rest/v1/targets

Request Headers:

Content-Type: application/json
Authorization: Basic <base64-encoded-credentials>

Request Body:

[
  {
    "controllerId": "device-12345",
    "name": "Production Device 12345",
    "description": "Temperature sensor - Building A",
    "address": "https://192.168.1.100",
    "securityToken": "myCustomToken123456",
    "requestAttributes": true,
    "targetType": 1
  }
]

See Target Entity Definition for all available fields.

Response: 201 Created

[
  {
    "createdBy": "admin",
    "createdAt": 1709212800000,
    "lastModifiedBy": "admin",
    "lastModifiedAt": 1709212800000,
    "controllerId": "device-12345",
    "name": "Production Device 12345",
    "description": "Temperature sensor - Building A",
    "updateStatus": "registered",
    "securityToken": "mySecureToken987654321",
    "address": "https://192.168.1.100",
    "lastControllerRequestAt": 0,
    "installedAt": 0,
    "_links": {
      "self": {
        "href": "http://localhost:8080/rest/v1/targets/device-12345"
      },
      "assignedDS": {
        "href": "http://localhost:8080/rest/v1/targets/device-12345/assignedDS"
      },
      "installedDS": {
        "href": "http://localhost:8080/rest/v1/targets/device-12345/installedDS"
      },
      "attributes": {
        "href": "http://localhost:8080/rest/v1/targets/device-12345/attributes"
      },
      "actions": {
        "href": "http://localhost:8080/rest/v1/targets/device-12345/actions"
      }
    }
  }
]

Registration

To complete the whole process, the provisioned device can register itself via the Direct Device Integration API using its controllerId and securityToken.

Endpoint:

GET /{tenant}/controller/v1/{controllerId}

Request Headers:

Authorization: TargetToken mySecureToken987654321

Response: 200 OK

{
  "config": {
    "polling": {
      "sleep": "00:05:00"
    }
  },
  "_links": {
    "configData": {
      "href": "http://localhost:8080/DEFAULT/controller/v1/device-12345/configData"
    }
  }
}

Add Device Attributes (Optional)

By following the link to configData provided in response to the last call, you can add some attributes to the device. In the code example below, we have shown how to add two attributes, namely hwRevision and VIN.

Endpoint: PUT {tenant}/controller/v1/{controllerId}/configData

Authentication: TargetToken

Request Headers:

Content-Type: application/json
Authorization: TargetToken mySecureToken987654321

Request Body:

{
  "mode": "merge",
  "data": {
    "hwRevision": "2",
    "VIN": "JH4TB2H26CC000000"
  }
}

Response: 200 OK

Best Practices

1. Security Tokens: Generate strong, unique tokens for each device (at least 32 characters)
2. Bulk Creation: Use array notation to create multiple targets in a single request
3. Target Types: Use target types to categorize devices (e.g., by hardware model)
4. Naming Convention: Use consistent, meaningful naming for controllerId (e.g., serial numbers)
5. Pre-assignment: Assign distribution sets before devices go online for immediate updates

---

Direct Registration via Direct Device Integration API

In this scenario, devices register themselves automatically when they first connect to hawkBit. This is called auto-registration and is ideal for dynamic environments.

When to Use

• Devices are manufactured without pre-registration
• You have a dynamic fleet with frequent additions
• Gateway devices manage multiple sub-devices
• You prefer decentralized, self-service provisioning
• IoT scenarios with thousands of devices

Prerequisites

• Gateway Token authentication enabled on the server:
  • Target Security Token mode (per-device tokens), OR
  • Gateway Token mode (single token for all devices in a tenant), OR
  • Certificate-based authentication (mTLS)
• Device must know its controllerId (typically MAC address, serial number, or UUID)

see Configuration Properties below for details on how to enable authentication modes.

Workflow

 %%{init: {'theme':'base', 'themeVariables': {
    'primaryColor':'#6BAF4A',
    'primaryTextColor':'#000',
    'primaryBorderColor':'#6BAF4A',
    'lineColor':'#4A2C5C',
    'secondaryColor':'#E8D5F2',
    'tertiaryColor':'#6BAF4A',
    'noteBkgColor':'#F5F5F5',
    'noteTextColor':'#000',
    'noteBorderColor':'#6BAF4A',
    'actorBorder':'#4A2C5C',
    'actorBkg':'#6BAF4A',
    'actorTextColor':'#000',
    'actorLineColor':'#4A2C5C',
    'signalColor':'#4A2C5C',
    'signalTextColor':'#000',
    'labelBoxBkgColor':'#E8D5F2',
    'labelBoxBorderColor':'#6BAF4A',
    'labelTextColor':'#000',
    'loopTextColor':'#000',
    'activationBorderColor':'#4A2C5C',
    'activationBkgColor':'#F5F5F5',
    'sequenceNumberColor':'#FFF'
  }}}%%
sequenceDiagram
    participant Device as Device
    participant DDIAPI as DDI API<br/>(REST)
    participant Server as hawkBit Server
    participant MgmtAPI as Management API<br/>(REST)
    participant Admin as Admin/Backend System

    Note over Device,Admin: Phase 1: Enable Gateway Token Authentication

    Admin->>MgmtAPI: GET /rest/v1/system/configs/authentication.gatewaytoken.key
    Note right of MgmtAPI: Basic Auth:<br/>admin credentials
    activate MgmtAPI
    MgmtAPI->>Server: Retrieve Gateway Token
    activate Server
    Server-->>MgmtAPI: Gateway Token Value
    deactivate Server
    MgmtAPI-->>Admin: Gateway Token:<br/>3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW
    deactivate MgmtAPI

    Note over Device,Admin: Phase 2: Device Auto-Registration (First Connection)

    Device->>DDIAPI: GET /{tenant}/controller/v1/{controllerId}
    Note right of DDIAPI: Authorization:<br/>GatewayToken {token}
    activate DDIAPI
    DDIAPI->>Server: Authenticate & Check Target
    activate Server
    Server->>Server: Target not found
    Server->>Server: Auto-create Target:<br/>- controllerId<br/>- updateStatus: "registered"<br/>- createdBy: "system"
    Server->>Server: Generate securityToken<br/>Update lastControllerRequestAt
    Server-->>DDIAPI: Target Configuration
    deactivate Server
    DDIAPI-->>Device: 200 OK<br/>Polling interval + links
    deactivate DDIAPI
    Note left of DDIAPI: config.polling.sleep<br/>_links.configData

    Note over Device,Admin: Phase 3: Add Device Attributes (Optional)

    Device->>DDIAPI: PUT /{tenant}/controller/v1/{controllerId}/configData
    Note right of DDIAPI: Send attributes:<br/>- hw_revision<br/>- os_version<br/>- serial_number<br/>mode: "merge"
    activate DDIAPI
    DDIAPI->>Server: Update Target Attributes
    activate Server
    Server->>Server: Merge/Replace/Remove<br/>attributes
    Server-->>DDIAPI: 200 OK
    deactivate Server
    DDIAPI-->>Device: Configuration updated
    deactivate DDIAPI

Enable Gateway Token Authentication

All devices share a single token for the tenant. Use with caution in production.

Enable in system configuration:

hawkbit.server.ddi.security.authentication.gatewaytoken.enabled=true

Enable in tenant configuration:

authentication.gatewaytoken.enabled=true

Retrieve Gateway Token:

curl http://localhost:8080/rest/v1/system/configs/authentication.gatewaytoken.key \
  -u admin:admin

Response:

{
  "value": "3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW",
  "global": false,
  "lastModifiedAt": 1770794878411,
  "lastModifiedBy": "admin",
  "createdAt": 1770794562205,
  "createdBy": "admin",
  "_links": {
    "self": {
      "href": "http://localhost:8080/rest/v1/system/configs/authentication.gatewaytoken.key"
    }
  }
}

Device Auto-Registration on First Poll

The device polls the hawkBit server using its controllerId. If the target doesn't exist, hawkBit creates it automatically.

Endpoint:

GET /{tenant}/controller/v1/{controllerId}

Authentication: GatewayToken

Request Headers:

Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW

Response: 200 OK

{
  "config": {
    "polling": {
      "sleep": "00:05:00"
    }
  },
  "_links": {
    "configData": {
      "href": "http://localhost:8080/DEFAULT/controller/v1/device-abc-001/configData"
    }
  }
}

Add Device Attributes (Optional)

The device can send its attributes (hardware version, OS version, custom data) to hawkBit.

Endpoint: PUT {tenant}/controller/v1/{controllerId}/configData

Authentication: GatewayToken

Request Headers:

Content-Type: application/json
Authorization: GatewayToken mySecureToken987654321

Request Body:

{
  "mode": "merge",
  "data": {
    "hw_revision": "1.2",
    "os_version": "Linux 5.10.0",
    "serial_number": "SN123456789",
    "mac_address": "00:1A:2B:3C:4D:5E"
  }
}

Modes:

• merge: Merge new attributes with existing ones
• replace: Replace all attributes with new data
• remove: Remove specified attributes

Response: 200 OK

Best Practices

1. Authentication: Use Target Security Tokens or certificates in production; Gateway Tokens only for development
2. Polling Interval: Respect the server-provided polling interval to avoid overloading the server
3. Attributes: Send detailed device attributes to enable filtering and reporting
4. Controller ID: Use persistent, unique identifiers (MAC address, serial number, UUID)
5. Feedback: Always send feedback after updates (success/failure) for audit trails
6. Error Handling: Implement exponential backoff on connection failures

---

Comparison: Management API vs DDI API

Aspect	Management API Provisioning	DDI Auto-Registration
Timing	Before device deployment	On first device connection
Control	Centralized by admin	Decentralized (device-initiated)
Use Case	Pre-planned deployments	Dynamic fleet management
Authentication	Basic Auth (admin credentials)	TargetToken / GatewayToken / mTLS
Security Token	Set during creation or auto-generated	Auto-generated on registration
Pre-assignment	Possible before device connects	Only after first poll
Scalability	Manual or scripted bulk creation	Automatic, scales infinitely
Device Attributes	Must be set via separate request	Device sends on first connection
Audit Trail	createdBy: admin	createdBy: system

---

Security Considerations

Management API

1. Access Control: Restrict Management API access using role-based permissions
2. Credentials: Use strong passwords and consider API keys for automated systems
3. HTTPS: Always use HTTPS in production to protect credentials
4. Token Generation: Generate cryptographically random security tokens (32+ characters)
5. Least Privilege: Grant only necessary permissions (e.g., CREATE_TARGET for provisioning systems)

DDI API

1. Gateway Token: Never use in production for large deployments; prefer per-device tokens
2. Token Storage: Devices should securely store their security tokens (TPM, secure element)
3. Certificate Auth: Use mTLS for maximum security in IoT deployments
4. Token Rotation: Consider implementing token rotation mechanisms
5. Auto-Registration: Disable auto-registration in highly secure environments; use Management API only

---

Configuration Properties

Enable DDI Authentication Modes

System-wide (application.properties):

# Target Security Token (per-device)
hawkbit.server.ddi.security.authentication.targettoken.enabled=true

# Gateway Token (shared token)
hawkbit.server.ddi.security.authentication.gatewaytoken.enabled=true

# Anonymous downloads (not recommended for production)
hawkbit.server.ddi.security.authentication.anonymous.enabled=false

---

Related Documentation

• Management API - Complete Management API reference
• Direct Device Integration API - Complete DDI API reference
• Authentication - Detailed authentication mechanisms
• Authorization - Role-based access control
• Entity Definitions - Data models and schemas

---