This document gives an overview of Orc8r's security architecture, with specific focus on the northbound (REST API) and southbound (gateway) interfaces. For more in-depth information, see Security Debugging.
Orc8r security is enforced in a two-tiered approach
- mutual TLS termination at the Orc8r proxy
- application-level access enforcement
Every request to Orc8r is mutually-authenticated via client-validated TLS. This validation occurs at the Orc8r proxy, where the request's
client certificate is converted to a set of trusted metadata in the proxied request. From there, individual services can make
application-level decisions on access enforcement, often by making requests to the
accessd Orc8r service.
The one exception to client-validated endpoints is the southbound bootstrapper endpoint. Orc8r provides a mechanism for registered gateways
to securely bootstrap their authentication process via an open (server-validated only) service endpoint granting access to the
bootstrapper service. This endpoint allows gateways to periodically refresh their session certificates, which grant access to the full
For the northbound interface (NMS and direct usage of the REST API), requests must include a provisioned client certificate. This
certificate can be generated using the
accessc CLI from any Orc8r pod.
Gateways generate, or can be provisioned with, two pieces of identifying information
- hardware ID is the gateway's unique identifier
- challenge key is a long-term keypair used for the bootstrap process
Operators must include two additional pieces of information to allow the gateway to connect to Orc8r
control_proxy.ymlis a config file providing the location of the Orc8r
rootCA.pemis a CA certificate providing the root of trust for validating Orc8r during TLS handshakes
Operators use the
show_gateway_info.py script to read the hardware ID and public part of the challenge key. They then register the gateway
with the cloud (e.g. via NMS), including these pieces of information, and provision the gateway with the correct values in
rootCA.pem. From here, the gateway can begin the bootstrap process.
The bootstrap process involves two sequential requests to the
GetChallengegateway requests a challenge from Orc8r
RequestSigngateway sends signed challenge and a CSR
If the bootstrap process is successful, Orc8r signs and returns the CSR from the
RequestSign request, which the gateway can now use as
its session certificate. Orc8r enforces a max validity period, so gateways must periodically re-bootstrap to receive updated session
Operators can use the
checkin_cli.py script to debug issues with this process of checking in and bootstrapping.
Application-layer access control
Once a request passes TLS termination at the Orc8r proxy, Orc8r also supports finer-grained application-level access control. In Orc8r, an ACL defines a mapping between identities, where each mapping includes read/write permissions. There are 3 types of identities
- Gateway identities represent a gateway
- Operator identities represent a network operator
- Network identities represent access to a particular network
At the Orc8r proxy, client certificates are translated to trusted request metadata. Middleware can then convert the metadata, via calls to
certifier service, to an identity.
At the southbound interface, only gateway identities are allowed to make requests. Unregistered gateways are blocked.
At the northbound interface, only operator identities are allowed to make requests.
Additionally, the northbound interface is protected by a token that is sent in the header with every request.
The admin can create additional users and tokens with desired permissions using the REST API.
To access REST API resources, perform the following steps:
- Log in with their username and password through the
- Copy the token from the response body
- Authenticate with their username and token (in lieu of the password field) through the Swagger Authorize tool on the top right corner
For backwards compatibility, token security layer is hidden under the
useToken in the certifier config.
Currently, it is off by default.
Check out REST API Security for more details.