Guide to developing client applications with the ForgeRock® Identity Edge Controller (IEC).
Preface
This guide shows you how to use the ForgeRock® Identity Edge Controller (IEC) SDK to develop client applications and to register them with the IEC Service. The IEC SDK client library provides client APIs in C and Go for client applications to invoke ForgeRock Access Management (AM) functionality through the IEC Service.
The SDK library is small and uses a secure lightweight messaging protocol so that it can run on constrained devices. The examples in this Guide use the C API. Adjust the examples if you are using Go.
Chapter 1. Before You Start
Before you start developing clients, it is helpful to have an overview of the IEC and its components. Read Getting Started first.
The IEC Service attests for both clients (SDK) and devices. Onboarding either of these node types will fail if the IEC Service has not registered successfully with AM. In general, the functional flow is from the SDK Client library (libiecclient.so
) API, via ZMQ and the IEC Service to the AM IEC Plugin and back.
The code examples in this guide assume that you have installed all the required components, including the IEC SDK, and that everything is up and running, as described in the Installation Guide. The examples also assume that you have unpacked the SDK in a directory named ~/forgerock
and that you have set the LIBRARY_PATH
variables, as described in "To Install the IEC SDK" in the Installation Guide. Adjust the examples for your environment.
1.1. About the Build Script
The SDK includes a sample client application named simpleclient
that allows you to test that all your IEC components are up and running and serves as a reference for building your first client application. The SDK also includes a build script named build-examples.sh
. This script sets the required environment variables and builds all applications that it finds in the following directories:
~/forgerock/examples/app-name
The script assumes that the application consists of a single C file named ~/forgerock/examples/app-name/app-name.c
and creates an executable application named app-name in the corresponding ~/forgerock/examples/app-name
directory.
Before you use the script, open it in a text editor and adjust the path to your local compiler, for example:
export CC=usr/bin/gcc
The build script is not executable by default. Make sure that the script is executable before you try the examples in this guide:
chmod +x build-examples.sh
1.2. Using the Training Environment
ForgeRock provides a training environment that enables you to get all the IEC components up and running very quickly in Docker containers, and to test your client applications.
The training environment includes all the sample applications referenced in this guide. The default credentials for the AM admin user in the training environment are amadmin
and password
. The environment already has the required configured realm named edge
. If you are not using the training environment, configure this realm, as described in "Configuring AM for IoT" in the Installation Guide.
The training environment is open source and anyone with a GitHub account can use or contribute to the project.
Although it is easiest to get started using the training environment, the remainder of this guide assumes that you are developing applications in your own environment.
Chapter 2. Initializing Client Applications With the IEC SDK
The IEC SDK requires access to a configuration to provide keys, URLs, and so on. After you have installed and registered the IEC Service, you can initialize this configuration in two ways:
Manually, using a JSON configuration file and the
iecutil
utility.Dynamically, using the
iec_set_attribute
function to set individual attribute values.
2.1. Initializing a Client Manually
The iecutil
utility creates a configuration database (named iec-sdk.db
) based on the properties in this configuration file. A sample configuration file follows:
{ "zmq_client": { "endpoint": "tcp://127.0.0.1:5556", "secret_key":"zZZfS7BthsFLMv$]Zq{tNNOtd69hfoBsuc-lg1cM", "public_key":"uH^{aIzDw5,...TRbHcu0q#(zo]uLl6Wyv/1{/^C+", "server_public_key":"9m27tKf3....G-f[>W]gP%fPD:?mX*)hdJ", "msg_timeout_sec": 5 }, "logging": { "enabled": true, "debug": true, "max_file_size_mb": 5, "max_backup_files": 5, "max_file_age_days": 0, "compress_file_backups": true }, "client_configuration": { "id": "iec-client" } }
The configuration database must exist for the ZMQ communication to be established. Once the database exists, you can update it from AM through the IEC Service. For security reasons, you should delete or protect the JSON configuration file once the client has been initialized.
To initialize a client manually:
Your C application must include the
libiecclient.h
library and a call toiec_initialise()
.See the example client application init_sdk_static.c.
Create a new directory in the
~/forgerock/examples
directory, with the same name as your client application and place the C application in that directory.For example, to build the
init_sdk_static.c
sample application, copy init_sdk_static.c. into a new directory namedinit_sdk_static
:mkdir ~/forgerock/examples/init_sdk_static cp init_sdk_static.c ~/forgerock/examples/init_sdk_static
Run the build script to set the build variables and build the application:
~/forgerock/build-examples.sh
The build script creates the application
init_sdk_static
in the~/forgerock/examples/init_sdk_static
directory:ls examples/init_sdk_static/ init_sdk_static init_sdk_static.c
Copy the database configuration file (
sdk-config.json
) to the directory containing your application. For example:cp ~/forgerock/sdk-config.json ~/forgerock/examples/init_sdk_static
Edit the database configuration file to specify the IP address on which the SDK runs. For example, if you are setting this up in the training environment, edit the file as follows:
zmq_client.endpoint: tcp://172.16.0.11:5556
Note
The value provided for client_configuration/id is used as the name of the client identity and must be unique within the AM realm. [1]
Change to the directory in which your client application is located, then use
iecutil
to initialize the client application, based on the database configuration file in that directory:cd ~/forgerock/examples/init_sdk_static ~/forgerock/iecutil -file sdk-config.json -initialise sdk iec util: Initialising sdk iec util: Finished sdk initialisation
An SDK application looks in the directory from which it's run for a configuration database or for a file that contains the database location.
Note
If you change the configuration and need to reinitialize the SDK, remove the
iec-sdk.db
in the application directory, then run the initialization again.Run the example application:
cd ~/forgerock/examples/init_sdk_static ./init_sdk_static
If the initialization was successful, you should see the
iec-client
identity in the Edge Identity Manager Console.
2.2. Initializing a Client Dynamically
Dynamic configuration takes precedence over a manual database configuration, if one exists. You can use the iec_set_attribute
utility to set a number of configuration attribute values, such as the IEC_ENDPOINT
and IEC_SECRETKEY
. For a list of all the attributes, see the libiectypes.h library.
To initialize the client dynamically:
Your C application must include the
libiecclient.h
library, and provide the complete SDK configuration with theiec_set_attribute()
function.See the sample client application init_sdk_dynamic.c.
If you are working in the training environment, the sample application is already present in
~/forgerock/examples/init_sdk_dynamic
. If you are not working in the training environment, create a new directory in the~/forgerock/examples
directory, with the same name as your client application and place the C application in that directory.For example, to build the
init_sdk_dynamic.c
application, copy init_sdk_dynamic.c into a new directory namedinit_sdk_dynamic
:mkdir ~/forgerock/examples/init_sdk_dynamic cp init_sdk_dynamic.c ~/forgerock/examples/init_sdk_dynamic
Run the build script to set the build variables and build the application:
~/forgerock/build-examples.sh
The build script creates the application
init_sdk_dynamic
in the~/forgerock/examples/init_sdk_dynamic
directory:ls examples/init_sdk_dynamic/ init_sdk_dynamic init_sdk_dynamic.c
Run the example application:
cd ~/forgerock/examples/init_sdk_dynamic ./init_sdk_dynamic
*** Initialising the SDK dynamically *** SDK function(s): iec_initialise Setting dynamic attributes... Done Initialising sdk... Done
If the initialization was successful, you should see the
iec-dynamic-client
identity in the Edge Identity Manager Console.
[1] If the value provided contains a colon character (:), it must be a valid URI. For more information, see StringOrURI in the JSON Web Token specification.
Chapter 3. Registering a Device
A client application developed with the IEC SDK can register a device ID with AM and provide configuration from AM for the device with this ID.
Note
There is a wide range of device node types from many different manufacturers. Specific programming and configuration of these devices is outside the scope of the IEC project.
To register a device:
Your client application must include the
libiecclient.h
library and a call toiec_device_register()
.See the sample client application register_device.c. This sample application includes dynamic client initialization, shown in "Initializing a Client Dynamically".
If you are working in the training environment, the sample application is already present in
~/forgerock/examples/register_device
. If you are not working in the training environment, create a new directory in the~/forgerock/examples
directory, with the same name as your client application and place the C application in that directory.For example, copy register_device.c into a new directory named
register_device
:mkdir ~/forgerock/examples/register_device cp register_device.c ~/forgerock/examples/register_device
Set the device ID and any custom registration data. In the example, the device ID is
Narwhal
. [2]Note
The registration data is discarded as soon as the device is registered. No registration data is stored in AM.
Run the build script to set the build variables and build the application:
~/forgerock/build-examples.sh
The build script creates the application
register_device
in the~/forgerock/examples/register_device
directory:ls examples/register_device/ register_device register_device.c
Run the example application:
cd ~/forgerock/examples/register_device ./register_device
*** Registering a device *** SDK function(s): iec_initialise, iec_device_register Setting dynamic attributes... Done Initialising sdk... Done Registering device (id: Narwhal)... Done
If the registration was successful, you should see the
Narwhal
identity in the Edge Identity Manager Console. Thereg-dev-client
identity is the identity of your client application, set with theIEC_CLIENT_ID
dynamic attribute.
3.1. Understanding the Device Registration Process
The device registration flow is as follows:
The call to
iec_device_register
initiates the registration.Note
The procedure assumes that the device is made known (in some way) to the client.
Using the specified device ID and device registration data, such as keys, the client issues a ZMQ request of type
DeviceRegister
to the IEC Service. The IEC Service receives the request and does the following:Registers with AM claiming to be node type
device
.Checks that the IEC Service has been registered with AM.
Authenticates the device with AM, with the specified device ID and node type
client
(the client attests for the device).
The client registers the device with AM using claims, with node type
device
and the following data:The specified device ID
Registration data
Registration key
The client returns with an outcome.
The IEC Service responds with a success ZMQ message.
The device is registered.
[2] If the value provided contains a colon character (:), it must be a valid URI. For more information, see StringOrURI in the JSON Web Token specification.
Chapter 4. Getting and Changing Device Configuration
Once a device is registered with AM, the client application can request configuration for the device from AM, by specifying the device ID.
In this example, the user provides device configuration to AM in JSON format through the Edge Identity Manager. By default, configuration is set at the IEC level and applied to all clients and devices registered with that IEC. Device configuration is not returned if it's added to the device or client profile.
To change this default behavior, edit the GetDeviceConfig
script (Edge Device Configuration Command Handler) in the AM console.
Note
In the current implementation, IEC and SDK configuration are only requested when their respective processes are restarted.
To get the configuration for a device:
Your client application must include the
libiecclient.h
library and a call toiec_device_configuration()
, with thedeviceId
parameter.See the sample client application get_device_configuration.c.
The sample application includes "Initializing a Client Dynamically" and "Registering a Device".
If you are working in the training environment, the sample application is already present in
~/forgerock/examples/get_device_configuration
.If you are not working in the training environment, create a new directory in the
~/forgerock/examples
directory, with the same name as your client application and place the C application in that directory.For example, copy get_device_configuration.c into a new directory named
get_device_configuration
:mkdir ~/forgerock/examples/get_device_configuration cp get_device_configuration.c ~/forgerock/examples/get_device_configuration
Set the
deviceId
. In the example, thedeviceId
isIbex
.Make sure that the build script is executable, then run the script to set the build variables and build the application:
~/forgerock/build-examples.sh
The build script creates the application
get_device_configuration
in the~/forgerock/examples/get_device_configuration
directory:ls examples/get_device_configuration/ get_device_configuration get_device_configuration.c
Run the example application:
cd ~/forgerock/examples/get_device_configuration ./get_device_configuration
*** Registering a device *** SDK function(s): iec_initialise, iec_device_register, iec_device_configuration, iec_json_* Setting dynamic attributes... Done Initialising sdk... Done Registering device (id: Ibex)... Done Requesting configuration for device (id: Ibex)... Done Parsing configuration: { }... Done Extract the "minimum" value from the configuration...Not set
If the initialization and registration were successful, you should see the
get-config-client
andIbex
device identities in the Edge Identity Manager Console.Initially there is no device configuration so the sample client returns an empty JSON object as the value of
Parsing configuration: { }
.In the Edge Identity Manager console, Set the Device Configuration under the IEC profile, in JSON format, for example:
{ "display": "mountain goat", "minimum": 123 }
The sample application returns the value of the
minimum
property, if set.Run the example application again:
./get_device_configuration
*** Registering a device *** SDK function(s): iec_initialise, iec_device_register, iec_device_configuration, iec_json_* Setting dynamic attributes... Done Initialising sdk... Done Registering device (id: Ibex)... Done Requesting configuration for device (id: Ibex)... Done Parsing configuration: { "display": "mountain goat", "minimum": 123 }... Done Extract the "minimum" value from the configuration...123
Notice that the configuration that you entered in the Edge Identity Manager console is now returned by the client.
In a real application, the client would place this configuration in the specified memory area on the device.
4.1. Understanding the Device Configuration Process
Obtaining device configuration occurs as follows:
The client initiates a request to obtain the device configuration into the specified memory area, using the
iec_device_configuration()
library call with the parameterdeviceID
.The client issues a ZMQ request of type
DeviceCommand
to the IEC Service, specifying thedeviceID
and theGET_CONFIG
command.The IEC Service receives the request and does the following:
Verifies that the IEC has been registered with AM.
Authenticates the device with AM.
With the specified
deviceID
and node typeclient
(the client attests for the device), the service receives an SSO access token from AM.Obtains the command URL from the trust layer.
Encrypts the request.
Sends the
GET_CONFIG
request to AM, using the SSO access token.The service sends this request with the
deviceID
and no other parameters.The AM plugin runs the
Edge Device Configuration Command Handler
script and returns the device configuration for thisdeviceID
.The IEC Service responds with a ZMQ message that contains the device configuration from AM.
The device configuration is placed in the specified memory area.
Note
The device configuration can be used to provide MQTT connection information to the device, such as hostname, quality of service, publish\subscription topics, and so on.
Chapter 5. Getting OAuth2 Tokens For a Device
A client application developed with the IEC SDK can request OAuth2 bearer tokens (access token and ID token) from AM for a specific device ID.
To request an OAuth2 token:
Your client application must include the
libiecclient.h
library and a call toiec_device_tokens()
, with thedeviceId
parameter.See the sample client application get_device_tokens.c.
The sample application includes "Initializing a Client Dynamically" and "Registering a Device".
If you are working in the training environment, the sample application is already present in
~/forgerock/examples/get_device_tokens
. If you are not working in the training environment, create a new directory in the~/forgerock/examples
directory, with the same name as your client application and place the C application in that directory.For example, copy get_device_tokens.c into a new directory named
get_device_tokens
:mkdir ~/forgerock/examples/get_device_tokens cp get_device_tokens.c ~/forgerock/examples/get_device_tokens
Set the device ID and any custom registration data. In the example, the device ID is
Rhino
.Make sure that the build script is executable, then run the script to set the build variables and build the application:
~/forgerock/build-examples.sh
The build script creates the application
get_device_tokens
in the~/forgerock/examples/get_device_tokens
directory:ls examples/get_device_tokens/ get_device_tokens get_device_tokens.c
Run the example application:
cd ~/forgerock/examples/get_device_tokens ./get_device_tokens
*** Getting OAuth 2.0 access and ID tokens for a device *** SDK function(s): iec_initialise, iec_device_register, iec_device_tokens, iec_json_* Setting dynamic attributes... Done Initialising sdk... Done Registering device (id: Rhino)... Done Requesting OAuth 2.0 ID token for device (id: Rhino)... Done Extracting access and id tokens... access token: 8-Nfp1wH_ws41Cmgut_aImRXBsQ id token: eyJ0eXAiOiJKV1QiLCJraWQiOiJ3VTNpZklJYUxPVUFSZVJCL0ZHNmVNMVAxUU...H4GrQ
If the initialization and registration were successful, you should see the
get-device-tokens-client
andRhino
device identities in the Edge Identity Manager Console.The client returns the access and id tokens for the device. In a real application, the client would place these tokens in the specified memory area on the device.
5.1. Understanding the Device Token Process
The flow for obtaining device tokens is as follows:
The client initiates the process with the
iec_device_tokens
library call and thedeviceID
parameter.Using the specified device ID, the client issues a ZMQ request of type
DeviceCommand
to the IEC Service, with the specific commandGET_TOKENS
.The IEC Service receives the request and follows the standard
DeviceCommand
behavior:Verifies that the IEC has been registered with AM.
Authenticates the device with AM.
With the specified
deviceID
and node typeclient
(the client attests for the device), the service receives an SSO access token from AM.Obtains the command URL from the trust layer.
Encrypts the request.
Sends the
GET_CONFIG
request to AM, using the SSO access token.The service sends this request with the
deviceID
and no other parameters.The AM plugin runs the
Edge Device Tokens Command Handler
script and returns the device tokens for thisdeviceID
.
The IEC Service responds with a ZMQ message that contains the device tokens from AM.
The device tokens are placed in the specified memory area.
Chapter 6. Pairing a Device With a User
A registered device can be paired with another identity in AM, usually a human (user) identity but potentially any other device identity. The user must exist in the same realm as the device and must be able to authenticate outside of the IEC authentication flow.
The device first obtains a code and a verification URL. The user manually verifies the code, at the specified URL. The device then obtains the user tokens that authorize it to access the specified user resources. For a more detailed explanation of the process, see "Understanding User/Device Pairing".
Before you start this example, create a user identity in AM in the edge
realm. In the AM console (in the edge
realm) select Identities > New Identity and enter the User ID, Password and Email address of a sample user. In this example, we assume a user with User ID bjensen
. You don't need to complete any additional information for the user.
Also make sure that you have configured the OAuth2 Verification URL, as described in "Configuring AM for IoT" in the Installation Guide.
To pair the user with a device:
Your client application must include the
libiecclient.h
library and calls toiec_user_code()
andiec_user_tokens()
with thedeviceId
parameter.See the sample client application get_user_tokens.c.
The sample application includes "Initializing a Client Dynamically" and "Registering a Device".
If you are working in the training environment, the sample application is already present in
~/forgerock/examples/get_user_tokens
.If you are not working in the training environment, create a new directory in the
~/forgerock/examples
directory, with the same name as your client application and place the C application in that directory.For example, copy get_user_tokens.c into a new directory named
get_user_tokens
:mkdir ~/forgerock/examples/get_user_tokens cp get_user_tokens.c ~/forgerock/examples/get_user_tokens
Set the
deviceId
. In the example, thedeviceId
isSpringbok
.Make sure that the build script is executable, then run the script to set the build variables and build the application:
~/forgerock/build-examples.sh
The build script creates the application
get_user_tokens
in the~/forgerock/examples/get_user_tokens
directory:ls examples/get_user_tokens/ get_user_tokens get_user_tokens.c
Run the example application:
cd ~/forgerock/examples/get_user_tokens ./get_user_tokens
*** Getting OAuth 2.0 user tokens via device flow *** SDK function(s): iec_initialise, iec_device_register, iec_user_code, iec_user_tokens, iec_json_* Setting dynamic attributes... Done Initialising sdk... Done Registering device (id: Springbok)... Done Requesting a user code for device (id: Springbok)... Done Please instruct the user to visit: http://am.iec.com:8080/openam/oauth2/realms/root/realms/edge/device/user?nonce=0 and enter user code: XDQm3PXK Requesting user tokens for device (id: Springbok)...
The client outputs an instruction to the user to visit the Verification URL with the specified code. The Verification URL corresponds to the URL that is set in the OAuth2 Provider service in AM. In the training environment, this URL is
http://am.iec.com:8080/openam/oauth2/realms/root/realms/edge/device/user?nonce=0
.Navigate to that URL and enter the code returned by the client (
XDQm3PXK
in this example).Important
If you have the AM console open, use a private browser session to test this step, otherwise the AM takes the credentials of the existing logged in user.
Log in to AM as the sample user you created at the beginning of this procedure (
bjensen
).AM returns a message indicating that the specified device (
springbok
) is requesting access to your account. Select Allow.The client returns the user tokens in the output:
Requesting user tokens for device (id: Springbok)... Done: { "access_token": "rwZDFemw-xK2hRvkcG1bJusACuU", "id_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiJ3VTNpZklJYUxPVUFSZVJCL0...", "token_type": "Bearer", "expires_in": 3599 }
In a real application, the client would place these tokens in the specified memory area on the device, authorizing the device to access the specified user resources.
6.1. Understanding User/Device Pairing
The process of pairing a user and a device is similar to that described in "Understanding the Device Token Process".
The client initiates a request to obtain a user code, using the
iec_user_code()
library call with thedeviceID
parameter.Using the specified device ID, the client issues a ZMQ request of type
DeviceCommand
to the IEC Service, with the commandGET_USER_CODE
.The IEC Service receives the request and follows the standard
DeviceCommand
behavior:Verifies that the IEC has been registered with AM.
Authenticates the device with AM.
With the specified
deviceID
and node typeclient
(the client attests for the device), the service receives an SSO access token from AM.Obtains the command URL from the trust layer.
Encrypts the request.
Sends the
GET_USER_CODE
request to AM, using the SSO access token.The service sends this request with the
deviceID
and no other parameters.The AM plugin runs the
Edge User Code Command Handler
script and returns the user code and Verification URL.
The IEC Service responds with a ZMQ message that contains the user code and Verification URL from AM.
These details are passed to the user, who authenticates and validates the user code.
AM now regards the device and user as paired and constructs the access tokens for the device.
The IEC service sends the
GET_USER_TOKENS
request to AM with theEdge User Tokens Command Handler
script.The process is similar to "Understanding the Device Token Process" and enables the the device to obtain the access tokens from AM. These tokens authorize the device to access the specified user resources.
Chapter 7. Running Custom Commands on a Device
If your deployment requires functionality not covered by the features described previously, your client application can use the IEC Command Handler to run custom commands on devices through AM. Running a custom command involves the following:
Writing an IEC Command Handler script in Groovy.
Mapping that script to a command key in the IEC Service
Calling the command with the
iec_device_custom_command
library call.
Before you start this example, write a custom IEC Command Handler script and map it to a command key in IEC. The following procedure sets up a Hello World
script:
In the AM console, in the
edge
realm, select Scripts > New Script.Set the script Name to
Hello World
and the Script Type toIEC Command Handler
then select Create.In the Script field, paste the following Groovy script:
import groovy.json.JsonOutput import groovy.json.JsonSlurper logger.info("Running custom command handler script") // Pre-defined variables passed to the script def jsonSlurper = new JsonSlurper() def reqJson = jsonSlurper.parseText(request) if (reqJson.command == "HELLO_WORLD") { response = JsonOutput.toJson([response: 'Hello World from an AM Command Script']) } else { def errorMessage = "Unexpected '${reqJson.command}' command" logger.error(errorMessage) response = JsonOutput.toJson([response: 'error', message: errorMessage]) }
Select Validate to check the script syntax, then select Save Changes.
Copy the script ID from banner at the top of the page (for example
Scripts > 20d894e8-a645-4128-a5d1-e561c249db9a
).Select Services > IEC Service.
Under Command Script Mapping, enter
HELLO_WORLD
as the Key and the script ID (20d894e8-a645-4128-a5d1-e561c249db9a
) as the Value.Select Add and Save Changes.
Your client application must include the
libiecclient.h
library and a call toiec_device_custom_command()
with thedeviceId
and the command key (HELLO_WORLD
) as parameters.See the sample client application run_device_custom_command.c.
The sample application includes "Initializing a Client Dynamically" and "Registering a Device".
If you are working in the training environment, the sample application is already present in
~/forgerock/examples/run_device_custom_command
.If you are not working in the training environment, create a new directory in the
~/forgerock/examples
directory, with the same name as your client application and place the C application in that directory.For example, copy run_device_custom_command.c into a new directory named
run_device_custom_command
:mkdir ~/forgerock/examples/run_device_custom_command cp run_device_custom_command.c ~/forgerock/examples/run_device_custom_command
Set the
deviceId
. In the example, thedeviceId
isYak
.Make sure that the build script is executable, then run the script to set the build variables and build the application:
~/forgerock/build-examples.sh
The build script creates the application
run_device_custom_command
in the~/forgerock/examples/run_device_custom_command
directory:ls examples/run_device_custom_command/ run_device_custom_command run_device_custom_command.c
Run the example application:
cd ~/forgerock/examples/run_device_custom_command ./run_device_custom_command
*** Running a device custom command *** SDK function(s): iec_initialise, iec_device_register, iec_device_custom_command, iec_json_* Setting dynamic attributes... Done Initialising sdk... Done Registering device (id: Yak)... Done Executing 'Hello World' custom command... Done Received response: Hello World from an AM Command Script
The client outputs the Hello World text.
7.1. Understanding Custom Commands
Custom commands work in a similar way to the process described in "Understanding the Device Configuration Process".
The client initiates a request to run a custom command, using the
iec_device_custom_command()
library call with thedeviceID
parameter, and the custom command key. The key is mapped to the custom Groovy script that you supply in the AM console.Using the specified device ID, the client issues a ZMQ request of type
DeviceCommand
to the IEC Service, with the custom command key.The IEC Service receives the request and follows the standard
DeviceCommand
behavior:Verifies that the IEC has been registered with AM.
Authenticates the device with AM.
With the specified
deviceID
and node typeclient
(the client attests for the device), the service receives an SSO access token from AM.Obtains the command URL from the trust layer.
Encrypts the request.
Sends the custom command key request to AM, using the SSO access token.
The service sends this request with the
deviceID
, custom command and command parameters.The AM plugin runs the script associated with the custom key and returns a JSON payload.
The IEC Service responds with a ZMQ message that contains the return output from AM.
IEC Glossary
- Access Management (AM)
ForgeRock software (part of the ForgeRock Identity Platform) that provides access and identity management.
- client
An edge node type representing a client application that uses the IEC SDK.
- constrained device
A device that does not have the ability to connect securely across wide-area networks, due to cost and/or physical constraints. See RFC 7228.
- device
An edge node type representing a physical device that can be onboarded via a client node.
- Directory Services (DS)
ForgeRock software that is part of the ForgeRock Identity Platform and provides storage for identities and configuration.
- edge
Industry term for the geographic distribution of IoT devices. Edge computing enables a connected device to process data closer to where it is created (on the edge).
- edge gateway
Hardware and software deployed at the edge, through which devices communicate.
- Edge Identity Manager
ForgeRock software that provides a User Interface to AM for viewing and managing device identities.
- edge node
A physical or virtual object that exists at the edge and benefits from having an identity. Examples of edge nodes include a device, the IEC Service or a client application.
- Identity Edge Controller (IEC)
ForgeRock software consisting of multiple components that securely provide devices with identity.
- IEC AM Plugin
ForgeRock software plugin that adds IoT specific functionality to AM.
- IEC SDK
ForgeRock client library that provides an API for client applications to invoke AM functionality via the IEC Service.
- IEC Service
ForgeRock software that runs on the edge gateway and provides secure communication between client applications and AM.
- IEC Utility
ForgeRock software used when installing the IEC Service or IEC SDK to configure the components.
- OP-TEE
Open source implementation of the GlobalPlatform Trusted Execution Environment (TEE) specification.
- Rich Execution Environment (REE)
GlobalPlatform term for the environment in which the user-facing operating system runs.
- Rich OS
Operating system running in the Rich Execution Environment (REE), typically Linux.
- Trusted Application (TA)
An application that can run in the Trusted Execution Environment (TEE).
- Trusted Execution Environment (TEE)
GlobalPlatform term for a secure area of the main processor of a device that ensures data is stored and processed in an isolated and trusted environment.