Contents
Use the Duo Network Gateway API to programmatically administer your Duo Network Gateway server deployment.
Overview
The Duo Network Gateway API lets administrators configure the Duo Network Gateway (DNG) through a RESTful API. The API has methods for creating, retrieving, updating, and deleting core configuration in the Duo Network Gateway, as well as configuration and management of all DNG protected applications.
First Steps
-
Install Duo Network Gateway on a designated server in your network. To be able to use the DNG API you must verify the DNG requirements and prerequisites, and complete the DNG installation process for your chosen deployment type.
Once your DNG server is available at https://URL-OF-NETWORK-GATEWAY-ADMIN:8443 then you may opt to complete first-time Duo Network Gateway configuration using the API instead of via the Network Gateway admin console or with scripted configuration.
-
Proceed to setup a client certificate for API authentication.
Client Certificate Authentication
The Network Gateway API uses client certificate authentication to authenticate all API requests. Client certificates can be configured using scripted configuration or the DNG admin console.
Client Certificate Requirements
The client certificate presented to the Network Gateway API must have the following properties:
- X509 extended key usage extension set to
clientAuth - X509 key usage extension set to
digitalSignature
Any self-signed certificate meeting these requirements can be used as the client certificate.
The Duo Network Gateway can generate a self-signed certificate for client authentication using the DNG admin console or the command-line interface (CLI).
Create Client Certificate
From the DNG Admin Console
Generating an API client certificate from the DNG admin console always creates a password-protected key. Use the provided shell or batch script to decrypt the private key for usage in scenarios where supplying a password is not possible.
-
Log in to the DNG admin console at https://URL-OF-NETWORK-GATEWAY-ADMIN:8443.
-
Navigate to API Settings and click Add Client Certificate.
-
You will be given the option to create a new self-signed certificate or to upload a certificate you already have that meets the client certificate requirements.
-
If you opted to have DNG generate the client certificate you may download the new certificate and key.
From the CLI
You may choose to create an API certificate with or without a password-protected key.
Generate an API Certificate and Password-Protected Key
To generate a client certificate and password protected key, run the following command from the DNG Docker host:
docker exec network-gateway-admin generate-api-cert -p [passphrase] [your certificate common name here]
Generate an API Certificate and Non-Password-Protected Key
To generate a client certificate and non-password protected key, run the following command from the DNG Docker host:
docker exec network-gateway-admin generate-api-cert [your certificate common name here]
After running either command save the two portions of the output accordingly for use with your API client of choice.
Add API Certificates
After generating the API certificate, you will need to add it to your running DNG configuration.
To add a client certificate to the current configuration, run the following command from the DNG Docker host:
docker exec -i network-gateway-admin add-api-cert < your-certificate-file.crt
Clear API Certificates
To clear all of the currently configured client certificates, run the following command from the DNG Docker host:
docker exec network-gateway-admin clear-api-certs
Base URL
All Network Gateway API methods use the same network interface and port as the admin console e.g. https://URL-OF-NETWORK-GATEWAY-ADMIN:8443. For example, if your Duo Network Gateway admin console can be accessed via the following URL: https://dng.example.com:8443, then all API calls will use that as the base URL. Note that the Duo Network Gateway admin console and API should be internal to your network and not publicly exposed.
Duo Network Gateway API endpoint example with paging that retrieves the first 10 configured SSH Servers:
https://dng.example.com:8443/api/ssh-servers?limit=10&offset=0
Response Format
Responses are formatted as a JSON object with a top-level stat key.
Successful responses will have a stat value of "OK" and a response key. The response will either be a single object or a sequence of other JSON types, depending on which endpoint is called.
{
"stat": "OK",
"response": {
"key": "value"
}
}Values are returned as strings unless otherwise documented.
Unsuccessful responses will have a
stat value of "FAIL", an integer
code, and a
message key that further describes the failure.
A message_detail key may be present if additional information is available (like the specific parameter that caused the error).
{
"stat": "FAIL",
"code": 40002,
"message": "Invalid request parameters",
"message_detail": "username"
}The HTTP response code will be the first three digits of the more specific code found inside the JSON object. Each endpoint's documentation lists HTTP response codes it can return. Additionally, all API endpoints that require a signed request can return the following HTTP response codes:
| Response | Meaning |
|---|---|
| 200 | The request completed successfully. |
| 400 | The request parameters provided are invalid. |
| 401 | The client certificate presented is unauthorized or invalid. |
| 405 |
The request's HTTP verb is not valid for this endpoint (for example, POST when only GET is supported).
|
Response Paging
Some API endpoints return a paged list of results on GET, up to the API endpoint's limit, or maximum results per page.
A successful response when the total results exceed the endpoint's default page size will include a metadata section with information about the total number of objects found and the results returned in the paged response. If the request returns no paging metadata, then either the endpoint does not support paged results or the total results do not exceed one page.
Specifying incorrect paging parameters results in a 400 invalid parameters response.
| Metadata Information | Description |
|---|---|
total_objects
|
An integer indicating the total number of objects retrieved by the API request across all pages of results. |
next_offset
|
An integer indicating The offset from If not present in the metadata response, then there are no more pages of results left. |
prev_offset
|
An integer indicating the offset from |
Use the metadata information returned to change the paging parameters for your request.
| Paging Parameter | Required? | Description |
|---|---|---|
limit
|
Optional |
The maximum number of records returned in a paged set of results. Each endpoint that supports paged results has its own If a request specifies a value greater than the endpoint's maximum |
offset
|
Optional |
The offset from When used with "limit", the handler will return "limit" records starting at the n-th record, where n is the offset. Default: |
To retrieve the full set of results for a request with paged results, repeat the call, specifying the offset parameter value, until there are no more results (indicated by the absence of next_offset).
Paging Metadata Examples:
The metadata response will look like these examples except where noted for an individual API endpoint.
This metadata information indicates that there are 951 total objects returned by that endpoint, and no offset or limit was specified so the response set defaulted to the first 100 objects:
{
"metadata": {
"next_offset": 100,
"prev_offset": 0,
"total_objects": 951
}This metadata information indicates that the request specified offset=500 limit=200, so the response set was objects 500-699:
{
"metadata": {
"next_offset": 700,
"prev_offset": 300,
"total_objects": 11318
}This metadata information indicates that there are 2342 total objects, and the request specified offset=2300 and used that endpoint's default limit of 100, so the response set was the end of the list (objects 2300-2342):
{
"metadata": {
"prev_offset": 2200,
"total_objects": 2342
}Duo Network Gateway OpenAPI Specification
Download the Duo Network Gateway OpenAPI YAML file for full details of the DNG API endpoints.