OAuth2

The OAuth2 specification defines the process for a server to grant an access token to a client to enable the client to access a resource.

• The client presents the access token to the resource server and if the resource server determines that the token is valid the it provides access.
• OAuth2 does not specify the structure of the token or how the token is distributed to the resource server.

RFC 7519 defines JSON Web Tokens (JWT).

• These are tokens containing required and optional fields defined in a JSON format.
• The encryption and authentication of these tokens are defined in the JOSE specifications also developed by the IETF.

The usage of this format in the context of Example takes place in the following order:

1. The client wishing to access a resource makes a request to the OAuth2 server.
2. The OAuth2 server issues a token in the format described in this document. This token is signed using the authorization server's private key.
3. The client presents the token to the server, requesting access to a resource.
4. The server checks the X.509 certificate that is referenced in the token and validates the contents of the token using the public key referenced in the OAuth2 server’s X.509 certificate.
5. The server shall also check the fields to check the whether the token should provide access to the resource. For example are the valid to and not before fields within the current date.

▲ Top

RFC 7519

The RFC 7519 specification defines the specific usage of fields defined in this RFC.

Authentication

The token shall be authenticated using the ES256 algorithm (ECDSA using P-256 and SHA-256).

• The identification of the Public Key to be used to authenticate the message shall be carried using an X.509 certificate.
• This certificate shall be validated against the Example LA Root Certificate.

Fields

The following example shows the JWT structure that the Example LA would generate to enable the Example account service to access a specific Example device.

• Similar tokens would be generated for Apps to access a user’s account or devices.
• The fields described below will always be present.
• The values in the fields will depend on:
  • Who is issuing the token.
  • Who is expected to receive the token.
  • Who is going to use the token.

The following is the payload of the token.

• All the fields defined below are required when used in the Example ecosystem.
• The token shall be encrypted using the Public Key of the device and signed with the Private Key of the issuing authority (Example LA or Example Account Service).

{
  "title": "Access Token",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "iss": {
      "type": "string",
      "description": "Issuer of Token"
    },
    "sub": {
      "type": "string",
      "description": "Subject of Token"
    },
    "aud": {
      "type": "string",
      "description": "Audience for Token"
    },
    "exp": {
      "type": "string",
      "description": "Expiry date of token"
    },
    "nbf": {
      "type": "string",
      "description": "Not valid before this date"
    },
    "iat": {
      "type": "string",
      "description": "Date of Issue"
    },
    "jti": {
      "type": "string",
      "description": "JSON Token ID unique identifier for this token. This should be checked against revoked tokens for the device before accepting. "
    }
  }
}

Referring to the above payload JSON code example:

• The "iss" field refers to the party generating the JWT. In this example the issuer is the Example LA.
• The "sub" field refers to the party that is going to use the token to access a service or a device.
  • In this example the Example Account service will use the token to log into a device to enable the Example Account Service to automatically configure the device to work with a specific account.
• The "aud" field refers to the party that will receive and validate the token.
  • In the case that the token is validated, the party shall grant access to the holder of the token.
  • In this example the device is the audience.
• The "exp" field refers to the expiry date for the token.
  • After this time the token shall not be accepted.
• The "nbf" field refers to the date before which the token is not valid.
• The "iat" field refers to the date of issue of the token.
• The "jti" field is a unique ID for the token.
  • A specific token can be revoked using the Credential Object for the device issued by the Example LA or Example Account Service.
  • The device must check this field against the revocation list delivered in the Credential Object.

Types of Tokens

The following token types are used in the Example ecosystem:

1. A token issued by the Example LA to enable a Example Account Service to access a Example device.
2. A token issued by a Example Account Service to enable access to either a Example device or to a Example account managed by the Example Account Service.

   Field	Type: Example LA to Enable Access to Example Device	Type: Example Account Service to Allow Access to Account
   "iss"	Example LA	Example Account Service Name
   "sub"	Example Account Service Name	App ID Example Service ID
   "aud"	Example Unique Device ID	Example Account ID Example Unique Device ID

The device receiving the token shall ensure that the following matches:

• "iss" is the same as either the Master Issuer ID provided during manufacture or the Example Account Service ID provided when the device is associated with an end user account.
• "aud" is the Unique ID of the device.
• The entity identified in the "iss" field should match the X.509 certificate for the entity and the public key carried in that X.509 certificate shall be used to verify the token.

▲ Top

JOSE (JavaScript Object Signing and Encryption) specifications

Any JSON object defined for Privacy Rights Management or for Network Security shall be encrypted in accordance to the JOSE Specifications for JSON encryption and authentication.

• The JOSE specifications refer to two types of serialization.
• For the purposes of Example the JWS serialization shall be used.

The following describes the specific methods and algorithms that should be applied in the context of the Example specification.

• The handling of the signing of JSON objects shall be implemented according to RFC 7516 .
• The public keys for the actors in the Example system shall comply with the X.509 structure for digital certificates.
• RFC 7516 provides the linkage between the signed JSON object and the relevant X.509 certificates.

There are two categories of JSON objects:

1. Individually addressed objects that can only be processed by a specific entity (device, app, or service). All Network Security and Privacy Rights objects are of this category.
2. Objects that can be accessed by multiple entities. These are typically Device Data objects and media files. These are encrypted under Content Encryption Keys that are distributed via Privacy Rights Objects.

The following parameters defined in RFC 7516 are compulsory for individually addressed JSON objects:

• "alg" (Algorithm) Header Parameter
• "enc" (Encryption Algorithm) Header Parameter
• "zip" (Compression Algorithm) Header Parameter
• "kid" (Key ID) Header Parameter
• "x5c" (X.509 Certificate Chain) Header Parameter

For DeviceData the "x5c" is not present as the encryption and signing of the JSON utilizes symmetric cipher.

The following is the high level structure of the signed message. The above parameters are carried in the JOSE header.

For the individually addressed objects the following settings shall be used:

"alg":"ECDH-ES+A256KW"
"enc":"A256GCM"

The specific definitions of these algorithms can be found in RFC 7518 .

For JSON objects carrying Device data the following settings shall be used:

"alg":"A256GCMKW"
"enc":"A256GCM"

Note: Any message which indicated a different algorithm shall not be processed.

The key used to wrap the Content Encryption is identified by the value defined by "kid".

• These keys are carried in the Privacy Rights objects and the "kid" is a unique value in the context of a single Privacy Management system.
• Certain fields in the security objects must be accessible when the JSON object is encrypted.
• These are carried in the protected header section of the JSON object (according to the JWE specification, these are covered by the signature of the object but are not encrypted).
• These fields are indicated in the JSON schemas for the JSON security objects.

▲ Top