IoT SDK examples

The IoT SDK examples demonstrate how to:

Authenticate a thing after manual registration
Authenticate a thing with dynamic registration
Request a user token for an authenticated thing

These examples assume 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:

Before you run the example, register the thing manually (using manual-thing as the thing’s ID).

Then, run the thing/manual-registration example:

cd /path/to/iot-edge
./run.sh example "thing/manual-registration" \
-name "manual-thing" \
-url "http://am.localtest.me:8080/openam" \
-tree "auth-tree"
Creating Thing manual-thing… Done
Requesting access token… Done
Access token: uk6gfxEwO4Qq8pDaijcD9ssmyqk
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

The Register Thing node supports multiple registration methods, specified in the node’s JWT Registration Method property. These examples show the different methods.

Proof-of-possession and certificate

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/dynamic-registration/pop-cert/main.go.

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

The example assumes the following node configuration in the auth-reg-tree:

Authenticate Thing node
- JWT Authentication Method : Proof of Possession
- Issue Restricted Token enabled
Register Thing node
- JWT Registration Method : Proof of Possession & Certificate
- Create Identity enabled

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

cd /path/to/iot-edge
./run.sh example "thing/dynamic-registration/pop-cert" \
-name "dynamic-thing" \
-url "http://am.localtest.me:8080/openam" \
-tree "auth-reg-tree"
Creating Thing dynamic-thing… Done
Requesting access token… Done
Access token: 9szFZrb006z1L7KF_dJCLNMsVPw
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.

Proof-of-possession and software statement

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 software statement that contains the key pair’s public key in the jwks claim.

The source code for this example is in /path/to/iot-edge/examples/thing/dynamic-registration/pop-sw-stmt/main.go.

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

Change the registration method in the Register Thing node. The example assumes the following node configuration in the auth-reg-tree:

Authenticate Thing node
- JWT Authentication Method : Proof of Possession
- Issue Restricted Token enabled
Register Thing node
- JWT Registration Method : Proof of Possession & Software Statement
- Create Identity enabled

If you have already run the Proof-of-possession and certificate example, delete the dynamic-thing identity in the AM admin UI before you run this example.

From the iot-edge directory, run the thing/dynamic-registration/pop-sw-stmt example:

cd /path/to/iot-edge
./run.sh example "thing/dynamic-registration/pop-sw-stmt" \
-name "dynamic-thing" \
-url "http://am.localtest.me:8080/openam" \
-tree "auth-reg-tree"
Creating Thing dynamic-thing… Done
Requesting access token… Done
Access token: RXDEVQBY6YgZNnX07FEtJRKd_Sg
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.

Software statement

This example registers a thing with a unique ID, rather than a specified name. After registration, the ID is retrieved and used to authenticate the thing. When the thing is authenticated, the flow requests an access token for the thing.

The flow mimics OAuth 2.0 Dynamic Registration and OAuth 2.0 JWT Bearer Authentication to request an access token, using a standard API.

The thing must have an asymmetric key pair for signing, and a software statement that contains the key pair’s public key in the jwks claim.

The source code for this example is in /path/to/iot-edge/examples/thing/dynamic-registration/sw-stmt/main.go.

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

Change the configuration of the auth-tree and the reg-tree as follows:

In the auth-tree set these values on the Authenticate Thing node:
- JWT Authentication Method : Client Assertion
- Issue Restricted Token disabled
In the reg-tree set these values on the Register Thing node:
- JWT Registration Method : Software Statement
- Create Identity enabled
- Under Default Attribute Values, click Add, then set thingType as the KEY and device as the VALUE

From the iot-edge directory, run the thing/dynamic-registration/sw-stmt example:

cd /path/to/iot-edge
./run.sh example "thing/dynamic-registration/sw-stmt" \
-url "http://am.localtest.me:8080/openam" \
-audience "http://am.localtest.me:8080/openam/oauth2/access_token" \
-reg-tree "reg-tree" \
-auth-tree "auth-tree"
Register thing using Software Statement… Done
Requesting attributes… Done
Attributes:  {map[_id:862b8345-d9cd-4931-911a-e8743c3d28cb thingConfig:[] thingKeys:[{"keys":[{"kty":"EC","kid":"veziPUQYgKIj0GTML2e2A4epDK_hfFqBZvAJhNzOjYs=","use":"sig","alg":"ES256","x":"n3DAs6v4YF3t0SzlV4wtRambjLBR4higehgBuMpSf00","y":"sP7JHsDIlF3W334wgSHl9rxSbN1TMg_tYOU9lUC2l1A","crv":"P-256"}]}]]}
Authenticate thing using Client Assertion… Done
Requesting access token… Done
Access token: UOVU_dN04HiEWiqd-1P0Fn4QGmY
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.

Log in to the AM admin UI and select Identities in the Top Level Realm to see the new identity in the list. The identity will have a unique ID, such as aa3373b1-93ef-49d0-bbbf-b95dcab6691b.

Proof-of-possession

This example creates a new identity with a specified name, authenticates the thing, and requests an access token for the thing. The thing must have an asymmetric key pair for signing. No trusted third party is used in this flow, so you should use this registration method only if the thing that is registering is already trusted.

The source code for this example is in /path/to/iot-edge/examples/thing/dynamic-registration/pop/main.go.

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

In the auth-reg-tree, change the configuration as follows:

Authenticate Thing node
- JWT Authentication Method : Proof of Possession
- Issue Restricted Token enabled
Register Thing node
- JWT Registration Method : Proof of Possession
- Create Identity enabled

If you have already run a previous registration example that created a named identity, delete the dynamic-thing identity in the AM admin UI before you run this example.

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

cd /path/to/iot-edge
./run.sh example "thing/dynamic-registration/pop" \
-name "dynamic-thing" \
-url "http://am.localtest.me:8080/openam" \
-tree "auth-reg-tree"
Creating Thing dynamic-thing… Done
Requesting access token… Done
Access token: n3cYnvOSq15s2wzSwKyTuQbkoD8
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.

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.

To request a user token, a user must 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 example assumes that user bjensen is authenticated and accepts the request.

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

In the auth-reg-tree, change the configuration as follows:

Authenticate Thing node
- JWT Authentication Method : Proof of Possession
- Issue Restricted Token enabled
Register Thing node
- JWT Registration Method : Proof of Possession & Certificate
- Create Identity enabled

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 "auth-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
}
Creating Thing user-authorized-thing… Done

Requesting user code… Done
 User code response: {
   "device_code":"eyJ0eXAiOiJKV1QiLC…p4GQHM",
   "user_code":"Y6GPhHpt",
   "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=Y6GPhHpt",
   "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=Y6GPhHpt

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

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

Click Allow.

The thing is now authenticated to AM and has received an access token. The output shows the complete flow.

Done
Access token response: {
"access_token": "I46b6E7k8xHyQPRcJ_Izcas1GVc",
"expires_in": 3599,
"refresh_token": "W9Yjr_7SEsnccw3x50f7o8PbWLs",
"scope": "subscribe publish",
"token_type": "Bearer"
}

Introspecting access token to get more information… Done
Introspection response: {
"active": true,
"auditTrackingId": "403dafaf-e367-4ef5-a485-e20fa44fbf0c-998197",
"authGrantId": "tQKArSNFxEJKX_PLFVcHGTKqby8",
"auth_level": 0,
"client_id": "forgerock-iot-oauth2-client",
"exp": 1656586652,
"iss": "http://am.localtest.me:8080/openam/oauth2",
"realm": "/",
"scope": "subscribe publish",
"sub": "(usr!bjensen)",
"subname": "bjensen",
"token_type": "Bearer",
"user_id": "bjensen",
"username": "bjensen"
}

Refreshing access token with reduced scope… Done
Access token response: {
"access_token": "fI4KL7Ui2CjkvtULGMDfw0CDXSk",
"expires_in": 3599,
"refresh_token": "FJ5mfvvB8eMtj7MOj2t4MSKOUsQ",
"scope": "publish",
"token_type": "Bearer"
}

Introspecting access token to get more information… Done
Introspection response: {
"active": true,
"auditTrackingId": "403dafaf-e367-4ef5-a485-e20fa44fbf0c-998250",
"authGrantId": "tQKArSNFxEJKX_PLFVcHGTKqby8",
"auth_level": 0,
"client_id": "forgerock-iot-oauth2-client",
"exp": 1656586652,
"iss": "http://am.localtest.me:8080/openam/oauth2",
"realm": "/",
"scope": "publish",
"sub": "(usr!bjensen)",
"subname": "bjensen",
"token_type": "Bearer",
"user_id": "bjensen",
"username": "bjensen"
}