 |
The Xentara Web Service v1.2
User Manual
|
|
The Xentara Web Service v1.2
User Manual
|
The Xentara Web service uses JSON Web Tokens (JWTs) for authentication. JSON Web Tokens can be generated using a number of tools, for example at https://jwt.io/. More commonly, however, JSON Web Tokens are requested from an OAuth 2.0 authorization server, or from an OpenID Connect authorization server.
The advantage of using JWTs over manually managed user passwords or access tokens, is that the tokens do not have to be stored on the server. This makes it much easier to generate new tokens, to renew expired tokens, etc., which would otherwise require updating a token list located on the host Xentara is running on.
JWTs also allow you to use single sign-on providers like auth0 or Azure AD to manage access to a Xentara Web Service server.
The Web Service server always checks the following JWT claims:
| Claim Name | Claim Description |
|---|---|
| iss | Issuer |
| aud | Audience |
| exp | Expiration Time |
| nbf | Not Before |
The allowable values for the iss and aud claims must be specified in the Xentara model file. exp and nbf are checked against the current time.
Additionally, arbitrary other claims can be checked to restrict access to certain users. Typically, the following claims will be checked:
| Claim Name | Claim Description |
|---|---|
| roles | Roles |
| groups | Groups |
| entitlements | Entitlements |
The sub (Subject) claim that contains the user name or user ID of the user is also a possible candidate to restrict access. This requires hardcoding the allowed user names into the Xentara model file, however.
Claims can be used as additional claims if they are arrays of strings (like roles, groups, and entitlements), or simple strings (like sub).
For each claim, you must specify a list of allowed values. The authentication will be accepted if any value of the additional claims matches any of the allowed values.
In the following example, all subjects (users) that have the entitlement “Xentara” will be allowed to access the Web Service:
| Claim Name | Allowed values |
|---|---|
| entitlements | “Xentara” |
In the following example, all subjects (users) that belong to the role “Maintenance” or the role “Control” will be allowed to access the Web Service:
| Claim Name | Allowed values |
|---|---|
| roles | “Maintenance”, “Control” |
In the following example, all subjects (users) that belong to the role “Maintenance” or the role “Control”, or that are part of the group “Admin” will be allowed to access the Web Service:
| Claim Name | Allowed values |
|---|---|
| roles | “Maintenance”, “Control” |
| groups | “Admin” |
An authoritative list of claims is maintained by IANA at [https://www.iana.org/assignments/jwt/jwt.xhtml#claims].
The Xentara Web Service only accepts signed JWTs. To be able to verify the signature of the tokeb, the public signing key of the issuer must be copied to the host on which Xentara is running.
Xentara supports the following signature algorithms:
The Xentara Web Service supports JSON Web Key (JWK) Sets. Many authentication providers do not supply encryption keys, but JWK Sets, which allows for rotating the signing key.
A JWK Set is a JSON file that contains one or more public keys. This JSON file can generally be downloaded from the authentication provider, and must be copied to the host on which Xentara is running.