Middleware provides a read interface to the Certificate Manager via a REST API located at https://certs.it.vt.edu/api/v1.
REST API Client Example
The following code sample in Python provides a simple but complete usage overview that covers authentication and reading data:
There are a couple prerequisites that prospective clients need to consider before attempting to consume the REST API.
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).
Personal Digital Certificate (PDC)
A PDC may also provide the security credential to invoke the REST API endpoints.
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.
The following conventions are intended to facilitate using the API. We recommend committing these conventions, which we have found improves users’ ability to anticipate URIs and JSON document field names.
URI Naming Conventions
- Resource URIs are named with a plural resource collection, for example, /v1/certs?[by=x&keyword=y] .
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
The HTTP Bearer token authentication method provides the best balance of security and usability to clients:
- Strong security via digital signatures
- Excellent cross-platform support
- Precise control over token validity period
A signed JSON Web Token (JWT) provides most of the advantages above and 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:
For a PDC:
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.
The certs resource provides information about a certificate and a subset of requests data for that certificate. Searches “by” cn, username, email, and serial are supported. Examples: