Untitled :: ForgeRock IoT

Develop IoT clients

This guide shows you how to use the IoT SDK to develop client applications and to register them with AM. It also shows you how to build the IoT Gateway.

Develop a client

Develop a client application with the IoT SDK.

Requirements

Build the IoT Gateway for your target system.

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Develop a client application with the IoT SDK

This section shows you how to create a client application for a thing, named Gopher. The thing is manually registered in AM and authenticated with a username/password authentication flow. For more information about the IoT SDK API, see the Go package documentation.

Develop the application

These steps assume that you have installed the required software and cloned the things GitHub repository:

Create a directory structure for your Go project:
```
mkdir -p things/cmd/gopher
```
Create an empty project file (main.go ):
```
cd things
touch cmd/gopher/main.go
```

Open main.go in a text editor, and add the following code:

package main

import (
    "github.com/ForgeRock/iot-edge/v7/pkg/builder"
    "github.com/ForgeRock/iot-edge/v7/pkg/callback"
    "log"
    "net/url"
)

func main() {
    amURL, err := url.Parse("http://am.localtest.me:8080/openam")
    if err != nil {
        log.Fatal(err)
    }
    _, err = builder.Thing().
        ConnectTo(amURL).
        InRealm("/").
        WithTree("Example").
        HandleCallbacksWith(
            callback.NameHandler{Name: "Gopher"},
            callback.PasswordHandler{Password: "5tr0ngG3n3r@ted"}).
        Create()
    if err != nil {
        log.Fatal(err)
    }
    log.Println("Gopher successfully authenticated.")
}

Create a Go module:

go mod init example.com/things && go mod tidy
go: creating new go.mod: module example.com/things
go: to add module requirements and sums:
        go mod tidy
go: finding module for package github.com/ForgeRock/iot-edge/v7/pkg/callback
go: finding module for package github.com/ForgeRock/iot-edge/v7/pkg/builder
go: found github.com/ForgeRock/iot-edge/v7/pkg/builder in github.com/ForgeRock/iot-edge/v7 v7.4.0
go: found github.com/ForgeRock/iot-edge/v7/pkg/callback in github.com/ForgeRock/iot-edge/v7 v7.4.0

This step creates a go.mod file that specifies your project dependencies and versions.

Build an executable for your client application:
```
go build example.com/things/cmd/gopher
```
This step builds an executable gopher application in the things directory.

Run the application

Before you can run the application, you must register an identity for Gopher in AM:

Get an admin SSO token from AM:

curl \
--header 'X-OpenAM-Username: amAdmin' \
--header 'X-OpenAM-Password: changeit' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
--request POST \
'http://am.localtest.me:8080/openam/json/authenticate'
{
 "tokenId": "qGAzvBw20z5…AAA.*",
 "successUrl": "/openam/console",
 "realm": "/"
}

bash

Save the tokenId returned in this request as a variable, for example:

export tokenId=qGAzvBw20z5…AAA.*
echo $tokenId
qGAzvBw20z5…AAA.*

bash

curl \
--header 'Content-Type: application/json' \
--header 'Accept-Api-Version: resource=4.0, protocol=2.1' \
--cookie "iPlanetDirectoryPro=${tokenId}" \
--data '{
    "userPassword": "5tr0ngG3n3r@ted",
    "thingType": "device"
}' \
--request PUT \
"http://am.localtest.me:8080/openam/json/realms/root/users/Gopher"
{
  "_id": "Gopher",
  "_rev": "-1",
  "realm": "/",
  "username": "Gopher",
  "uid": [
    "Gopher"
  ],
  "universalid": [
    "id=Gopher,ou=user,dc=openam,dc=forgerock,dc=org"
  ],
  "objectClass": [
    "iplanet-am-managed-person",
    "inetuser",
    "fr-iot",
    "sunFMSAML2NameIdentifier",
    "inetorgperson",
    "devicePrintProfilesContainer",
    "iplanet-am-user-service",
    "iPlanetPreferences",
    "pushDeviceProfilesContainer",
    "forgerock-am-dashboard-service",
    "organizationalperson",
    "top",
    "kbaInfoContainer",
    "person",
    "sunAMAuthAccountLockout",
    "oathDeviceProfilesContainer",
    "webauthnDeviceProfilesContainer",
    "iplanet-am-auth-configuration-service",
    "deviceProfilesContainer"
  ],
  "dn": [
    "uid=Gopher,ou=people,dc=openam,dc=forgerock,dc=org"
  ],
  "inetUserStatus": [
    "Active"
  ],
  "cn": [
    "Gopher"
  ],
  "sn": [
    "Gopher"
  ],
  "thingType": [
    "device"
  ],
  "createTimestamp": [
    "20200831103235Z"
  ]
}

bash

Run the executable to authenticate your application to AM:
```
./gopher
2020/09/01 11:09:49 Gopher successfully authenticated.
```
bash

Build the ForgeRock IoT Gateway

ForgeRock does not deliver binaries for the IoT Gateway. There are simply too many operating system and architecture combinations to support. The IoT Gateway and the IoT SDK are developed in the Go programming language primarily because it has uncomplicated build tooling and good support for cross-compilation to target systems.

Build the IoT Gateway on a target system

These steps assume that you have installed the required software and cloned the Things GitHub repository:

On your target system, navigate to the gateway directory:
```
cd /path/to/iot-edge/cmd/gateway
```
Build the IoT Gateway binary:
```
go build -o ./bin/gateway .
```
The IoT Gateway binary is now available at bin/gateway

Run the IoT Gateway with the --help flag for available command-line options:

./bin/gateway --help
Usage:
  gateway [OPTIONS]

Application Options:
      --url=      AM URL
      --realm=    AM Realm
      --audience= JWT Audience
      --tree=     Authentication tree
      --name=     Gateway name
      --address=  CoAP Address of Gateway
      --key=      The file containing the Gateway's signing key
      --kid=      The Gateway's signing key ID
      --cert=     The file containing the Gateway's certificate
      --timeout=  Timeout for AM communications (default: 5s)
  -d, --debug     Switch on debug

Help Options:
  -h, --help      Show this help message

Cross-compile the IoT Gateway for a target system

You can specify a target system with a combination of the $GOOS and $GOARCH environment variables. This lets you build the IoT Gateway for a variety of operating system and architecture combinations.

This example runs the IoT Gateway on an arm 32-bit processor (for example, a Raspberry Pi 3 running in 32-bit mode).

Build the IoT Gateway for linux/arm, as follows:

GOOS=linux GOARCH=arm go build -o ./bin/linux_arm/gateway .

For a complete list of environment and cross-compilation targets, see the go Documentation.

For more build options, see the go command environment variables.