Overview of REST API

ActivID CMS is a highly extensible card and credential management platform. It provides the tools, documentation, and APIs needed to enable system integrators and technology partners to:

  • Extend ActivID CMS functionality,

  • Support additional credential providers, such as Private Key Infrastructure (PKI) Certificate Authorities (CAs),

  • Customize data handling for personalization/production of smart cards and USB security devices, and

  • Leverage ActivID CMS functionality from external systems (such as Card and Credential Request Management and Card Issuance, Operator Management, etc.)

These tools and API are provided by the CCM Card and Credential Management API. For details, refer to About the CCM API.

The initial version of the REST API provided only one service: Operator management. The current version provides additional services that focus on device issuance and termination.

The remainder of this documentation details the REST API services:

  • The OAuth 2.0 API to manage operator authentication with PKI

  • The SCIM (System for Cross-domain Identity Management) API to:

    • Create, search, and delete operators.

    • Search, update and delete devices.

    • Search device policies.

    • Create, search, update, and delete content requests.

Note: The ActivID CMS REST API is the successor of the CCM API. It is not yet complete; the CCM API can still be used. For more information, see About the CCM API.

Architecture

Until ActivID CMS 5.10, we provided a Java and C SDK including a SOAP client for the CCM Card and Credential Management API. The typical integration involves a Java or C application linking to the ActivID CMS SDK to both interact with the ActivID CMS server and the device plugged in. These SDKs are still available.

Diagram Description automatically generated

With the extension of the REST API for device issuance in ActivID CMS 5.10, we move to a new integration scheme where the application is a Single-Page Application (SPA) running in a Chrome™-based browser.

Diagram Description automatically generated

Note: In later versions of ActivID CMS, we will also support direct REST calls from the SPA to the ActivID CMS server.

It is assumed that the SPA has a back end with customer services. The back end sends requests to the ActivID CMS server after being authenticated.

The SPA interacts with the device plugged in the machine through the ActivID CMS Chrome Extension and the ActivID CMS Client. If written in Angular, the SPA can also benefit from the CMS Angular Service that facilitates this integration.

ActivID CMS Client

The ActivID CMS Client is a native executable program used by the browser to exchange data between a device and the ActivID CMS server during a Synchronization.

The Operator Portal and the User Portal automatically propose to download and install the ActivID CMS Client if it is missing. The .msi installation file can be downloaded from the ActivID CMS server.

ActivID CMS Extension

The ActivID CMS extension is a Chrome component that facilitates communication between the web front end (for example, the Operator Portal) and the ActivID CMS Client.

The extension works for both the Google Chrome and the Chrome-based Microsoft Edge browsers.

The Operator Portal and the User Portal automatically propose to download and install the ActivID CMS extension if it is missing. It is available in the Chrome store: https://chrome.google.com/webstore/detail/activid-cms-extension/ddfoinleihmgpkhfmemkncgffilfahnm

Concepts

A request to provision content into a device. Content includes credentials and any data specified by the device policy. The request is linked to:

  • A target Device, onto which the credentials are to be provisioned.

  • A Wallet, for which the credentials are to be provisioned.

A generic term for a piece of information that is certified by an authority used to authenticate an individual or a machine. Credentials are trusted pieces of data that attest to the identification or authentication of users (or other trusted identities). Credentials are classified according to the mechanisms by which they are consumed, by applications, and by the types of services they enable.

Typical credentials managed by ActivID CMS are cryptographic key pairs and their associated certificates, and OATH Open Authentication keys used to generate OTPs.

A hardware or software device capable of serving as a storage and execution platform for embedded applications, credentials, and their services (for example, smart cards, One-Time Password (OTP) tokens, USB keys such as Crescendo Keys, and Trusted Platform Modules (TPMs)).

This is the exact equivalent of the “Security Module” in the CCM Card and Credential Management API.

A Device Flow represents the complete personalization process of a device. It may include the content delivery initiated by the creation of a content request, but it also includes steps before and after that content delivery, like the collection of data or the device layout definition and printing.

Device policies enable organizations to enforce uniform applications and device policies on a per-user-group basis. A device policy defines the information used to personalize applications on a device during device issuance or a device update.

A group represents a population of users for whom you want to manage devices. User groups are defined as LDAP queries.

Synchronization is the operation in which a physical device is updated; this is the final step of the device issuance performed by ActivID CMS. The ActivID CMS Client drives the synchronization by opening a secure connection to the ActivID CMS server. A web front-end application can communicate with the ActivID CMS Client through the Chrome extension.

When synchronization is performed, the device is updated according to the actions queued for that device: for instance, a ContentRequest previously submitted to ActivID CMS, or a recycling action (in the case of a Device status update). For example, certificates may be loaded, key pairs may be generated and loaded, or data may be removed.

In ActivID CMS, a User instance represents an actual user of the organization. Each user is identified by a unique identifier. This identifier is an LDAP Lightweight Directory Access Protocol attribute which has been defined in ActivID CMS as the unique user identifier attribute (for example, the identifier might be the sAMAccountName, or UID.)

Note: Even though the definition is general, the REST API currently limits the users manipulation to the ActivID CMS operators. Other users are only available through their wallet (see below).

In ActivID CMS, a Wallet instance is a set of Devices and Credentials assigned to a User.