AWS Partner Network (APN) Blog

Onboarding and Managing Agents in a SaaS Solution – Using AWS IoT Core

Editor’s note: This is the second in a two-part series about managing agents in a SaaS solution. Read Part 1 >>

By Oren Reuveni, Sr. Partner Solutions Architect – AWS SaaS Factory

Cloud Anything-9In a previous post, I discussed the concept of managing agents in a SaaS environment throughout their lifecycle. Here, I will use a specific solution to demonstrate an implementation of this concept.

The solution is based on AWS IoT Core, which I chose because it facilitates and offloads a significant amount of the processes and abilities that are needed to manage agents.

A managed cloud service, AWS IoT Core lets connected Things easily and securely interact with cloud applications. A Thing is a representation of a specific device or logical entity. It can be a physical device or sensor (for example, a light bulb or a switch on a wall), a logical entity like an instance of an application, or agents in our case.

AWS IoT Core facilitates the registration of new Things and helps manage them throughout their lifecycle, allowing the SaaS provider to focus on their core business instead of implementing an agent management system.

AWS IoT can support billions of devices and trillions of messages, and can process and route those messages to Amazon Web Services (AWS) endpoints and other devices reliably and securely.

Advantages of This Solution

A SaaS solution based on AWS IoT Core enables you to manage agents throughout their lifecycle. This service manages agent onboarding and communication, monitors its ongoing activity, handles version updates and configurations, and more.

AWS IoT Core provides a data ingestion flow for the agents that also handles authentication and authorization. It also provides a managed, scalable endpoint for agent communication. This allows us to couple an agent to its tenant context in terms of identity and permissions, and use this identity-based processing and isolation ability to securely route agent data to their specific tenant datastore.

Since AWS IoT Core keeps a Thing registry, we can analyze a multi-tenant agent fleet using various queries in a cross tenant, yet secured manner. This way we get valuable insights and visibility, and are able to group and act on agents meeting a particular query.

AWS IoT Core allows a more agile experience of building your solution by providing seamless integration with AWS services. These services include AWS Lambda, data and analytics services such as Amazon Simple Storage Service (Amazon S3), Amazon DynamoDB, Amazon OpenSearch Service (successor to Amazon Elasticsearch Service), Amazon Kinesis, and machine learning (ML) services such as Amazon SageMaker.

Since most of the logic runs on the server side, AWS IoT Core gives the SaaS provider a lot of flexibility and the ability to execute changes without the need to update the edge.

Consider using this solution if you intend to manage a fleet of dozens of agents or more, and require functionality such as agent profile management, data processing and routing, and agent configuration changes.

You can achieve even more using AWS IoT services. Analytics, security-related features, and various insights are just a some of the abilities AWS IoT can offer. I’ll include a few examples of using those features in this post.

Registering Agents

The first step in working with agents is the registration process. Key challenges of registration is ensuring a secure way to both register a tenant’s agent, and that the inbound interactions from that agent have the appropriate credentials and tenant scope.


First, you need to deploy the agent’s binary needs in the target environment. An agent can take several forms. It can be a code library or a binary deployed in a server. It can be packaged as a Lambda function, a container, or as a server image like an Amazon Machine Image (AMI).

After you deploy the agent, you need to give it registration information and the ability to authenticate against the SaaS environment. You can generate this information by using the credentials of a trusted user—a registered SaaS application user that’s known and authenticated in the system.

You can do this interactively through the user interface (UI) or programmatically through an application programming interface (API), command line interface (CLI), or software developer kit (SDK). The information is packaged as a token that’s fed into the registration process in the remote environment.

The token has three parts:

  1. Temporary AWS credentials with specific permissions that are generated by AWS Simple Token Service (AWS STS). The agent uses these temporary credentials to authenticate. The AWS STS credentials also provide the permission for interacting with specific components within the SaaS environment.
    You can choose the time-to-live (TTL) of the credentials when generating them. We recommend keeping to the minimum value of 900 seconds. Note than an alternative to using STS credentials is the AWS IoT temporary provisioning claim.
  2. Data payload, which contains important properties for registering the agent. The example below includes Agent ID, Tenant ID, and the endpoint to contact the registration process. You can sign and encrypt the token prior to sending the request.
    Here’s an example of a possible format for a token:
{"registration_token_example": {
    "version": "v2.1",
    "timestamp": "VALUE",
    "temp_aws_credentials": {
        "access_key": "ACCESS_KEY_VALUE",
        "secret_key": "SECRET_KEY_VALUE",
        "session_token": "SESSION_TOKEN_VALUE"
    "registration_data": {
        "agent_id": "5he9f03h6btmjp07gjes",
        "tenant_id": "69c5ygydn2",
        "api_endpoint_to_contact": "",
        "path": "/register",
        "region": "eu-west-1"
  1. The third and last component required for the registration is a Certificate Signing Request (CSR). The agent generates a local certificate, along with a CSR. This will be signed in the next stage of the process and allows the agent to register with AWS IoT Core.
    The agent can use the agent_id and tenant_id parameters from the token in the certificate subject field, which are later extracted from the certificate and used as Thing parameters in AWS IoT registry.
    The agent sends the CSR as part of the HTTP request to the API endpoint, so AWS IoT will be able to sign the request. I will elaborate about the registration with AWS IoT in the following section.

The Registration Process

Now, you can start the registration process itself. To initiate it, the agent uses the token and the CSR. This usually happens as part of an automated process for registering single or multiple agents, but can be also executed manually.


Figure 1 — Agent registration process.

The agent sends a secured HTTP request to the SaaS environment API endpoint. This endpoint is managed by Amazon API Gateway, and uses the identity and access management (IAM) authentication feature. The agent uses the temporary AWS STS credentials to authenticate its request against the API endpoint.

In addition to authentication, these credentials authorize the agent to run under specific, limited permissions within the AWS environment.

After the authentication phase completes, the agent’s request that contains the registration data and the CSR is processed (using Lambda) to register it with the SaaS provider’s Certificate Authority (CA).

This step is needed because in this solution, we’re using the Just in Time Provisioning (JITP) feature where you register a CA with AWS IoT Core. This allows you to sign on IoT Things (or agents in our case) certificates using this CA, and then have them provisioned when they first authenticate against AWS IoT Core with the signed certificate.

You can log into the system the agent ID and tenant ID values from the token as a part of this registration event.

After the CSR is signed, it’s passed back to the agent (also in a secured manner). This process allows you to establish secure communication between the agent and SaaS environment. The CA that signs the agent’s CSR is generated by the SaaS provider prior to the registration process, and stored in the SaaS environment.

For a detailed description of JITP, please refer to:

In addition to the certificate, the response can contain relevant application configuration data and tenant-specific data (like user defined scripts or other configuration parameters) that are required for the agent’s onboarding process.

As an alternative, the response can contain a temporary Amazon S3 pre-signed URL that is the link for this data. This alternative also allows sending bigger amounts of data to the agent. For example, it can point to new file versions for the agent to fetch.

At this point, the agent is registered and has the ability communicate with the SaaS environment and vice versa. The communication is done through an AWS IoT Core API endpoint.


Figure 2 — Ongoing communication between the agent and AWS IoT Core.

How AWS IoT Core Manages Agents in a SaaS Solution

AWS IoT core keeps the inventory of the agents and their metadata, and manages them by using multiple abilities. An active AWS IoT agent can be used to run jobs, send data to the SaaS environment, and communicate with it using AWS IoT SDK.

Let’s look at some examples for managing agents using this service.

Example: SaaS Solution Onboarding

When an agent first contacts AWS IoT Core (as part of the JITP flow described in the previous section), a new Thing is created to represent the agent in the system. It’s created using a provisioning template that can use the data in the agent’s generated certificate subject field as registration parameters.

The service can then onboard and configure the new agent by, for example, updating it with additional Thing attributes that are relevant to the agent—for example tier, current version, and registration date—and adding it to thing groups and billing groups. You can use those parameters for later analysis, metering and billing purposes, and more.

Each agent has its own certificate, and a policy is also defined for the new Thing. IoT policies define the operations a device can perform in AWS IoT and are attached to device certificates. When a device presents the certificate to AWS IoT, it’s granted the permissions specified in the policy.

For more information about certificates and policies, see AWS IoT Authentication and AWS IoT Core policies.


Figure 3 — A registered agent in the AWS IoT Core service console.

Example: Sending Metrics Using AWS IoT in a Multi-Tenant Environment

AWS IoT Core allows you to easily publish metrics and other telemetry data to your SaaS environment through IoT topics. AWS IoT then uses a set of rules to process this communication.

Following is an example rule that stores messages sent to the tenant-1532/logs topic into a prefix by the same name (tenant-1532/logs/) in the specified Amazon S3 bucket. The SQL statement filters the messages, and the role ARN grants AWS IoT permission to write to the S3 bucket.

    "topicRulePayload": {
        "sql": "SELECT * FROM 'tenant-1532/logs'",
        "ruleDisabled": false,
        "awsIotSqlVersion": "2016-03-23",
        "actions": [
                "s3": {
                    "bucketName": "my-bucket",
                    "cannedacl": "public-read",
                    "key": "${topic()}/${timestamp()}",
                    "roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3"

To learn more about this topic, please refer to:

Example: Fleet Indexing Service – Visibility, Metering, and Billing

Fleet indexing allows you to easily search, group, and act on agents meeting a particular query. Here’s an example of querying for v2 agents that belong to tenant 1532.


Figure 4 – Querying agent data using Fleet indexing.

Additional Mentions

AWS IoT Greengrass seamlessly extends AWS to edge devices so they can act locally on the data they generate, while still using the cloud for management, analytics, and durable storage. It acts as an on-premises agent hub, and lets you run some of your solution’s logic on the edge. This allows you to implement offline operation for certain features and enables reduced data transfer while being managed using AWS.

AWS IoT Analytics is a fully-managed service that makes it easy to run and operationalize sophisticated analytics on massive volumes of IoT data, without having to worry about the cost and complexity typically required to build an IoT analytics platform.

AWS IoT Defender helps you secure your fleet of IoT devices. It continuously audits your IoT configurations to make sure they aren’t deviating from security best practices.

AWS IoT has more features and abilities that I did not mention in this post. To learn more, please visit the AWS IoT page.


You can manage agents in a multi-tenant SaaS environment using AWS IoT Core.

The solution we reviewed in this post offers a modular and secure approach to register and manage agents. It relies on AWS managed services to offload the heavy lifting of implementing and maintaining those mechanisms, and provides scalability, elasticity, and availability. This allows SaaS providers to focus on their core business.

AWS IoT Core meets multiple needs that are specific for SaaS environments, such as tenant isolation, assimilating identity into tenant activity, and tenant level visibility.

Changing and updating this solution to add more capabilities due to new product requirements and features is easy because of its modular approach, and because most of the solution’s logic, including the agent onboarding phase, is located on the server side.

Using AWS IoT Core for agent management provides various capabilities for managing, securing, and analyzing usage and sent data from the registered agents.


About AWS SaaS Factory

AWS SaaS Factory helps organizations at any stage of the SaaS journey. Whether looking to build new products, migrate existing applications, or optimize SaaS solutions on AWS, we can help. Visit the AWS SaaS Factory Insights Hub to discover more technical and business content and best practices.

SaaS builders are encouraged to reach out to their account representative to inquire about engagement models and to work with the AWS SaaS Factory team.

Sign up to stay informed about the latest SaaS on AWS news, resources, and events.