Guide to getting started quickly with ForgeRock® Identity Edge Controller software.

Preface

Use this guide to understand what Identity Edge Controller (IEC) software can do and how you can contribute to the IEC open source project.

Chapter 1. Overview of Identity Edge Controller Components

The ForgeRock Identity Edge Controller (IEC) includes multiple components working together to enable devices to register as identities in ForgeRock Access Management (AM).

When a device has registered, the IEC enables that device to do the following:

Obtain a configuration from AM
Request OAuth2 access and ID tokens
Be paired with a user, using the OAuth2 Device Flow
Call customisable scripts in AM

1.1. IEC Components

The IEC includes the following components:

IEC Service

The IEC Service runs on an edge gateway on the local network and provides secure communications between client applications and AM.

The ARM TrustZone enabled version of the IEC Service provides secure storage on edge gateways that support OP-TEE.

IEC AM Plugin

The IEC AM Plugin adds IoT-specific functionality to AM and provides a secure communication point for the IEC Service into AM. The plugin enables the IEC Service to perform tasks such as registering edge nodes and retrieving OAuth2 tokens.

Edge Identity Manager

The Edge Identity Manager is a basic User Interface to AM that enables you to view and manage edge node identities.

IEC SDK Client Library

The SDK client library provides a simple C API for client applications to invoke 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 following diagram shows the IEC components and where they are situated in an IoT system:

1.2. IEC Architecture

The IEC implements a hierarchy of nodes at the edge, typically, devices that run embedded software. Edge nodes are physical or virtual things that exist at the edge and benefit from having an identity. The nodes can range from constrained nodes that have tight limits on power, memory, and processing resources, to fully capable nodes that can connect securely across a wide-area network.

A node's type is stored with its identity and is used to make decisions about the node's functions and properties. In IEC, an edge node can be one of the following types:

IEC
The IEC edge node type represents an IEC Service and has a one to many relationship with CLIENT edge nodes.
CLIENT
The CLIENT edge node type represents a client application that uses the IEC SDK and has a one to many relationship with DEVICE edge nodes.
DEVICE
The DEVICE edge node type represents a physical device that can be onboarded through the IEC SDK.

The following diagram shows the IEC architecture and the different node types:

1.3. Using the IEC Training Environment

In addition to this documentation on Backstage, the IEC project includes 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 a number of sample applications, referenced in the Client Application Developers Guide.

Chapter 2. Contributing to the IEC Project

This chapter shows you how to get started contributing to the IEC project, where to find the IEC source code, and how to view and raise issues.

2.1. Contributing to the IEC Core

The IEC Core is an open source project that contains the source code and build instructions for the IEC edge components. The edge components include the following:

IEC Service
IEC SDK
IEC Utility

The IEC Core repository is publicly available to browse or clone. ForgeRock customers and partners can contribute to the project if they have a subscription agreement with ForgeRock.

For information about obtaining a subscription agreement, see this Knowledge Base article.

2.2. Finding and Logging Issues on IEC

The IEC core development is tracked at https://bugster.forgerock.org/jira/projects/OPENIEC/issues. You can browse the existing issues without logging in. If you have a customer or partner agreement with ForgeRock, you can log in to create new issues. Otherwise, contact the IoT team to create an issue on your behalf.

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.