Format of the OAuth 2.0 Configuration File

Table of Contents

• The Top-Level OAuth 2.0 Configuration Object
• Issuer Objects
• The Authorization Claims Object
• Verification Object
  • Public Key Verification
  • Verification Using a JSON Web Key Set
• The Non-Conformance Options Object
• JSON Schema

The Top-Level OAuth 2.0 Configuration Object

The Xentara OAuth 2.0 configuration file consists of a JSON object containing the OAuth 2.0 configuration:

{
  "$schema": "https://docs.xentara.io/xentara/schema-xentara-oauth2.json",
  "scope": [ "com.mycompany:xentara" ],
  "issuers": {
    ...
  }
}

Object Members

$schema	An optional string value containing the URI of the JSON schema for Xentara OAuth 2.0 configuration files. Xentara itself ignores this member, but some editors may use it to associate the model file with the correct JSON schema. The schema schould always point to https://docs.xentara.io/xentara/schema-xentara-oauth2.json.
scope	An optional JSON array containing the default 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 default scope can usually be overridden for individual services in the corresponding service configuration. The array can contain as few or as many scope strings as desired. If you do not specify this member, or if you specify an empty array, no scope checking will be performed, and no scope will be sent in the WWW-Authenticate header.
issuers	An optional JSON array containing the issuers that are allowed to issue authorization tokens for Xentara. The array can contain as few or as many issuers as desired. If the array is empty, or if you do not specify this member, then no issuers are available and OAuth 2.0 authorization is not possible. The format for the individual objects contained in this array is described below.

Issuer Objects

A JSON object describing an individual OAuth 2.0 issuer has the following syntax:

{
  "iss": "https://oauth2.mycompany.com/",
  "aud": "Xentara",
  "roles": [ "Operator", "Remote User" ],
  "authorizationClaims": {
    ...
  },
  "verification": {
    ...
  },
  "nonConformance": {
    ...
  }
}

Object Members

iss	A string value containing the value of the iss (issuer) claim used by the issuer.
aud	A string value containing the value of the aud (audience) claim used by the issuer to denote authorizations for Xentara.
roles	An optional JSON array containing the names of additional roles assigned to client that are authorized by this issuer. The roles specified here are assigned in addition to the roles assigned through authorization claims. The role “Everyone” is assigned automatically to any authorized client, and should not appear in this array. If this array is empty, or of you do not specify this parameter, then clients authorized by this issuer will only be assigned the role “Everyone”, as well as any roles assigned through authorization claims.
authorizationClaims	An optional JSON object defining the authorization claims for the issuer. The format for this object is described below.
verification	A JSON object specifying the method used to verify the signature of the token. The format of this object is described below.
nonConformance	An optional JSON object containing options for allowing non-conformant tokens. The format of this object is described below. If you do not specify this member, then only tokens strictly conforming to RFC 9068 will be accepted.

The Authorization Claims Object

A JSON object describing the authorization claims of an OAuth 2.0 issuer has the following syntax:

"authorizationClaims": {
  "groups": {
    "User": [ "Observer" ],
    "Eng": [ "Operator" ],
    "Admin": [ "Operator", "Administrator" ]
  },
  "roles": "implicit"
}

The authorization claims object contains one member for each authorization claim. The name of the member must be the name of the corresponding authorization claim (roles, groups, entitlements, etc.).

The value of each member must be one of two things:

• For an explicit mapping, the value must itself be a JSON object that maps each claim value to an array of roles. Unknown role names are ignored with a warning.
• For an implicit mapping, the value must be the string "implicit" (in quotes).

Verification Object

The verification is represented by a double nested JSON object. The outer object has a single member whose name is the verification method, and whose value is another JSON object that contains the actual verification parameters.

Public Key Verification

Public key verifies the signature using the known public key of the issuer. The JSON object describing public key verification has the following syntax:

"verification": {
  "@RS512": {
    "keyFile": "mycompany/public-key.pem"
  }
}

Method Descriptor

The verification method descriptor in the outer JSON object specifies the algorithm the issuer uses to sign the authentication token. The following algorithms are supported:

Descriptor	Algorithm
"@PS256"	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
"@PS384"	RSASSA-PSS using SHA-384 and MGF1 with SHA-384
"@PS512"	RSASSA-PSS using SHA-512 and MGF1 with SHA-512
"@ES256"	ECDSA using P-256 and SHA-256
"@ES256K"	ECDSA using secp256k1 and SHA-256
"@ES384"	ECDSA using P-384 and SHA-384
"@ES512"	ECDSA using P-521 and SHA-512
"@EdDSA"	EdDSA, using either Curve25519 or Curve448
"@RS256"	RSASSA-PKCS1-v1_5 using SHA-256
"@RS384"	RSASSA-PKCS1-v1_5 using SHA-384
"@RS512"	RSASSA-PKCS1-v1_5 using SHA-512
"@HS256"	HMAC using SHA-256
"@HS384"	HMAC using SHA-384
"@HS512"	HMAC using SHA-512

Inner Object Members

keyFile

A string value containing the path to the file containing the issuer’s public key. If the path is relative, the public key file is searched for as described under Public Key File Location. For all algorithms except HMAC, the public key file must contain the public key in PEM format. For HMAC, the file must contain the unencoded binary HMAC secret.

Verification Using a JSON Web Key Set

Public key verifies the signature using a JSON Web Key Set.

"verification": {
  "@JWKS": {
    "jwksFile": "mycompany/jwks.json"
  }
}

Method Descriptor

The verification method descriptor in the outer JSON object must be @JWKS for JSON Web Key Set verification.

Inner Object Members

keyFile

An string value containing the path to a locally stored copy of the issuer’s JWK set file. If the path is relative, the JWK set file is searched for as described under JWK Set File Location.

The Non-Conformance Options Object

The JSON object describing the non-conformance options for an OAuth 2.0 issuer has the following syntax:

"nonConformance": {
  "allowGenericJwt": true,
  "allowMissingTyp": true,
  "allowMissingIat": true,
  "allowMissingExp": true,
  "allowMissingSub": true,
  "allowMissingClientId": true,
  "allowMissingJti": true
}

Object Members

allowGenericJwt	An optional Boolean value specifying whether to allow a non-conformant value of “JWT” for the typ (type) header parameter, in addition to the conformant “at+jwt” or “application/at+jwt”. Please note that the typ header parameter is not case sensitive, so “jwt” and “Jwt” etc. will be accepted as well if you set this option. If you do not specify this member, then tokens with the generic type “JWT” will be rejected, as required by section 4 of RFC 9068.
allowMissingTyp	An optional Boolean value specifying whether to accept non-conformant tokens without a typ (type) header parameter. If you do not specify this member, then tokens without a typ header parameter will be rejected, as required by section 4 of RFC 9068.
allowMissingIat	An optional Boolean value specifying whether to accept non-conformant tokens without an iat (assued at) claim. If you do not specify this member, then tokens without an iat claim will be rejected, as required by section 2.2 of RFC 9068.
allowMissingExp	An optional Boolean value specifying whether to accept non-conformant tokens without an exp (expiration time) claim. If you do not specify this member, then tokens without an exp claim will be rejected, as required by section 2.2 of RFC 9068.
allowMissingSub	An optional Boolean value specifying whether to accept non-conformant tokens without a sub (subject) claim. If you do not specify this member, then tokens without a sub claim will be rejected, as required by section 2.2 of RFC 9068.
allowMissingClientId	An optional Boolean value specifying whether to accept non-conformant tokens without a client_id (client identifier) claim. If you do not specify this member, then tokens without a client_id claim will be rejected, as required by section 2.2 of RFC 9068.
allowMissingJti	An optional Boolean value specifying whether to accept non-conformant tokens without a jti (JWT ID) claim. If you do not specify this member, then tokens without a jti claim will be rejected, as required by section 2.2 of RFC 9068.

JSON Schema

A JSON schema file to validate OAuth 2.0 configuration files is available here.