Introducing the Conjur OpenAPI Description

Published April 30th, 2021 by John O'Donnell

The Conjur REST API is now available as an open-source OpenAPI definition. This effort creates new avenues for API exploration, a basis for consistent and easily maintainable documentation, and the ability to leverage popular tools built for the industry standard OpenAPI Specification (OAS). The project includes a complete description of both Conjur OSS and Enterprise APIs.

The Conjur OpenAPI Specification is available on GitHub. The repository’s Wiki contains up-to-date API documentation generated from the description.

Understanding the API Description

The Conjur OpenAPI description is split across 10 YAML files: 9 representing a particular category of API request, and a root file, openapi.yml. Each YAML file defines their related endpoints as path components, complete with required and optional parameters and all possible responses. The root file consolidates these definitions and attributes each to their URI by reference:

openapi.yml

paths:
  '/{authenticator}/{account}/login':
    $ref: 'authentication.yml#/components/paths/Login'

authentication.yml

components:
  paths:
    Login:
      get:
        parameters:
        - name: "authenticator"
          in: "path"
          required: true
          schema:
            $ref: "#/components/schemas/Authenticators"
          ...
        responses:
          "200":
            $ref: 'openapi.yml#/components/responses/ApiKey'
          ...

Included in the repo’s Wiki is a page titled Interpreting the Spec, a guide for navigating the OpenAPI definition. For those unfamiliar with the OpenAPI Specification, Swagger provides comprehensive documentation of the standard and its conventions.

Using the Conjur OpenAPI Spec

As a language agnostic API description standard, the OpenAPI Specification defines API descriptions which allow both human and machine users to investigate a given API without documentation or implementation details. Describing the Conjur REST API in this standard serves to simplify many processes for developers and users.

Exploring the Conjur API in Postman

Postman is a popular API development platform which allows users to interactively explore APIs through their easy-to-use GUI. Users can explore the Conjur REST API by importing the Conjur OpenAPI description into Postman, or by importing the optimized Postman Collection generated from the description.

Generating Conjur API Client Libraries

The repository includes tools for generating client libraries with OpenAPI Generator, making it easier for developers to integrate Conjur into their projects. The OpenAPI Generator supports generating API clients for 35 languages or frameworks, including 7 of the top 10 languages in the TIOBE Programming Community Index for March 2021:

  • C
  • Java
  • Python
  • C++
  • C#
  • JavaScript
  • PHP

Generate any supported client with the command bin/generate_client -l <language>.

Currently, there are no officially supported Conjur API clients generated from the OpenAPI spec. The project’s next goal is to build a fully supported SDK of well-documented, easily-updatable, spec-generated API clients.

Using a Generated Client

Using a generated client requires minimal setup. The following steps detail generating, setting up, and using a Python client.

  1. Generate the client and installing into your environment
bin/generate_client -l python
pip3 install -e /path/to/generated/client
  1. Import the package into your project
import conjur
  1. Setup client configuration with host URL, username and password
config = conjur.Configuration()
config.host = "http://<conjur-url>"
config.username = "<username>"
config.password = "<password>"
  1. Setup an API client, and use it to create an API class instance
api_client = conjur.ApiClient.(config)
auth_api = conjur.AuthenticationApi(api_client)
  1. Authenticate the client with Conjur, and add the access token to the API configuration as an API key
access_token = auth_api.get_access_token(
  account=ACCOUNT_NAME,
  login=LOGIN,
  body=ADMIN_API_KEY,
  accept-encoding="base64"
)

config.api_key = {'Authorization': f'token="{access_token}"'}
config.api_key_prefix = {'Authorization': 'Token'}

The authenticated client can now make authorized calls to any of the other Conjur API endpoints.

The project repo contains two full examples of using a generated API client to perform popular Conjur functions in Python and Ruby.

Using the Conjur OpenAPI Description with your API Gateway

Setting up an API gateway for your Conjur distribution is now simpler than ever, with many of the most popular gateway solutions providing tools for importing an OpenAPI description.

A popular gateway, yet exception to the above rule, is Kong OSS, which does not provide a built-in tool for designing a gateway service given an OpenAPI description. This requires converting the OpenAPI spec into a Kong configuration using Kong’s Inso, a CLI tool for their API design suite Insomnia. This tool works on a bundled version of the OpenAPI description, where the 10 separate YAML files are combined into one.

Before the bundled files can be converted to a Kong configuration, the specification needs to be edited. Most of the tools included in the repository currently support OAS v3.0, which does not include a formal definition for mutual TLS security schemes. This functionality is added in the recently released v3.1, and the Conjur OpenAPI description needs to be updated to this standard:

securitySchemes:
  conjurKubernetesMutualTls:
    type: mutualTLS

Once the security scheme is updated, the Conjur OpenAPI description can be converted to a Kong configuration:

docker run --rm -it \
  -v /path/to/openapi/project:/opt/openapi \
  node: latest \
  bash -c "
    npm i -g insomnia-inso \
    && cd /opt/openapi \
    && inso --verbose \
      generate config spec.yml \
      --type declarative \
      --output out/kong/kong.yml
  "

More details can be found here.

Contributing

The OpenAPI specification is an open source project, and all contributions are welcome! Be sure to familiarize yourself with the repository’s contribution guide, and file an issue if you encounter any problems.

Learn more about the Conjur OpenAPI Description on GitHub and reach us in the community to continue the conversation.