Describing Security Controls

Security controls encompass a broad range of protective measures implemented in information systems. While authentication and authorization are commonly recognized, modern web applications employ numerous additional controls¹ including data encryption², digital signatures³ for content integrity verification, and provenance tracking⁴ to document content manipulation history. The diversity of implementation approaches creates significant challenges for users attempting to understand available controls and their interaction methods.

The developer community has long sought standardized methods to communicate these controls effectively. The OpenAPI Specification⁵ enables API providers to document functionality in a standardized format, facilitating easier integration by developers. However, while OpenAPI effectively describes authentication methods on a per-endpoint basis, it shows notable limitations when representing other critical security controls such as encryption protocols, digital signature verification, and data provenance mechanisms⁶. These limitations have prompted exploration of complementary approaches to security control documentation.

The Open Geospatial Consortium (OGC)⁷ acknowledges this challenge extends to geospatial APIs as well. To improve developer documentation, OGC is exploring various approaches for communicating security controls beyond OpenAPI's capabilities. Alternative solutions include leveraging Well-Known URIs⁸ to represent APIs and express security controls, with the api-catalog link relation⁹ serving as a notable example.

In addition to Well-Known URIs, OGC provides examples of conformance classes and the definition of landing pages in OGC API Commons—Part 1: Core¹⁰. This standard describes the concept of a landing page in both HTML and JSON where the API endpoints are described.

The APIs in this Portfolio, including the Greeting API, serve as experimental platforms to demonstrate various methods for describing security controls. For instance, a conformance class was implemented to indicate that the Greeting API adheres to the Basic Authentication Scheme¹¹. However, this approach has limitations: developers can only determine that authentication is required somewhere in the API, but not which specific methods require it.

HTML landing pages offer a more comprehensive description of API functionality and developer requirements, including authentication server locations and registration procedures. Yet, while HTML content serves human users well, it falls short for applications seeking automated API connections. Consider a user of a Geographical Information System (GIS) like QGIS¹² - how can the system automatically detect available security controls when connecting to a service? This challenge is currently being addressed by the OGC's Standard Working Group (SWG)¹³ for OGC API Common - Security. Those interested in contributing to this effort are encouraged to join the OGC and participate in the ongoing standardization work.