[fapi] Support OAuth 2.0 MTLS and Certificate-Bound Access Tokens

Author: tkan145

CHANGELOG.md

@@ -15,7 +15,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Bump openresty to 1.21.4.3 [PR #1461](https://github.com/3scale/APIcast/pull/1461) [THREESCALE-10601](https://issues.redhat.com/browse/THREESCALE-10601)
 
-- Support Financial-grade API (FAPI) - Baseline profile [PR #1465](https://github.com/3scale/APIcast/pull/1465) [THREESCALE-10973](https://issues.redhat.com/browse/THREESCALE-10973)
+- Support Financial-grade API (FAPI) 1.0 - Baseline profile [PR #1465](https://github.com/3scale/APIcast/pull/1465) [THREESCALE-10973](https://issues.redhat.com/browse/THREESCALE-10973)
+
+- Support Financial-grade API (FAPI) 1.0 - Advance profile [PR #1465](https://github.com/3scale/APIcast/pull/1466) [THREESCALE-11019](https://issues.redhat.com/browse/THREESCALE-11019)
 
 ## [3.15.0] 2024-04-04
 

gateway/src/apicast/policy/fapi/README.md

@@ -3,6 +3,8 @@
 ## Description
 
 The FAPI policy supports various features of the Financial-grade API (FAPI) standard.
+* FAPI 1.0 Baseline Profile
+* FAPI 1.0 Advance Profile
 
 ## Example configuration
 
@@ -30,3 +32,19 @@ The FAPI policy supports various features of the Financial-grade API (FAPI) stan
     }
 ]
 ```
+
+### Validate certificate-bound access tokens
+
+```
+"policy_chain": [
+    {
+      "name": "apicast.policy.fapi",
+      "configuration": {
+        "enable_oauth2_mtls": true
+      }
+    },
+    {
+      "name": "apicast.policy.apicast"
+    }
+]
+```

gateway/src/apicast/policy/fapi/apicast-config.json

@@ -9,7 +9,12 @@
     "type": "object",
     "properties": {
       "validate_x_fapi_customer_ip_address": {
-        "description": "Validate x-fapi-customer-ip-address header",
+        "description": "Validate x-fapi-customer-ip-address header. If the verification fails, the request will be rejected with 403",
+        "type": "boolean",
+        "default": "false"
+      },
+      "enable_oauth2_mtls ": {
+        "description": "Configure OAuth 2.0 Mutual TLS Client Authentication.If enable, all tokens are verified and must contain the certificate hash claim. If the verification fails, the request will be rejected with 401.",
         "type": "boolean",
         "default": "false"
       }

gateway/src/apicast/policy/fapi/fapi.lua

@@ -1,16 +1,27 @@
 --- Financial-grade API (FAPI) policy
+-- Current support the following profile:
+--    FAPI 1.0 - Baseline profile
+--    FAPI 1.0 - Advance profile
 
 local policy = require('apicast.policy')
 local _M = policy.new('Financial-grade API (FAPI) Policy', 'builtin')
 
 local uuid = require 'resty.jit-uuid'
 local ipmatcher = require "resty.ipmatcher"
+local X509 = require('resty.openssl.x509')
+local b64 = require('ngx.base64')
 local fmt = string.format
 
 local new = _M.new
 local X_FAPI_TRANSACTION_ID_HEADER = "x-fapi-transaction-id"
 local X_FAPI_CUSTOMER_IP_ADDRESS = "x-fapi-customer-ip-address"
 
+-- The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header
+-- Parameter is a base64url encoded SHA-256 thumbprint (a.k.a. digest)
+-- of the DER encoding of the X.509 certificate.
+-- https://tools.ietf.org/html/rfc7515#section-4.1.8
+local header_parameter = 'x5t#S256'
+
 local function is_valid_ip(ip)
   if type(ip) ~= "string" then
     return false
@@ -29,16 +40,30 @@ local function error(status_code, msg)
   ngx.exit(ngx.status)
 end
 
+local function check_certificate(cert, cnf)
+  if not cert then
+    ngx.log(ngx.DEBUG, "client certificate is not available")
+    return false
+  end
+
+  if not cnf then
+    ngx.log(ngx.DEBUG, "cnf claim is not available")
+    return false
+  end
+  return b64.encode_base64url(cert:digest('SHA256')) == cnf[header_parameter]
+end
+
 --- Initialize FAPI policy
 -- @tparam[config] table config
 -- @field[config] validate_x_fapi_customer_ip_address Boolean
 function _M.new(config)
   local self = new(config)
   self.validate_customer_ip_address = config and config.validate_x_fapi_customer_ip_address
+  self.enable_oauth2_mtls = config and config.enable_oauth2_mtls
   return self
 end
 
-function _M:access()
+function _M:access(context)
   --- 6.2.1.13
   -- shall not reject requests with a x-fapi-customer-ip-address header containing a valid IPv4 or IPv6 address.
   if self.validate_customer_ip_address then
@@ -55,6 +80,17 @@ function _M:access()
       end
     end
   end
+
+  if self.enable_oauth2_mtls then
+    if not context.jwt then return error(context.service or {}) end
+
+    local cert = X509.parse_pem_cert(ngx.var.ssl_client_raw_cert)
+
+    if not check_certificate(cert, context.jwt.cnf) then
+      ngx.log(ngx.WARN, 'fapi oauth_mtls failed for service ', context.service and context.service.id)
+      return error(ngx.HTTP_UNAUTHORIZED, "invalid_token")
+    end
+  end
 end
 
 function _M:header_filter()

spec/policy/fapi/fapi_spec.lua

@@ -1,5 +1,15 @@
 local FAPIPolicy = require('apicast.policy.fapi')
 local uuid = require('resty.jit-uuid')
+local X509 = require('resty.openssl.x509')
+local b64 = require('ngx.base64')
+local clientCert = assert(fixture('CA', 'client.crt'))
+
+local header_parameter = 'x5t#S256'
+
+local function jwt_cnf()
+  local cnf = b64.encode_base64url(X509.parse_pem_cert(clientCert):digest('SHA256'))
+  return { [header_parameter] = b64.encode_base64url(X509.parse_pem_cert(clientCert):digest('SHA256')) }
+end
 
 describe('fapi_1_baseline_profile policy', function()
     local ngx_req_headers = {}
@@ -77,3 +87,78 @@ describe('fapi_1_baseline_profile policy', function()
     end)
   end)
 end)
+
+describe('fapi_1 advance profile', function()
+  local context = {}
+  before_each(function()
+    context = {
+      jwt = {},
+      service = {
+        id = 4,
+        auth_failed_status = 403,
+        error_auth_failed = 'auth failed',
+        auth_failed_headers = 'text/plain; charset=utf-8'
+      }
+    }
+
+    ngx.header = {}
+    stub(ngx, 'print')
+    stub(ngx, 'exit')
+    context.jwt = {}
+  end)
+
+  it('accepts when the digest equals cnf claim', function()
+      ngx.var = { ssl_client_raw_cert = clientCert }
+      context.jwt.cnf = jwt_cnf()
+
+      local fapi_policy = FAPIPolicy.new({enable_oauth2_mtls=true})
+      fapi_policy:access(context)
+      assert.stub(ngx.exit).was_not.called_with(403)
+  end)
+
+  it('rejects when the client certificate not found', function()
+    ngx.var = { ssl_client_raw_cert = nil }
+    context.jwt.cnf = jwt_cnf()
+
+    local fapi_policy = FAPIPolicy.new({enable_oauth2_mtls=true})
+    fapi_policy:access(context)
+
+    assert.stub(ngx.exit).was_called_with(ngx.HTTP_UNAUTHORIZED)
+    assert.stub(ngx.print).was_called_with('{"error": "invalid_token"}')
+  end)
+
+  it('rejects when the cnf claim not defined', function()
+    ngx.var = { ssl_client_raw_cert = clientCert }
+
+    local fapi_policy = FAPIPolicy.new({enable_oauth2_mtls=true})
+    fapi_policy:access(context)
+
+    assert.stub(ngx.exit).was_called_with(ngx.HTTP_UNAUTHORIZED)
+    assert.stub(ngx.print).was_called_with('{"error": "invalid_token"}')
+  end)
+
+  it('rejects when context.service is nil', function()
+    ngx.var = { ssl_client_raw_cert = clientCert }
+
+    local fapi_policy = FAPIPolicy.new({enable_oauth2_mtls=true})
+    context.service = nil
+    fapi_policy:access(context)
+
+    assert.stub(ngx.exit).was_called_with(ngx.HTTP_UNAUTHORIZED)
+    assert.stub(ngx.print).was_called_with('{"error": "invalid_token"}')
+  end)
+
+  it('rejects when the digest not equals cnf claim', function()
+    ngx.var = { ssl_client_raw_cert = clientCert }
+
+    context.jwt.cnf = {}
+    context.jwt.cnf[header_parameter] = 'invalid_digest'
+
+    local fapi_policy = FAPIPolicy.new({enable_oauth2_mtls=true})
+    context.service = nil
+    fapi_policy:access(context)
+
+    assert.stub(ngx.exit).was_called_with(ngx.HTTP_UNAUTHORIZED)
+    assert.stub(ngx.print).was_called_with('{"error": "invalid_token"}')
+  end)
+end)