Prerequisites

Install the Required Software

Download the following software before you evaluate ForgeRock IoT, and test the examples:

  • Go, version 1.15 or later.

  • Git (to download the source code and run the examples).

Get the Examples

  1. Clone the iot-edge Git repository:

    git clone https://github.com/ForgeRock/iot-edge.git

    This command creates a directory named iot-edge.

  2. Change to the iot-edge directory:

    cd /path/to/iot-edge

    The examples assume that this is your current working directory.

  3. The examples also assume that you are working with version 7.1.0 of the code.

    Check out the release/v7.1.0 branch:

    git checkout release/v7.1.0

Install and Configure AM

  1. Read the ForgeRockĀ® Access Management (AM) Evaluation Guide to set up an AM instance, with a default configuration.

    The examples in this guide assume the following:

  2. Log in to AM as user amAdmin with password changeit.

  3. Add an IoT service.

    The IoT service configures the identity store, adding the required Thing attributes to AM users (for all LDAPv3ForOpenDS and LDAPv3ForForgeRockIAM stores in the realm). For more information about this service, see IoT Service in the AM Reference :

    • In the Top Level Realm, select Services  Add a Service  IoT Service, and click Create.

    • Enable Create OAuth 2.0 Client.

      The IoT service creates an OAuth 2.0 Client with the given name and default configuration required to serve as the client for this service. The client is created without any scope(s), and is used by default for all Things that request access tokens.

      Advanced Use

      If a Thing (or group of Things) needs a client with different configuration to the default, you can create a custom client here, and add its name to the Thing’s thingOAuth2ClientName profile attribute.

    • Enable Create OAuth 2.0 JWT Issuer.

      The service creates a Trusted JWT Issuer with the given name and default configuration required for the IoT Service to act as the Issuer when handling requests for access tokens.

      Advanced Use

      If you configure the client manually, the JWT issuer must have the following settings:

      • JWT Issuer: forgerock-iot-service

      • Consented Scopes Claim: scope

      • Resource Owner Identity Claim: sub

      The signing/verification key used by this issuer is configured in the secrets store under am.services.iot.jwt.issuer.signing. It must use the HS256 algorithm.

    • Click Save Changes.

  4. Add an OAuth2 Provider service:

    • Select Services  Add a Service  OAuth2 Provider, and click Create.

    Advanced Use

    If your service will use the introspection feature of the SDK, change the following settings:

    • On the Core tab, enable Use Client-Based Access & Refresh Tokens.

    • On the Advanced tab, select an asymmetric key for the OAuth2 Token Signing Algorithm.

  5. Configure the IoT OAuth 2.0 client:

    • Select Applications  OAuth 2.0  Clients.

    • Click on forgerock-iot-oauth2-client.

    • In the Scope(s) field, add publish and subscribe.

    • Click Save Changes.

    Advanced Use

    If you create your own OAUth2 client here, make sure that the client contains the JWT Bearer, Device Code and Refresh Token grant types, and has a strong generated password.

  6. Create two authentication trees:

    • Select Authentication  Trees  Create Tree.

    • Type auth-tree in the Name field, and click Create.

    • Add an Authenticate Thing node and click Save.

      Show Me
      auth tree
    • Select Authentication  Trees  Create Tree.

    • Type reg-tree in the Name field, and click Create.

    • Add an Authenticate Thing node and a Register Thing node.

    • On the Register Thing node, enable Create Identity, then click Save.

      Show Me
      reg tree
  7. Add a secret ID mapping.

    • Select Configure  Secret Stores and click on the default-keystore.

    • On the Mappings tab, click + Add Mapping.

    • In the Secret ID list, select am.services.iot.cert.verification, and in the Alias field, type es256test then click Add.

      This mapping indicates which key the Register Thing node should use when verifying the registration certificate. The CA certificate in this example (es256test) is one of the test certificates included by default in AM.

    • Click Create to add the mapping.

    For more information about mapping secret IDs, see Mapping and Rotating Secrets in the AM Security Guide.