Add token introspection feature as a policy. [THREESCALE-312]

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## Added
 
 - New property `summary` in the policy manifests [PR #633](https://github.com/3scale/apicast/pull/633)
+- OAuth2.0 Token Introspection policy [PR #619](https://github.com/3scale/apicast/pull/619)
 
 ## Fixed
 

examples/policies/token_introspection_configuration.lua

@@ -0,0 +1,14 @@
+local policy_chain = require('apicast.policy_chain').default()
+
+local token_policy = require('apicast.policy.token_introspection').new({
+        introspection_url = "http://localhost:8080/auth/realms/3scale/protocol/openid-connect/token/introspect",
+        client_id = "YOUR_CLIENT_ID",
+        client_secret = "YOUR_CLIENT_SECRET"
+})
+
+policy_chain:insert(token_policy)
+
+return {
+        policy_chain = policy_chain
+}
+

gateway/src/apicast/policy/token_introspection/apicast-policy.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://apicast.io/poolicy-v1/schema#manifest#",
+  "name": "oauth2 token introspection policy",
+  "description": 
+  ["This policy executes OAuth 2.0 Token Introspection",
+   "(https://tools.ietf.org/html/rfc7662) for every API calls."],
+  "version": "builtin",
+  "configuration": {
+    "type": "object",
+    "properties": {
+      "introspection_url": {
+        "description": "Introspection Endpoint URL",
+        "type": "string"
+      },
+      "client_id": {
+        "description": "Client ID for the Token Introspection Endpoint",
+        "type": "string"
+      },
+      "client_secret": {
+        "description": "Client Secret for the Token Introspection Endpoint",
+        "type": "string"
+      }
+    }
+  }
+}

gateway/src/apicast/policy/token_introspection/init.lua

@@ -0,0 +1 @@
+return require('token_introspection')

gateway/src/apicast/policy/token_introspection/token_introspection.lua

@@ -0,0 +1,71 @@
+local policy = require('apicast.policy')
+local _M = policy.new('Token Introspection Policy')
+
+local cjson = require('cjson.safe')
+local http_authorization = require 'resty.http_authorization'
+local http_ng = require 'resty.http_ng'
+local user_agent = require 'apicast.user_agent'
+local resty_env = require('resty.env')
+
+local new = _M.new
+
+function _M.new(config)
+  local self = new()
+  self.config = config or {}
+  --- authorization for the token introspection endpoint.
+  -- https://tools.ietf.org/html/rfc7662#section-2.2
+  local credential = 'Basic ' .. ngx.encode_base64(table.concat({ self.config.client_id or '', self.config.client_secret or '' }, ':'))
+  self.introspection_url = config.introspection_url
+  self.http_client = http_ng.new{
+    backend = config.client,
+    options = {
+      headers = {
+        ['User-Agent'] = user_agent(),
+        ['Authorization'] = credential
+      },
+      ssl = { verify = resty_env.enabled('OPENSSL_VERIFY') }
+    }
+  }
+  return self
+end
+
+--- OAuth 2.0 Token Introspection defined in RFC7662.
+-- https://tools.ietf.org/html/rfc7662
+local function introspect_token(self, token)
+  --- Parameters for the token introspection endpoint.
+  -- https://tools.ietf.org/html/rfc7662#section-2.1
+  local res, err = self.http_client.post(self.introspection_url , { token = token, token_type_hint = 'access_token'})
+  if err then
+    ngx.log(ngx.WARN, 'token introspection error: ', err, ' url: ', self.introspection_url)
+    return { active = false }
+  end
+
+  if res.status == 200 then
+    local token_info, decode_err = cjson.decode(res.body)
+    if type(token_info) == 'table' then
+      return token_info
+    else 
+      ngx.log(ngx.ERR, 'failed to parse token introspection response:', decode_err)
+      return { active = false }
+    end
+  else
+    ngx.log(ngx.WARN, 'failed to execute token introspection. status: ', res.status)
+    return { active = false }
+  end
+end
+
+function _M:access(context)
+  if self.introspection_url then
+    local authorization = http_authorization.new(ngx.var.http_authorization)
+    local access_token = authorization.token
+    --- Introspection Response must have an "active" boolean value.
+    -- https://tools.ietf.org/html/rfc7662#section-2.2
+    if not introspect_token(self, access_token).active == true then
+      ngx.status = context.service.auth_failed_status
+      ngx.say(context.service.error_auth_failed)
+      return ngx.exit(ngx.status)
+    end
+  end
+end
+
+return _M

spec/policy/token_introspection/token_introspection_spec.lua

@@ -0,0 +1,184 @@
+local test_backend_client = require('resty.http_ng.backend.test')
+local cjson = require('cjson')
+describe("token introspection policy", function()
+  describe("execute introspection", function()
+    local context
+    local test_backend
+    local test_access_token = "test"
+    local test_client_id = "client"
+    local test_client_secret = "secret"
+    local test_basic_auth = 'Basic '..ngx.encode_base64(test_client_id..':'..test_client_secret)
+
+    local function assert_authentication_failed()
+      assert.same(ngx.status, 403)
+      assert.stub(ngx.say).was.called_with("auth failed")
+      assert.stub(ngx.exit).was.called_with(403)
+    end
+
+    before_each(function()
+      test_backend = test_backend_client.new()
+      ngx.var = {}
+      ngx.var.http_authorization = "Bearer "..test_access_token
+      context = {
+        service = {
+          auth_failed_status = 403,
+          error_auth_failed = "auth failed"
+        }
+      }
+    end)
+
+    it('success with valid token', function()
+      local introspection_url = "http://example/token/introspection"
+      local policy_config = {
+        client = test_backend,
+        introspection_url = introspection_url,
+        client_id = test_client_id,
+        client_secret = test_client_secret
+      }
+
+      test_backend
+        .expect{
+          url = introspection_url,
+          method = 'POST',
+          body = 'token='..test_access_token..'&token_type_hint=access_token',
+          headers = {
+            ['Authorization'] = test_basic_auth
+          }
+        }
+        .respond_with{
+          status = 200,
+          body = cjson.encode({
+              active = true
+          })
+        }
+      local token_policy = require('apicast.policy.token_introspection').new(policy_config)
+      token_policy:access(context)
+    end)
+
+    it('failed with invalid token', function()
+      local introspection_url = "http://example/token/introspection"
+      local policy_config = {
+        client = test_backend,
+        introspection_url = introspection_url,
+        client_id = "client",
+        client_secret = "secret"
+      }
+
+      test_backend
+        .expect{
+          url = introspection_url,
+          method = 'POST',
+          body = 'token='..test_access_token..'&token_type_hint=access_token',
+          headers = {
+            ['Authorization'] = test_basic_auth
+          }
+        }
+        .respond_with{
+          status = 200,
+          body = cjson.encode({
+              active = false
+          })
+        }
+      stub(ngx, 'say')
+      stub(ngx, 'exit')
+
+      local token_policy = require('apicast.policy.token_introspection').new(policy_config)
+      token_policy:access(context)
+      assert_authentication_failed()
+    end)
+
+    it('failed with bad status code', function()
+      local introspection_url = "http://example/token/introspection"
+      local policy_config = {
+        client = test_backend,
+        introspection_url = introspection_url,
+        client_id = "client",
+        client_secret = "secret"
+      }
+
+      test_backend
+        .expect{
+          url = introspection_url,
+          method = 'POST',
+          body = 'token='..test_access_token..'&token_type_hint=access_token',
+          headers = {
+            ['Authorization'] = test_basic_auth
+          }
+        }
+        .respond_with{
+          status = 404,
+        }
+      stub(ngx, 'say')
+      stub(ngx, 'exit')
+
+      local token_policy = require('apicast.policy.token_introspection').new(policy_config)
+      token_policy:access(context)
+      assert_authentication_failed()
+    end)
+
+    it('failed with null response', function()
+      local introspection_url = "http://example/token/introspection"
+      local policy_config = {
+        client = test_backend,
+        introspection_url = introspection_url,
+        client_id = "client",
+        client_secret = "secret"
+      }
+
+      test_backend
+        .expect{
+          url = introspection_url,
+          method = 'POST',
+          body = 'token='..test_access_token..'&token_type_hint=access_token',
+          headers = {
+            ['Authorization'] = test_basic_auth
+          }
+        }
+        .respond_with{
+          status = 200,
+          body = 'null'
+        }
+      stub(ngx, 'say')
+      stub(ngx, 'exit')
+
+      local token_policy = require('apicast.policy.token_introspection').new(policy_config)
+      token_policy:access(context)
+      assert_authentication_failed()
+    end)
+
+    it('failed with bad contents type', function()
+      local introspection_url = "http://example/token/introspection"
+      local policy_config = {
+        client = test_backend,
+        introspection_url = introspection_url,
+        client_id = "client",
+        client_secret = "secret"
+      }
+
+      test_backend
+        .expect{
+          url = introspection_url,
+          method = 'POST',
+          body = 'token='..test_access_token..'&token_type_hint=access_token',
+          headers = {
+            ['Authorization'] = test_basic_auth
+          }
+        }
+        .respond_with{
+          status = 200,
+          body = "<html></html>"
+        }
+      stub(ngx, 'say')
+      stub(ngx, 'exit')
+
+      local token_policy = require('apicast.policy.token_introspection').new(policy_config)
+      token_policy:access(context)
+      assert_authentication_failed()
+    end)
+
+    after_each(function()
+      test_backend.verify_no_outstanding_expectations()
+    end)
+  end)
+end)
+