Authentication and access control

wis2box provides built in access control for the WAF and API on a topic hierarchy basis. Configuration is done using the wis2box command line utility. Authentication tokens are only required for topics that have access control configured.

Adding Access Control

All topic hierarchies in wis2box are open by default. A topic becomes closed, with access control applied, the first time a token is generated for a topic hierarchy.


Make sure you are logged into the wis2box-management container when using the wis2box CLI

wis2box auth add-token --topic-hierarchy mytoken

If no token is provided, a random string will be generated. Be sure to the record token now, there is no way to retrieve it once it is lost.


Token credentials can be validated using the wis2box command line utility.

wis2box auth show
wis2box auth has-access --topic-hierarchy mytoken
wis2box auth has-access --topic-hierarchy notmytoken

Once a token has been generated, access to any data of that topic in the WAF or API requires token authentication. Tokens are passed as a bearer token in the Authentication header or as an argument appended to the URI. Headers can be easily added to requests using cURL.

curl -H "Authorization: Bearer mytoken" "http://localhost/oapi/collections/"
curl -H "Authorization: Bearer notmytoken" "http://localhost/oapi/collections/"

Removing Access Control

A topic becomes open and no longer requires authentication when all tokens have been deleted. This can be done by deleting individual tokens, or all tokens for a given topic hierarchy.

wis2box auth remove-tokens --topic-hierarchy
wis2box auth show

Extending Access Control

wis2box provides access control out of the box with subrequests to wis2box-auth. wis2box-auth could be replaced in nginx for another auth server like Gluu or a Web SSO like LemonLDAP or Keycloak. These services are not yet configurable via the wis2box command line utility.

wis2box is intentionally plug and playable. Beyond custom authentication servers, extending wis2box provides an overview of more modifications that can be made to wis2box.