auth_proxy provides authentication (local users/LDAP/AD) and authorization
(RBAC) before forwarding requests to an upstream
netmaster. It is TLS-only,
and it will only talk to a non-TLS
netmaster. Future versions will allow
or potentially require TLS-only communication with
auth_proxy also hosts the Contiv UI (see the contiv-ui repo).
The UI is baked into the container and lives at the
/ui directory. It is served
from the root of the proxy, e.g., if you run with
you can see the UI at https://localhost:10000
A custom version of the UI can be bindmounted over the baked-in version. Note that
you need to bind in the
/app directory under the
contiv-ui repo, not the base
make will generate a
contiv/auth_proxy:devbuild image using the current
code you have checked out and
HEAD from the
master branch in the
You can also specify a version, e.g.,
BUILD_VERSION=0.1 make. This will
contiv/auth_proxy:0.1 image using current code you have checked out
and whatever commit is tagged as
0.1 in the
auth_proxy will check the version of the
netmaster it's pointed to at startup.
We require that the major versions are the same and that the minor version of
netmaster is >= the minor version of
For example, version
auth_proxy will only talk to a
x is >= 2 and
y can be anything.
Tests currently run against the
contiv/auth_proxy:devbuild image. Make sure you
have built this image before running tests.
make test to run the systemtests and unit tests. The tests are fully
containerized and will spawn everything they require as part of the test run
(note that this does NOT currently include an AD server, and we are still using a
There is also a
MockServer available in the
directory which can pretend to be
netmaster for the purposes of testing. This
allows us to mock the parts of
netmaster we need (mainly that a given endpoint
returns some expected JSON response) without the burden of actually compiling
and running a full
netmaster binary and all of its dependencies plus creating
the necessary networks, tenants, etc. to get realistic responses from it.
For a complete e2e setup involving auth_proxy + UI + netmaster, please see contiv/install.
You will need a certificate and key to start
auth_proxy. You can run
make generate-certificate to generate a self-signed certificate and key under
./local_certs if you don't already have them.
To test auth_proxy in isolation, use
make run to start it using the compose file.
Before anything else, a prospective user must authenticate and get a token.
Authentication requires passing a username and password to the
login request ---> auth_proxy ---> authentication \ local user *or* LDAP / Active Directory / <---- token sent to client <---- auth_proxy ----
Subsequent requests must pass this token along in a
header. All non-login requests are simply passed on to the
authentication and authorization are both successful.
Example of a full request cycle:
- A request for
/api/v1/networks/is sent in with a token in the
- The user represented by the token is authenticated against a local DB or LDAP / Active Directory
- An authorization check is performed to see if the user is allowed to access the resource in question (networks)
- If both authentication and authorization are successful, the request is proxied to
- If the user is not an admin and the endpoint returns data for multiple tenants, the response from
netmasterwill be filtered to only return what the current user is allowed to see
request w. token ---> auth_proxy ---> authorization ----> request forwarded to netmaster \ netmaster / <----- results filtered based on token and returned to client <----- auth_proxy --------