Conjur OpenAPI Specification

This project contains the OpenAPI v3 specification for Conjur Open Source.

The Conjur OpenAPI specification provides a standardized, machine-readable version of the Conjur API that can be used to automatically generate API documentation, to generate Conjur client libraries in your language of choice, and to facilitate exploring the Conjur API using popular tools like Postman.

This project simplifies end users’ ability to interact with the Conjur API, and will enable the continued expansion of Conjur integrations so that Conjur works natively with the most popular software development tools. We’ll be using this OpenAPI spec to build a better, more consistent, always up-to-date Conjur SDK comprised of clients in the most popular languages with comprehensive automated test coverage.

Find more from CyberArk.

Certification level
Requirements
- Use With Conjur Enterprise
Getting Started
Contributing
License

Table of contents generated with markdown-toc

Certification level

This repo is a Community level project. It's a community contributed project that is not reviewed or supported by CyberArk. For more detailed information on our certification levels, see our community guidelines.

Requirements

This project requires Docker and access to DockerHub.

The OpenAPI Specification is compatible with Conjur Open Source v1.9+.
Clients are generated using OpenAPI Generator v4.3.1.

Use With Conjur Enterprise

An enterprise version of the spec can be generated by calling ./bin/transform --enterprise from within the repository.

The enterprise version of the spec includes the following exclusive endpoints:

/health
/remote_health
/info

However the /configuration/{account}/seed/follower endpoint is still not included at this time.

Getting Started

If you are new to OpenAPI you may want to visit the understanding the spec wiki page, which will give you a brief overview of how to interpret and make changes to the spec file.

To view the Conjur OpenAPI Specification directly, please see the spec/ directory.

Note: The OpenAPI source includes a custom property x-conjur-settings to differentiate Enterprise-only endpoints from the rest of the specification. In the sections below, we review many common ways that you can use the Conjur OpenAPI definition. We recommend using a Conjur OpenAPI definition from an official release that's compatible with your specific Conjur server version. If you're interested in building from source, you can run the following script to parse the custom x-conjur-settings parameters and generate an OpenAPI spec for the specific edition of Conjur that you're using:

./bin/transform --oss # Creates a spec definition for Conjur Open Source in out/oss/
./bin/transform --enterprise # Creates a spec definition for Conjur Enterprise in out/enterprise/

In the sections below, we review some of the ways you can leverage the spec in your own workflows. Need help with something that's not yet documented here? Please open an issue - we'd be happy to help you get started.

Swagger Editor

The Swagger Editor is a great tool for viewing and editing OpenAPI specifications, although we discourage editing directly in the UI because our spec is split over multiple files. In order to view the spec in Swagger run the ./bin/start_spec_ui script, all of the standard spec files will be bundled together and an instance of the UI will be opened pointing at the bundled spec.

Generating client libraries

To generate a client library using the OpenAPI spec, use the provided script:

$ ./bin/generate_client -l <language> [-o <output-dir>]

The script will generate a Python client in the absence of a <language> argument.
A full list of supported languages can be found in OpenAPI Generator documentation.

Examples

Included in the examples directory are demonstrations for using spec-generated API clients.
The demos show how to use popular Conjur API endpoints:

Authenticate a user
Change user's own password
Rotate user's API key
Load the root policy
Store and retrieve a secret

There are currently examples in two languages, Python and Ruby.
The examples can be run using their respective scripts:

$ ./examples/python/start
$ ./examples/ruby/start

Each example performs the following steps:

Generate an OpenAPI client with ./bin/generate_client -l <language> (if not already present)
Spin up the a Conjur environment from docker-compose (if not already present)
Perform language-specific environment setup
Run the example

Exploring the Conjur API with Postman

A step-by-step guide can be found in the examples/postman directory.

Using the OpenAPI spec with API Gateways

Because the OpenAPI Specification is a widely accepted standard interface for RESTful APIs, many popular API gateways have tools for importing an OpenAPI spec into their service.

Included in this project is an example of using Kong Gateway OSS with Conjur. Importing an OpenAPI spec into Kong requires first converting it into a Kong declarative configuration, which can be done with script bin/generate_kong_config. The example can be run with examples/kong/start.

Apigee Edge has a convenient and well-documented process for creating an API proxy from an OpenAPI Specification, but requires the spec to define a public target server.

While AWS API Gateway provides a workflow for setting up a new API by importing an OpenAPI spec, there are many OpenAPI features that are not supported. This precludes this project from being completely compatible.

Contributing

We welcome contributions of all kinds to the Conjur OpenAPI Spec. For instructions on how to
get started and descriptions of our development workflows, please see our contributing guide.

License

This project is licensed under Apache License v2.0.

cyberark / conjur-openapi-spec

readme