IoT SDK Examples

The IoT SDK examples demonstrate how to:

This section assumes that you have downloaded the example repository and that the iot-edge directory is your current directory.

Authenticate a Thing After Manual Registration

This example authenticates a Thing and requests an access token for the Thing. The Thing must have an asymmetric key pair for signing. This is provided in the /path/to/iot-edge/examples/resources directory. The source code for this example is in /path/to/iot-edge/examples/thing/simple/main.go.

This sequence diagram shows how the Thing is authenticated for the session:

manual-registration

Before you run the example, register the Thing manually (using manual-thing as the Thing’s ID). Then, run the thing/simple example:

cd /path/to/iot-edge
./run.sh example "thing/simple" \
-name "manual-thing" \
-url "http://am.localtest.me:8080/openam" \
-tree "auth-tree"
Creating Thing manual-thing... Done
 Requesting access token... RequestAccessToken response:  {
 "access_token":"iaZqWRyVBhGMLWwAOzDrOtKarfw",
 "scope":"publish",
 "token_type":"Bearer",
 "expires_in":3599}
 Done
 Access token: iaZqWRyVBhGMLWwAOzDrOtKarfw
 Expires in: 3599
 Scope(s): [publish]

 ______     __  __
 /\  __ \   /\ \/ /
 \ \ \/\ \  \ \  _"-.
 \ \_____\  \ \_\ \_\
 \/_____/   \/_/\/_/

The Thing is now authenticated to AM and has received an access token.

Authenticate a Thing With Dynamic Registration

This example registers a new identity, authenticates the Thing, and requests an access token for the Thing. The Thing must have an asymmetric key pair for signing, and a CA-signed X.509 certificate that contains the key pair’s public key. These are provided in the /path/to/iot-edge/examples/resources directory. The source code for this example is in /path/to/iot-edge/examples/thing/cert-registration/main.go.

This sequence diagram shows how the Thing is registered and authenticated for the session:

dynamic-registration

From the iot-edge directory, run the thing/cert-registration example:

cd /path/to/iot-edge
./run.sh example "thing/cert-registration" \
-name "dynamic-thing" \
-url "http://am.localtest.me:8080/openam" \
-tree "reg-tree"
Creating Thing dynamic-thing... Done
 Requesting access token... RequestAccessToken response:  {
   "access_token":"84T-lIAwUImk9NTP6ObKKWZouW8",
   "scope":"publish",
   "token_type":"Bearer",
   "expires_in":3599
 }
 Done
 Access token: 84T-lIAwUImk9NTP6ObKKWZouW8
 Expires in: 3599
 Scope(s): [publish]

 ______     __  __
 /\  __ \   /\ \/ /
 \ \ \/\ \  \ \  _"-.
 \ \_____\  \ \_\ \_\
 \/_____/   \/_/\/_/

The Thing is now registered with the ID dynamic-thing. It is authenticated to AM and has received an access token.

Sign in to the AM Admin UI and select Identities in the Top Level Realm to see the dynamic-thing in the list.

Request a User Token for an Authenticated Thing

This example creates a new identity for a Thing, using dynamic registration, and then authenticates it. When the Thing is authenticated, it requests a user access token using the OAuth 2.0 Device Authorization Grant. The access token authorizes the thing to access a user’s resources, or act on behalf of the user, as specified by the scope granted by the user.

The example demonstrates how the Thing can manage the access token’s lifecycle by introspecting and refreshing the token.

Requesting a user token requires a user to be registered and authenticated before approving the request. When you run the example, the user is directed to a URL to perform the authorization.

This sequence diagram shows how the Thing is authorized for the session:

user-token-request

  1. Run the thing/user-token example:

    cd /path/to/iot-edge
./run.sh example "thing/user-token" \
-name "user-authorized-thing" \
-url "http://am.localtest.me:8080/openam" \
-tree "reg-tree"

Creating Thing user-authorized-thing…​ Done

Requesting user code…​ Done
User code response: {
 "device_code":"code",
 "user_code":"code",
 "verification_uri":"http://am.localtest.me:8080/openam/oauth2/device/user",
 "verification_uri_complete":"http://am.localtest.me:8080/openam/oauth2/device/user?user_code=code",
 "expires_in":300,
 "interval":5
}
Requesting user access token…​ To authorise the request, go to

http://am.localtest.me:8080/openam/oauth2/device/user?user_code=code

  2. Go to http://am.localtest.me:8080/openam/oauth2/device/user?user_code=code and click Confirm.

    You are redirected to a screen that lets you confirm the authentication request:

  3. Click Allow.

    The Thing is now authenticated to AM and has received an access token.