Common JSON Objects

Table of Contents

• JSON Format for ACLs
• JSON Format for HTTP Authentication Settings
• JSON Format for Certificates

The Xentara model and configuration files use specially formatted JSON objects for common types of objects in JSON files. These formats are described here.

JSON Format for ACLs

A JSON object describing an ACL has the following syntax:

"ACL": {
  "inherit": true,
  "entries": [
    {
      "role": "Everyone",
      "allow": [ "read", "monitor" ],
      "deny": [ "write", "control" ]
    },
    {
      "role": "Operator",
      "allow": [ "write", "control" ],
      "deny": [ "admin" ]
    }
  ]
}

Object Members

inherit	An optional JSON Boolean value (true or false) specifying whether the ACL should inherit the parent ACL. See ACL Inheritance for details.
entries	An optional JSON array containing the entries of the ACL. The array can contain as few or as many entries as desired. The format of the individual entires is described below.

Entry Object Members

role	A string value containing the name of the role this entry applies to. Unknown role names are ignored with a warning.
allow	An optional JSON array containing the names of the entitlements to allow for this role. Unknown entitlement names are ignored with a warning. If you do not specify this member, or if the array is empty, the entry will not allow any entitlements beyond those inherited from the parent ACL.
deny	An optional JSON array containing the names of the entitlements to deny for this role. Unknown entitlement names are ignored with a warning. If you do not specify this member, or if the array is empty, the entry will not deny any entitlements.

JSON Format for HTTP Authentication Settings

A JSON object describing HTTP authentication settings has the following syntax:

"authentication": {
  "realm": "Xentara",
  "schemes": [ "Bearer" ],
  "scope": [ "com.mycompany:xentara" ]
}

Note

The HTTP authentication settings object might not always be called "authentication". Some configurations may use other names, for example "HTTPAuthentication".

Object Members

realm	An optional string value containing the realm to be returned in the WWW-Authenticate header in authentication error responses. The realm is a purely informative value intended to be used by the client to select the correct protection space. It is in essence an arbitrary value, but should be different for servers that use a different authentication scheme and/or authorization database. The “realm” directive is described in section 11.5. of RFC 9110 — HTTP Semantics. If you do not specify this member, then the realm will be “Xentara”.
schemes	An optional JSON array specifying the supported HTTP authentication schemes. Possible values are "Bearer" and "Basic". The "Bearer" scheme enables OAuth 2.0 authorization using bearer tokens, as described in RFC 6750 — The OAuth 2.0 Authorization Framework: Bearer Token Usage. The "Basic" scheme enables HTTP basic authentication and is described in RFC 7617 — The 'Basic' HTTP Authentication Scheme. Basic authentication uses the built-in Xentara Username/Password authentication. If you do not specify this member, then OAuth 2.0 authorization will be enabled as the only authentication scheme.
scope	An optional JSON array containing the OAuth 2.0 scope strings to use. These scope strings must appear in the scope claim of any JWTs used for OAuth 2.0 authorization. The scope strings are also sent as part of the WWW-Authenticate header when using the HTTP protocol. The individual scope strings must be valid OAuth 2.0 scope tokens according to section 3.3 of RFC 6749. The array can contain as few or as many scope strings as desired. If you specify an empty array, no scope checking will be performed, and no scope will be sent in the WWW-Authenticate header. If you do not specify this member, then the default scope strings configured in the OAuth 2.0 configuration file will be used.

JSON Format for Certificates

A JSON object describing a certificate has the following syntax:

"certificate": {
  "certificatePath": "mqtt/client.pem",
  "privateKeyPath": "mqtt/client.key.pem"
}

Note

The certificate settings object will not always be called "certificate". Many configurations will use more specific names, for example "serverCertificate" or "clientCertificate".

Object Members

certificatePath	A string value containing the path to the certificate file. The certificate file is searched for as described under Certificate File Location. The certificate file must be a PEM encoded file containing the certificate, as described in Certificate And Private Key File Structure.
privateKeyPath	A string value containing the path to the private key file. The private key file is searched for as described under Certificate File Location The private key file must be a PEM encoded file containing the certificate’s private key, as described in Certificate And Private Key File Structure.