How to View CMD-Auth API and Documentation

1 CMD-Auth API and Documentation

CMD-Auth documentation contains full details of the settings while the Swagger/Open API interface can be used during development or administration.
CMD-Auth will normally reside on private networks. In order to access the API and the documentation please follow the recommendation given below.

2 Prerequisites

The access to the endpoints can be modified by settings from the section routes.
By default all endpoints are accessible from official private IPs only (setting routes > for_trusted_ips_only). It is recommended to keep all routes private, but it is possible to set which routes are for private IPs only, or even make them all publicly accessible (not recommended).
Another critical setting is routes > trusted_ips which can be used to declare a list of additional IPs which are allowed to access the endpoints. IPs from the official ranges of private IPs are always allowed to access the endpoints.

IMPORTANT! By default, the application is generating new HTTPS certificates everytime the application is (re)started.
If the application was (re)started you may need to refresh the browser page and accept the latest generated certificates in order to continue using the documentation.

The API and the documentation are enabled by default. Just like any other routes, the API and the documentation can be disabled by including the routes ID in section routes > disabled of the settings.
Endpoints:

  • API: /api
  • Documentation: /documentation

When supplying settings through the User Data (i.e. AWS EC2 User Data), the machine running cmd-auth should normally be stopped before being able to update User Data. When the settings are updated the machine can be started again.

When supplying the settings through a custom url APP_SETTINGS_URL, or through a file APP_SETTINGS_PATH (in file /etc/cmd-auth/env/systemd.env), there is no need to stop the machine. In this case, in order to apply a fresh set of settings it is sufficient to restart unit cmd-auth.service. The restart of unit cmd-auth.service can also be done using the endpoint PATCH /admin/application/restart.

Since the first implementation of cmd-auth specifications, CleanDeck, is built using PHP, the following recommendations rely on facilities offered by the popular Apache HTTP server in order to proxy requests. Adjust for other types of servers.

As a reminder, CleanDeck has a powerful deployment tool which will help set up PHP and webservers: 

sudo env COMPOSER_ALLOW_SUPERUSER=1 composer exec cleandeck-deploy php nginx
sudo env COMPOSER_ALLOW_SUPERUSER=1 composer exec cleandeck-deploy php apache2

The machine which hosts the Apache HTTP server must be on a public network and at the same time must be able to communicate on internal networks with the machine hosting cmd-auth.
Such setup is the default when creating a new AWS VPC.

3 Internal Networks - View API and Documentation

In this scenario CMD-Auth is available on private networks only (highly recommended). Another machine hosting an Apache server has access to public networks and the private networks used by CMD-Auth.
If you only want to view the documentation without making any further requests using Swagger/Open API interface please edit an active virtual host of your public Apache HTTP server and add the following lines: 

SSLProxyEngine On
SSLProxyCheckPeerName Off
ProxyPass "/api"  "http(s)://192.168.11.22:12345/api"
ProxyPassReverse "/api"  "http(s)://192.168.11.22:12345/api"
ProxyPass "/documentation"  "http(s)://192.168.11.22:12345/documentation"
ProxyPassReverse "/documentation"  "http(s)://192.168.11.22:12345/documentation"

Replace "http(s)://192.168.11.22:12345" with the real address of cmd-auth server.
The Apache HTTP server must be restarted in order to update the settings: 

sudo systemctl restart httpd

CMD-Auth API and Documentation is now available by calling endpoints /api, respectively /documentation at a public address of your Apache HTTP Server.
There is no need to alter related settings in section routes.

4 Internal Networks - View API and Documentation and Use API

In this scenario CMD-Auth is available on private networks only (highly recommended). Another machine hosting an Apache HTTP Server has access to public networks and the private networks used by CMD-Auth.
If you want to view the documentation and make requests using Swagger/Open API interface please edit an active virtual host of your public Apache HTTP server and add the following lines: 

SSLProxyEngine On
SSLProxyCheckPeerName Off
ProxyPassMatch "^/(.*)$"  "http(s)://192.168.11.22:12345/$1"
ProxyPassReverse "^/(.*)$"  "http(s)://192.168.11.22:12345/$1"

Replace "http(s)://192.168.11.22:12345" with the real address of cmd-auth server.
The Apache HTTP server must be restarted in order to update the settings: 

sudo systemctl restart httpd

CMD-Auth API and Documentation is now available by calling endpoints /api, respectively /documentation at a public address of your Apache HTTP Server.
You may also use at will all the endpoints exposed by cmd-auth. This is especially useful when developing and when performing the administration of the application.
There is no need to alter related settings in section routes.

4 Public Networks (Not Recommended) - View API and Documentation and Use API

If the machine hosting cmd-auth is on a public network, you need to add your public IP (for this example "12.34.56.78") to the list of trusted IPs as follows: 

{
    "routes": {
        "for_trusted_ips_only": ["*"],
        "trusted_ips": ["12.34.56.78", "127.0.0.1", "::ffff:127.0.0.1", "::1"]
    }
}

You can now directly view the documentation at http(s)://public.ip.or.address:12345/documentation and use the API at http(s)://public.ip.or.address:12345/documentation.

As a reminder, it is not recommended to keep cmd-auth on public networks. In production, cmd-auth machines should stay on internal networks only.

Add Your Question
FAQs