Certificate Manager REST API | Middleware Services

Middleware provides a read interface to the Certificate Manager via a REST API.

Two versions are available:

v1 — single-criterion search (by=x&keyword=y)
v2 — multi-filter AND search with richer filtering options

Prerequisites

Enterprise Directory Service

An ED Service provides the security principal and credential to invoke REST API operations. An ED service is typically credentialed with an X.509 certificate issued by the Middleware CA, but may also have a password credential issued under approved circumstances (see below).

Request an ED Service.

Personal Digital Certificate (PDC)

A PDC may also provide the security credential to invoke the REST API endpoints.

Request a PDC.

Authorization to Invoke REST API

An authenticated user must be entitled to invoke various REST API operations. The entitlement structure is rest/search and is owned by the certs service.

Authentication

Two authentication methods are supported:

HTTP Bearer token authentication via ED service signed JWT
HTTP Bearer token authentication via PDC signed JWT

HTTP Bearer Auth

A signed JSON Web Token (JWT) is simply a JSON document that is prepended with a digital signature algorithm header and to which a digital signature is appended; all parts are base-64 encoded.

Claims should mirror the following:

For an ED service:

{
  "iss": "uusid=vt-service,ou=services,dc=vt,dc=edu",
  "sub": "uusid=vt-service,ou=services,dc=vt,dc=edu",
  "iat": 1476180159,
  "exp": 1476181959
}

For a PDC:

{
  "sub": "uupid=vt-username,ou=people,dc=vt,dc=edu",
  "iat": 1476180159,
  "exp": 1476181959
}

The fields of the JSON document follow an established vocabulary called claims, of which three are recognized for Certificate Manager Web services:

iss - REQUIRED DN of the service/person
sub - REQUIRED DN of the service/person
iat - REQUIRED creation (Issued At) date of token
exp - REQUIRED expiration date of token

The token MUST be signed with the private key corresponding to a valid (e.g. not expired) ED service certificate and whose service exists and is active in the Enterprise Directory. The signature MUST be produced using the RS256 algorithm.

In general JWT bearer tokens MUST NOT be shared since a bearer token is by nature a self-contained authentication token; whoever bears the token may authenticate and access services as the principal identified in the token.

URI Naming Conventions

Resource URIs are named with a plural resource collection, for example /v1/certs or /v2/certs.