 |
Xentara v2.0.3
User Manual
|
|
Xentara v2.0.3
User Manual
|
OAuth 2.0 uses JSON Web Tokens (JWTs) to encapsulate authorization information. A JWT contains a header with a number of parameters and a digital signature, as well as a list of so called “claims” that describe the authorization necessary.
Xentara normally checks that the typ (type) header parameter in the JWT is correct. The parameter must normally have the value “at+jwt” or “application/at+jwt”, as specified in section 4 of RFC 9068.
Please note that the typ header parameter is not case sensitive, so “AT+JWT” and “At+Jwt” etc. will be accepted as well.
Some token issuers issue JWTs with non-conformant typ (type) parameters. For such issuers, Xentara can be configured to accept “JWT” as value for the typ parameter, or to accept tokens without any typ parameter at all.
Xentara checks the following claims in a provided JWT:
| Claim Name | Claim Description |
|---|---|
| iss | issuer |
| aud | audience |
| iat | issued at |
| exp | expiration time |
| nbf | not before |
| scope | scope |
| sub | subject |
| client_id | client identifier |
| jti | JWT ID |
The allowable values for the iss (issuer) and aud (audience) claims for the individual issuers must be specified in the Xentara OAuth 2.0 configuration file.
The exp (expiration time) and nbf (not before) claims are checked against the current time, with a small leeway to account for transmission delays and clock skew. The iat (issued at) claim is also checked against the current time.
The scope claim, if present, is checked against the list of required scope strings. The list of required scope strings depends on the service the client is using to connect, but a default list of scope strings can be specified in the Xentara OAuth 2.0 configuration file. This default can usually be overridden in the configuration of the individual services, however.
The sub (subject), client_id (client identifier), and jti (JWT ID) claims must be present, as specified in section 2.2 of RFC 9068. The claim values must be strings, but their values are not checked.
Some token issuers may issue JWTs missing some claims required by RFC 9068. For such issuers, Xentara can be configured to accept JWTs missing specific claims. The iss (issuer) and aud (audience) claims are always required, however.
Normally, an authorized client will have the built-in role “Everyone”, plus a list of additional roles configured for the issuer that issued the token. To get more fine-grained control over the roles an authorized client will have, additional authorization claims can be specified. These claims are checked to assign additional roles to the client. Typically, the following claims defined in the JSON Web Token claims registry are used as authorization claims:
| 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 OAuth 2.0 configuration file, however.
For each authorization claim, the individual claim values are mapped to one or more Xentara roles. If the claim value is an array and contains more than one string, then each element is mapped individually, and the resulting roles are combined.
There are two types of mappings available for authorization claims: explicit mappings end implicit mappings.
In an explicit mapping, individual claim values are mapped explicitly to one or more roles. If the claim contains one or more of the mapped values, then the client is assigned the corresponding roles. Unknown claim values are silently ignored.
The mapping from claim values to roles can be completely arbitrary. The following explicit mapping may be defined for the groups claim, for example:
| Claim Value | Xentara Role |
|---|---|
| User | Observer |
| Eng | Operator |
| Admin | Operator, Administrator |
In this example, a claim value of “User” will give the client the additional Xentara role “Observer”, a cliam value of “Eng” will give the client the additional Xentara roles “Operator”, and a cliam value of “Admin” will the client the two additional Xentara roles “Operator” and “Administrator”. If the claim is an array containing, say, “User” and “Eng”, then the client will be assigned the roles for both values, i.e. “Observer” and “Operator”.
Another way is to map claim values to Xentara roles of the same name. The following explicit mapping may be defined for the roles claim, for example:
| Claim Value | Xentara Role |
|---|---|
| User | User |
| Engineering | Engineering |
| Administrator | Administrator |
In this example, claim values of “User”, “Engineering”, and “Administrator” will be mapped to Xentara roles of the same name. Other claim values will be silently ignored, even if they match the name of a Xentara role.
The two types of explicit mappings can be mixed, of course, so that some claim values are arbitrary, and other match the names of Xentara roles.
In an implicit mapping, any claim value is directly mapped to a Xentara role of the same name. Claim values that do not correspond to the name of a xentara role are silently ignored.
An implicit mapping is similar to an explicit mapping that maps claim values to xentara roles of the same name. Whereas an explicit mapping restricts the roles the issuer can assign to the specified values, an implicit mapping allows the issuer to assign any arbitrary role to a client. This gives the issuer complete control control over the client’s access rights, and should thus only be used for issuers you trust completely.