Global ID Generator API service | Ability™ Developer Portal

# Overview

The Global Id Generator is a global service. This means that there is only a single instance of it which is exposed to every other ABB Ability™ Platform instance.

Note

The purpose of the Global Id Generator is to prevent the creation of duplicate device or object identities across the entire ABB Ability™ system.

Each device generates its own UUID and uses the Global Id Generator GET method to confirm that the UUID is not already registered in the platform.

If the generated UUID is unique, it is used in an enrollment process to the CA server in order to receive a device certificate (CommonName [CN] is the same as the UUID). This certificate is then used to authenticate the device, when the UUID is registered in the Global Id Generator utilizing the POST method on a specific endpoint. Each device is only authorized to register itself, meaning that the certificate's CN value has to be the same as the {id} parameter used in the POST call.

# Generating Device Unique Identity

To securely connect, collect data, and command and control connected devices using the Ability Platform, each device must be uniquely identifiable, whether it is directly or indirectly connected to the platform. This is done by assigning a 128-bit number which acts as a universally unique identifier (UUID) to each device or entity. UUIDs can be generated in several ways, however in order to maintain the uniqueness of devices across the platform, the Ability Platform offers a web service called the Global ID Generator. This tutorial reviews how to create and register Unique Identifiers for devices using the Ability GIG API and UUID4 generator.

See Device ID Management for more information regarding Ability Device ID Management.

# Generating UUIDs using the Ability Global Id Generator (GIG)

To get comfortable with all the operations exposed by the Ability GIG service, see this article.

Unlike most other Ability APIs, different GIG operations are authorized using different techniques, i.e. mutual TLS authentication is required to register an object ID inside the GIG database. A bearer token is used to authorize a request for object ID generation.

# Types of authorization

# Azure Active Directory App-based authorization

This type of authorization is intended for applications registered in the ABB Azure Active Directory (AAD). These applications are given a unique application Id and a client secret. With these credentials, an application may obtain a bearer token, which is used to authorize against the GIG Service.

# Certificate based

This type of authorization is intended only for IoT devices that connect to the Ability Platform. Every device obtains its certificate during the device provisioning process. Devices request the certificate with the CN set to the device Id obtained from the GIG service or the Id generated by the RFC 4122 compliant tool. The CA which signed the device certificate has already been added to the trust manager as a trusted authority with the Global ID Service. As a result, when the device reaches the GIG service with a device certificate issued by the CA, the GIG service is able to authorize the request originating from the device.

# Step 1.1: Register an AAD application

To create an Active Directory Application, see this link. Grab the Application or Client Id (see screenshot below) and save the Id for future reference, as you will need it to generate an access token to authorize against the GIG service.

Create AAD App

In addition to Azure AD, GIG service is also protected by Azure API Management (APIM) service. The APIM service is an API Firewall to protect Ability APIs from malicious systems and users.

APIM controls which AAD Apps are allowed to access the GIG service, hence it is important to add the previously created AAD app against APIM to the allow list. Raise a support ticket with the ABB Ability™ Operations team to help you with this process.

Specifying Environments

While creating, the support ticket, be specific regarding in which environment you would like to add the AAD Application to the allow list.

After successfully adding the app to the allow list in the APIM, you can use the AAD App credentials (client Id and secret) in the GIG service.

# Step 1.2: Generating Access Token

An access token can be obtained with the following call by replacing these parameters:

curl -X POST \
  https://login.microsoftonline.com/{AADTenantID}/oauth2/token \
    -d 'grant_type=client_credentials&client_id={AAD AppId}&client_secret={client_secret}'

Note

Values listed below can be found in Azure Active Directory -> "App Registrations" blade.

AADTenantID: Directory (tenant) ID value
AAD AppId: Application (client) ID value
client_secret: Blade Certificates & Secrets -> Value

Please note, that those values shall be provided by Ops Team for standard cases.

Client Secret: Generation of a client secret for the AAD App: see here for details.

# Step 1.3: Create Unique Ids

Using this service, Business Lines can generate as many UUIDs as they need based on the number of devices being manufactured. Once generated, UUIDs are stored in the database for uniqueness, i.e if another user generates IDs using the GIG service, it generates a different set of Ids which are unique within the system.

Rules

You cannot create more than 100 UUIDs in one request. If you need more than 100 UUIDs, repeat the request multiple times.
This process is a combination of both creation and reservation of created UUIDs.

Refer to the payload below to find out how to generate UUIDs. To learn more about this API, see this page.

# API Request

curl -X POST \
  https://<<Host name of the GIG Service>>/api/ids \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \  
  -d '{
                "count": 2
   }'

# API Response

{
  "data": [
    {
      "id": "42453015-8799-466e-a7eb-6a7919b19fbe"
    },
    {
      "id": "ba6d9112-f643-4927-81eb-d4a34812fd29"
    }    
  ]
}

# Generating UUIDs using programs like uuidgen

UUIDs can also be created using UUID helper programs. Please refer to the below python snippet which creates UUID ver 4.0 as per RFC 4122

import uuid
print(uuid.uuid4())

When you decide to generate the UUIDs using external programs such as uuidgen, it is recommended that you validate the uniqueness against the GIG service to avoid any possible collision or duplicates.

As per this wiki article, while the probability that a UUID gets duplicated is not zero, the chance is so small that it can be considered negligible. Despite that, we do not recommend assuming that the generated UUIDs are unique 100% of the time. Hence, it is always better to cross-validate the UUIDs generated elsewhere with the ABB Ability™ GIG Service.

# Validation of the ID

The Python script below generates a UUID and validates that it is unique among the ABB™ Ability GIG service.

import uuid
import requests

# Generate UUID and convert the type to string
generated_uuid = str(uuid.uuid4())
 
# call the Get Api with UUID as the parameter
url = "https://api-glb01.dev.abilityplatform.abb/api/ids/" + generated_uuid 
 
# Receive the response
response = requests.request("GET", url, headers = headers, data = payload)
#print the output body
print(response.text.encode('utf8'))

Note

UUIDs generated outside of the GIG service must be validated using the above API. Make sure to register the generated IDs with the GIG service to reserve them and prevent other users from blocking the same IDs.

# Generate enrollment codes for Ability PKI

The ABB Ability™ PKI section contains all the information regarding the manual and [automated]/devices/pki/how-to-guides/automated-production-onboarding.html) production processes, as well as a tutorial to obtain enrollment codes with SCEP. Enrollment codes may also be received via the Certificate Manger API.

# Securing Ability PKI Enrollment Codes

Ability PKI enrollment codes are critical and should remain confidential. Compromised enrollment codes with the corresponding device ID may result in serious consequences. For example, malicious users who get access to this information may be able to enroll any malicious device and send junk data or get access to the ABB Ability™ Platform. Therefore, we recommend you keep security in mind when managing enrollment codes.

← Device.SyncModel (V1) Global ID Generator API →