Skip to main content
Version: v1.1

Identity and Access Manager (IAM)

Introduction​

The Identity and Access Manager (IAM) is the security backbone of every AosEdge Node. It manages the complete certificate lifecycle, establishes and maintains Node identity, handles initial provisioning and enrollment, and controls access permissions for service instances.

Every other AosCore component depends on IAM for its TLS credentials. The Communication Manager (CM) and Service Manager (SM) both obtain their certificates from the local IAM instance, making IAM the trust anchor for all inter-component and cloud communication.

IAM runs as the aos_iamanager process on every Node in a Unit — both Main Nodes and Secondary Nodes.

Responsibilities​

IAM provides the following core capabilities:

CapabilityDescription
Certificate lifecycle managementCreates key pairs, generates CSRs, applies signed certificates, tracks expiration, and supports renewal
Node identityEstablishes and reports the Node's identity — Node ID, Node type, hardware capabilities, and system information
Provisioning and enrollmentManages the initial setup sequence that establishes a Node's cryptographic identity and registers it with the system
Access control and permissionsRegisters service instance permissions and validates access tokens for functional servers
PKCS#11 integrationInterfaces with hardware security modules (HSMs) through the PKCS#11 standard for secure key storage
gRPC serverExposes public and protected APIs that other components use to obtain credentials and manage identity

Architecture​

IAM is structured as a set of cooperating subcomponents, each handling a specific aspect of identity and security management:

aos_iamanager
├── iamserver          # gRPC server (public + protected APIs)
│   ├── publicmessagehandler     # Handles public service requests
│   ├── protectedmessagehandler  # Handles protected service requests
│   └── nodecontroller           # Manages registered Node streams
├── identhandler       # System identification (pluggable modules)
│   └── visidentifier            # VIS-based identifier plugin
├── iamclient          # Client for IAM-to-IAM communication (multi-Node)
├── currentnode        # Current Node information provider
├── database           # SQLite storage (certificates, Node registrations)
└── config             # Configuration loading and validation

iamserver​

The IAM server is the primary interface point. It runs two separate gRPC servers:

  • Public server — accessible without mutual TLS authentication. Provides certificate retrieval, Node information, identity queries, and permission checks. Other components connect here to obtain their initial credentials.
  • Protected server — requires mutual TLS authentication. Provides provisioning operations (start/finish provisioning, deprovisioning), certificate management (key creation, certificate application), Node lifecycle control (pause/resume), and instance permission registration.

The server also includes a Node controller that manages bidirectional streaming connections from Secondary Node IAM instances. Through these streams, the Main Node IAM can forward provisioning and certificate operations to remote Nodes.

identhandler​

The identification handler establishes the Unit's system identity (system ID and unit model). It uses a pluggable module architecture:

  • VIS identifier — connects to a Vehicle Information Service (VIS) server via WebSocket to retrieve vehicle-specific identity information
  • File identifier — reads identity from local files (used in non-automotive deployments)

The identifier module also manages subjects — the set of identity claims associated with the Unit that can change at runtime.

iamclient​

On Secondary Nodes, the IAM client connects to the Main Node's IAM server using the RegisterNode bidirectional streaming RPC. Through this connection, the Main Node can remotely trigger provisioning, key creation, and certificate application on the Secondary Node.

The IAM client reports the local Node's information to the Main Node and processes incoming commands (provisioning requests, certificate operations, pause/resume).

currentnode​

The current Node handler collects and provides information about the local Node:

  • Node ID and Node type (from configuration)
  • CPU information (model, cores, threads, architecture, DMIPS)
  • Memory capacity
  • Disk partitions and their types
  • OS information
  • Custom Node attributes
  • Provisioning state (unprovisioned, provisioned)

This information is reported to other components and to the Main Node's IAM (via the IAM client) for Node registration.

database​

The IAM database is a local SQLite store (with schema migration support) that persists:

  • Certificate metadata — type, issuer, serial number, URLs, expiration for all managed certificates
  • Node registrations — information about Nodes registered with this IAM instance (on the Main Node)

config​

The configuration module loads and validates the IAM configuration file (aos_iamanager.cfg), which defines:

  • Node information (ID, type, name, hardware attributes, partitions)
  • Certificate module definitions (PKCS#11 library paths, slot configuration, key algorithms)
  • IAM server URLs (public and protected endpoints)
  • IAM client URLs (for connecting to the Main Node's IAM)
  • Database paths
  • Identifier plugin selection and parameters

gRPC API​

IAM exposes its functionality through gRPC services defined in the iamanager/v5 and iamanager/v6 proto packages. The current implementation uses API version 6.

Public Services​

ServicePurpose
IAMPublicCurrentNodeServiceGet current Node info, subscribe to Node changes
IAMPublicCertServiceRetrieve certificates by type/issuer/serial, subscribe to certificate changes
IAMPublicIdentityServiceGet system info (system ID, unit model), get and subscribe to subjects
IAMPublicPermissionsServiceValidate service instance permissions
IAMPublicNodesServiceList all Node IDs, get Node info, subscribe to Node changes, register Nodes (streaming)

Protected Services​

ServicePurpose
IAMNodesServicePause and resume Nodes
IAMProvisioningServiceGet cert types, start/finish provisioning, deprovision
IAMCertificateServiceCreate keys (returns CSR), apply signed certificates
IAMPermissionsServiceRegister/unregister service instance permissions

Operational Modes​

IAM supports two operational modes:

  • Normal mode — the standard runtime mode where IAM serves certificate requests, reports Node identity, and manages permissions
  • Provisioning mode — activated with the --provisioning flag, this mode enables initial certificate enrollment and Node setup operations that are restricted in normal mode

Multi-Node Behavior​

In a multi-Node Unit:

  • The Main Node IAM acts as the central authority — it runs the full IAM server (public + protected), manages Node registrations, and can forward operations to Secondary Nodes
  • Secondary Node IAMs run the IAM server locally (for local SM and MP certificate requests) and additionally run the IAM client to register with the Main Node's IAM

This architecture allows centralized provisioning management while keeping certificate operations local for performance and availability.

  • Node Identity — per-Node identity establishment and management