Developers Guide

Guide to building applications with the IoT SDK.


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.

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

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 a ForgeRock IoT 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 (
    func main() {
        amURL, err := url.Parse("")
        if err != nil {
        _, err = builder.Thing().
                callback.NameHandler{Name: "Gopher"},
                callback.PasswordHandler{Password: "5tr0ngG3n3r@ted"}).
        if err != nil {
        log.Println("Gopher successfully authenticated.")
  4. Create a Go module:

    go mod init
    go: creating new go.mod: module

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

  5. Build an executable for your client application:

    go build
    go: finding module for package
    go: finding module for package
    go: downloading v0.0.0-20200812141306-ee64981fa05f
    go: downloading v7.1.0
    go: found in v7.1.0
    go: found in v7.1.0

    This step builds an executable gopher application in the things directory.

Run the Client Application

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

    • Obtain 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 \
       "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
    • 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 \
        "_id": "Gopher",
        "_rev": "-1",
        "realm": "/",
        "username": "Gopher",
        "uid": [
        "universalid": [
        "objectClass": [
        "dn": [
        "inetUserStatus": [
        "cn": [
        "sn": [
        "thingType": [
        "createTimestamp": [

      Sign 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:

    2020/09/01 11:09:49 Gopher successfully authenticated.

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

  1. On your target system, navigate to the gateway directory:

    cd /path/to/iot-edge/cmd/gateway
  2. Build the IoT Gateway binary:

    go build -o ./bin/gateway .

    The IoT Gateway binary is now available at bin/gateway

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

    ./bin/gateway --help
      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).

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

    GOOS=linux GOARCH=arm go build -o ./bin/linux_arm/gateway .
  2. For a complete list of environment and cross-compilation targets, see the go Documentation.

    For more build options, see the go command environment variables