CDNI Client Access Control Metadata

6.1.1. MI.CATTokenLocator

The MI.CATTokenLocator object defines the location to read one or more tokens from the client request.¶

Property: location¶

• Description: Specifies the location name to find one or more tokens in the client request. Valid location names are:¶

  • "Authorization-Header" for the Authorization request header¶

  • "url-path-style-parameter" per [RFC6570], section 3.2.7.¶

  • "query-parameter" per [RFC6570], section 3.2.8 and [RFC6570], section 3.2.9¶

  • "cookie" for HTTP Cookies¶

• Type: String¶

• Mandatory-to-Specify: Yes¶

Property: scheme¶

• Description: The scheme for the Authorization request header that contains the CAT token¶

• Type: String¶

• Mandatory-to-Specify: Yes, only if the location property is ‘Authorization-Header'. Otherwise, his property is ignored.¶

Property: names¶

• Description: The names of the url-path-style parameter, query parameter or HTTP cookies that contain one or more CAT tokens.¶

• Type: String¶

• Mandatory-to-Specify: Yes, only if the location property is either ‘url-path-style-parameter', ‘query-parameter', or ‘cookie'. Otherwise, his property is ignored.¶

6.1.2. MI.CATTokenConfiguration

The MI.TokenConfiguration object defines the configuration parameters for verifying a CAT token.¶

Property: integrity-algo¶

• Description: The algorithm used for integrity protection of the CAT token. The minimum set of values to support are "hs256" (see [RFC9053], section 3.1)and "es256" (see [RFC9053], section 2.1)¶

• Type: String¶

• Mandatory-to-Specify: Yes¶

Property: integrity-algo-key¶

• Description: The value of the key used for integrity protection of the CAT token.¶

• Type: MI.SecretValue object that can either contain the hex version of the key in the clear (not recommended) or as a reference in an external key store. See the Protected Secrets Metadata standard [I-D.ietf-cdni-protected-secrets-metadata] for more details.¶

• Mandatory-to-Specify: Yes.¶

Property: encryption-algo¶

• Description: The algorithm used in the ‘enc' claim. The minimum value to support is "ecdh-ss+a128kw" (see [RFC9053], section 6.4.1).¶

• Type: MI.SecretValue object that can either contain the hex version of the symmetric key in the clear (not recommended) or as a reference in an external key store. See the Protected Secrets Metadata standard [I-D.ietf-cdni-protected-secrets-metadata] for more details.¶

• Mandatory-to-Specify: Yes¶

Property: encryption-algo-key¶

• Description: The value of the key used for encryption in the ‘enc' claim.¶

• Type: MI.SecretValue object that can either contain the hex version of the key in the clear (not recommended) or as a reference in an external key store. See the Protected Secrets Metadata standard [I-D.ietf-cdni-protected-secrets-metadata] for more details.¶

• Mandatory-to-Specify: Yes¶

6.1.3. MI.CATTokenVerificationAction

The MI.CATTokenVerificationAction object defines how a client response is created for an invalid OR valid but rejected token.¶

Property: rejected-token-action¶

• Description: An enumeration of ways in which a client response is created. Valid values are:¶

  • "fail" for returning a HTTP 403 response.¶

  • "allow" for ignoring the result of token validation, as if the token was not present. This typically would result in serving a HTTP 200 for the requested resource.¶

  • "token-defined" for constructing the client response per the parameters defined within the token. For a valid but rejected CAT token, the ‘catif' claim is used to construct the client response.¶

• Type: String¶

• Mandatory-to-Specify: Yes¶

Property: token-defined-response¶

• Description: Specifies how the token values are used to create the client response for an invalid OR valid but rejected token. This property gets used when the value of ‘rejected-token-action' property is ‘token-defined'. Use of this property for any other value of ‘rejected-token-action' is an invalid configuration.¶

• Type: MI.CATTokenDefinedResponse object¶

• Mandatory-to-Specify: Yes, if ‘rejected-token-action' property is ‘token-defined'¶

6.1.4. MI.CATTokenDefinedResponse

The MI.CATTokenDefinedResponse object defines how a client response is constructed using the token's available ‘catif' claim or some fallback.¶

Property: fallback-response¶

• Description: An enumeration defining a fallback response when the token defined values are inapplicable. Valid values are:¶

  • "fail" for returning a HTTP 403 response.¶

  • "allow" for ignoring the result of token validation, as if it was not present.¶

    • A missing token.¶

    • An invalid CAT token.¶

    • A valid but rejected CAT token with:¶

For CAT, this fallback-response will get used under the following conditions:¶

• Type: String¶

• Mandatory-to-Specify: No. Default value is ‘fail'.¶

Property: catif¶

• Description: Specifies the configuration for processing the ‘catif' claim to construct the client response for a valid but rejected CAT token.¶

• Type: MI.CATIF object¶

• Mandatory-to-Specify: Yes, when the rejected-token-action property for the MI.CATTokenVerificationAction object is set to ‘token-defined'¶

6.1.5. MI.CATIF

The MI.CATIF object specifies the processing of the ‘catif' claim to construct the client response for a valid but rejected CAT token. See Section 4.9.1 of [CTA-5007]¶

Property: response-header-names-force-add¶

• Description: For specific named headers of a rejected claim within the ‘catif' claim, these will be added to the client response, even if headers with same names were already going to be added to the response via other means.¶

• Type: Array of Strings¶

• Mandatory-to-Specify: No. If not specified, header names of a rejected claim within ‘catif' claim will be skipped in the client response if similarly named headers were to be added via other means.¶

6.1.6. MI.CATTokenObject

The MI.CATTokenObject object defines a read-only object that captures the results of the token verification. The verification result is available for inspection in all processing stages [I-D.goldstein-processing-stages-metadata]¶

Property: status¶

• Description: Captures the verification status of the CAT token via the following string values:¶

  • ‘success'¶

  • ‘failure'¶

• Type: String¶

Property: token¶

• Description: The string literal of the token in the request.¶

• Type: String¶

Property: status_details¶

• Description: Specifies details about the token verification result when the token verification ‘status' is ‘failure', else it is an empty string. This string contains one of the following values:¶

  • Empty string for a missing token.¶

  • "Invalid CAT" when a token cannot be parsed, per [RFC8392], Section 7.2¶

  • "Invalid Claim: <name of the first claim that caused the CAT token to be rejected>"¶

• Type: String¶

The following example shows use of the CAT scheme as the authentication mechanism for client requests at the dCDN. Some notable points are:¶

[
  {
    "generic-metadata-type": "MI.ClientAuthMetadata",
    "generic-metadata-value": {
      "delivery-auth": {
        "generic-metadata-type": "MI.Auth",
        "generic-metadata-value": {
          "auth-type": "MI.CommonAccessToken",
          "auth-value": {
            "version": 1,
            "token-object-name": "cat_1",
            "tokens": [
              {
                "location": "Authorization-Header",
                "scheme": "CAT"
              },
              {
                "location": "url-path-style-parameter",
                "names": [
                  "catv1"
                ]
              },
              {
                "location": "query-parameter",
                "names": [
                  "catv1,catv2"
                ]
              },
              {
                "location": "cookie",
                "names": [
                  "catv1"
                ]
              }
            ],
            "configuration": {
              "integrity-algo": "hs256",
              "integrity-algo-key": {
                "secret-store-id": "cat-key-vault",
                "secret-path": "/client-auth/cat/keys/integrity/dplus"
              },
              "encryption-algo": "ecdh-ss+a128kw",
              "encryption-algo-key": {
                "secret-store-id": "cat-key-vault",
                "secret-path": "/client-auth/cat/keys/enc/dplus"
              }
            },
            "verification-action": {
              "rejected-token-action": "token-defined",
              "token-defined-response": {
                "fallback-response": "fail",
                "catif": {
                  "response-header-names-force-add": [
                    "x-cat-reason",
                    "x-uCDN-name"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  {
    "generic-metadata-type": "MI.ProcessingStages",
    "generic-metadata-value": {
      "client-response": [
        {
          "match": "var.cat_1 and var.cat_1.status == 'failure'",
          "stage-metadata": {
            "response-transform": {
              "header-transform": {
                "add": [
                  {
                    "name": "x-auth-error",
                    "value": "'Invalid token' . var.cat_1.token .
                             'failed verification. Error:' .
                              var.cat_1.status_details",
                    "value-is-expression": true
                  }
                ]
              }
            }
          }
        }
      ]
    }
  }
]