Cloud components
Identity Provider
End-user identity service provider(IdP) is external to Cloud. For the reference implementation, cloud uses AWS Cognito as the identify provider.
However, any external OpenID connect OAuth 2.0 compliant identity provider can easily be integrated with the Cloud. For additional details, please refer to OAuth 2.0 Authorization Code Flow in the specification https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.
Deploy AWS Cognito as the default IdP or integrate with your own OpenID connect compliant IdP.
Reference Cloud components
The reference Cloud consists of multiple microservices running in a AWS cloud along with several AWS managed resources.
On successful installation of a full stack cloud, user should see the following cloud components/micro services up and running.
Cloud Gateway Server
Authorizer
Cloud Proxy Server
Device Proxy
Client Rest-API
TCPMux Server
Provisioning Server
Device Gateway
Notification Handler
AWS managed cloud resources:
Cloud database - RDS
Elastic Cache/Redis
AWS Private CA
AWS Secret Manager
AWS SNS
In-case if the ODM/OEM operator chooses to integrate and use their own IDP and security layer, following Cloud components/micro services will be installed and used to connect with device.
Cloud Proxy server
Device Proxy
TCPMux Server
AWS managed cloud resources
Cloud database
Below is the high level summary of various cloud components and its usage.
Cloud Gateway
In a full stack deployment, gateway acts as an entry point for Cloud users to access cloud bound APIs.
Before connecting to the gateway, user first authenticates himself/herself through the integrated IDP. For every request to the gateway, user needs to provide IDP issued JWT security token in the API request authorization header field. Requests will be rejected if the authorization token is missing, expired, or in a wrong format.
Gateway forwards all cloud bound requests to the Client Rest API service for further processing and provide response to user. Users may also query gateway for a JWT token that captures user authorization info, which can be used to invoke device bound APIs at proxy.
Cloud Proxy
Proxy service provides an interface to communicate with the device via the TCPmux server. It provides two groups of service:
tcpmux-server facing: API to post/delete device connection, get device, register device
Client- device facing: API to proxy requests to device via TCPmux
To access the device APIs via Proxy, user needs to present the valid JWT token issued by Cloud Authorizer microservice.
Device Proxy
Device proxy provides an interface to communicate with the device via the TCPmux server. It provides two groups of service:
tcpmux-server facing: API to post/delete device connection, get device, register device
Client- device facing: API to proxy requests to device via TCPmux
Client Rest-API
Client Rest-API service provides implementation for REST APIs more focused on Cloud. User profile management, device profile management, User-device mapping, User-device claim are some of the capabilities supported by Client Rest-API service.
Once the IDP issued JWT token is verified, gateway reaches out to Client Rest API microservice. Client Rest API service, serves the user request with the help of user and device profiles info stored in the Cloud db. If the user info is not found in the cloud db (first time user), it creates a profile for the user in the cloud db.
TCPMux Server
TCPMux server is the proxy for Cloud to device communication. On the device start-up, TCPMux client/IoT gateway agent running on the device establishes a persistent TCP connection with TCPMux server running on the Cloud. TCPMux connection can establish even when the device is behind the firewall. TCPMux automatically reestablishes the connection in case if connection gets terminated for some reason. TCPMux server will only authenticate devices with TLS certificates signed by a valid Certificate Authority, and vice versa. Data transfer between the device and the TCPMux server on the Cloud is encrypted. Cloud and the device will use this persistent TCP connection to securely interact.
Provisioning server - Admin
This is a cloud service component which is used by the admin to request OTP (one time passcode) that will be used by devices to request certificate. The service exposes only one endpoint(/admin/api/otp). The admin will need to provide an API KEY when calling this endpoint. The Admin API Key is generated during cloud deployment and can be viewed in the AWS secret manager (admin-api-key-prov-server-admin-api). Once the OTP is generated, it can be used on the device to request a certificate. We recommended to restrict this endpoint to only accept request from your Organization. Use security group for that. Sample API call to request a OPT:
curl -H 'Authorization: PROV-ADMIN put-your-admin-api-key' https://cloud-gateway.your-domain.com/api/otp && echo.
Provisioning server - Agent
This is a cloud service component in charge of issuing end-entity certificate to devices. It also provides API to download CACerts. All requests to issue certificate must be authenticated using previously downloaded OTP. Requests to get CaCerts are unauthenticated. The device will call this service to request a certificate.
Device Gateway
The Device Gateway services enables Jetson devices making REST API calls to reference cloud . It facilitates a secure and efficient exchange of data by providing several critical gateway functionalities, It acts as an intermediary to forward requests from devices to appropriate cloud services, enhancing security and enabling more efficient network configurations. Device gateway also Incorporates robust security measures to ensure that all device communications are authenticated and authorized before access to cloud resources is granted.
Notification Handler
The Notification Handler orchestrates the delivery of notifications from Jetson devices to client applications such as mobile apps. This service Gathers device-generated notifications and event data in real time. Processes and formats notifications according to the target client platform requirements. Delivers notifications through configured channels like AWS push notification service integrated with Firebase cloud messaging. Though reference implementation used GCP-FCM, Notification Handler service if flexible and with little effort can be integrated with any push notification service based on the client device ecosystem.
Cloud database
Cloud maintains a database to store the following details:
User profile
Details of managed devices
User - device permissions
Device - cloud connection status
Device ownership and claim info
Elastic Cache/Redis instance
Cloud uses a single node AWS elastic cache/Redis instance to track the device connection events and eventually performs async device provisioning. On a new device connection to the TCPMux server in the cloud, Proxy tracks the connection publishes the device connection event to Redis. Client REST API service consumes the device connection event from Redis. On a device connection event, Client REST API service computes the unique device claim code and pushes the same to the device with the help of TCPmux server.
AWS Private CA
AWS Private CA, where CA stands for Certificate Authority, is a service provided by Amazon Web Services. It’s part of the AWS Certificate Manager (ACM) and allows you to easily and securely manage the lifecycle of your own private certificates. AWS Private CA is used to securely store the CA certificates and use them for signing individual device certificate on request.
AWS Secret Manager
Reference cloud deployment makes use of AWS secret manager service to securely store, rotate, manage, and retrieve database credentials, API keys, certificates, and other application secrets. Cloud applications retrieve secrets with a call to Secrets Manager APIs, eliminating the need to hardcode sensitive information in plaintext. AWS Secret Manager service is also designed to be highly available and durable, automatically replicated across multiple Availability Zones.