IoT

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

  1. Create a directory structure for your Go project:

    mkdir -p things/cmd/gopher
  2. Create an empty project file (main.go ):

    cd things
    touch cmd/gopher/main.go
  3. 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.")
    }
  4. 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.

  5. 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

  1. 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": "/"
      }
    • Save the tokenId returned in this request as a variable, for example:

      export tokenId=qGAzvBw20z5…​AAA.*
      echo $tokenId
      qGAzvBw20z5…​AAA.*
    • Register the Gopher application, with the ID Gopher:

      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"
        ]
      }

      Log in to the AM admin UI and select Identities in the Top Level Realm, to see the Gopher identity in the list.

  2. Run the executable to authenticate your application to AM:

    ./gopher
    2020/09/01 11:09:49 Gopher successfully authenticated.
Copyright © 2010-2023 ForgeRock, all rights reserved.