From b56a8fabbab29bbf3bb07984287aa796055176cb Mon Sep 17 00:00:00 2001 From: "Yann Esposito (Yogsototh)" Date: Fri, 3 Nov 2017 17:03:16 +0100 Subject: [PATCH] initial commit --- .gitignore | 11 + CHANGELOG.md | 24 ++ LICENSE | 214 ++++++++++++++++++ README.md | 155 +++++++++++++ doc/intro.md | 3 + project.clj | 11 + src/ring_homogeneous_auth_middleware/core.clj | 77 +++++++ .../schemas.clj | 60 +++++ .../core_test.clj | 80 +++++++ 9 files changed, 635 insertions(+) create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 doc/intro.md create mode 100644 project.clj create mode 100644 src/ring_homogeneous_auth_middleware/core.clj create mode 100644 src/ring_homogeneous_auth_middleware/schemas.clj create mode 100644 test/ring_homogeneous_auth_middleware/core_test.clj diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c53038e --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +/target +/classes +/checkouts +pom.xml +pom.xml.asc +*.jar +*.class +/.lein-* +/.nrepl-port +.hgignore +.hg/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b336b1f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,24 @@ +# Change Log +All notable changes to this project will be documented in this file. This change log follows the conventions of [keepachangelog.com](http://keepachangelog.com/). + +## [Unreleased] +### Changed +- Add a new arity to `make-widget-async` to provide a different widget shape. + +## [0.1.1] - 2017-11-03 +### Changed +- Documentation on how to make the widgets. + +### Removed +- `make-widget-sync` - we're all async, all the time. + +### Fixed +- Fixed widget maker to keep working when daylight savings switches over. + +## 0.1.0 - 2017-11-03 +### Added +- Files from the new template. +- Widget maker public API - `make-widget-sync`. + +[Unreleased]: https://github.com/your-name/ring-homogeneous-auth-middleware/compare/0.1.1...HEAD +[0.1.1]: https://github.com/your-name/ring-homogeneous-auth-middleware/compare/0.1.0...0.1.1 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d921d3d --- /dev/null +++ b/LICENSE @@ -0,0 +1,214 @@ +THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC +LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM +CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + +1. DEFINITIONS + +"Contribution" means: + +a) in the case of the initial Contributor, the initial code and +documentation distributed under this Agreement, and + +b) in the case of each subsequent Contributor: + +i) changes to the Program, and + +ii) additions to the Program; + +where such changes and/or additions to the Program originate from and are +distributed by that particular Contributor. A Contribution 'originates' from +a Contributor if it was added to the Program by such Contributor itself or +anyone acting on such Contributor's behalf. Contributions do not include +additions to the Program which: (i) are separate modules of software +distributed in conjunction with the Program under their own license +agreement, and (ii) are not derivative works of the Program. + +"Contributor" means any person or entity that distributes the Program. + +"Licensed Patents" mean patent claims licensable by a Contributor which are +necessarily infringed by the use or sale of its Contribution alone or when +combined with the Program. + +"Program" means the Contributions distributed in accordance with this +Agreement. + +"Recipient" means anyone who receives the Program under this Agreement, +including all Contributors. + +2. GRANT OF RIGHTS + +a) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free copyright license to +reproduce, prepare derivative works of, publicly display, publicly perform, +distribute and sublicense the Contribution of such Contributor, if any, and +such derivative works, in source code and object code form. + +b) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free patent license under +Licensed Patents to make, use, sell, offer to sell, import and otherwise +transfer the Contribution of such Contributor, if any, in source code and +object code form. This patent license shall apply to the combination of the +Contribution and the Program if, at the time the Contribution is added by the +Contributor, such addition of the Contribution causes such combination to be +covered by the Licensed Patents. The patent license shall not apply to any +other combinations which include the Contribution. No hardware per se is +licensed hereunder. + +c) Recipient understands that although each Contributor grants the licenses +to its Contributions set forth herein, no assurances are provided by any +Contributor that the Program does not infringe the patent or other +intellectual property rights of any other entity. Each Contributor disclaims +any liability to Recipient for claims brought by any other entity based on +infringement of intellectual property rights or otherwise. As a condition to +exercising the rights and licenses granted hereunder, each Recipient hereby +assumes sole responsibility to secure any other intellectual property rights +needed, if any. For example, if a third party patent license is required to +allow Recipient to distribute the Program, it is Recipient's responsibility +to acquire that license before distributing the Program. + +d) Each Contributor represents that to its knowledge it has sufficient +copyright rights in its Contribution, if any, to grant the copyright license +set forth in this Agreement. + +3. REQUIREMENTS + +A Contributor may choose to distribute the Program in object code form under +its own license agreement, provided that: + +a) it complies with the terms and conditions of this Agreement; and + +b) its license agreement: + +i) effectively disclaims on behalf of all Contributors all warranties and +conditions, express and implied, including warranties or conditions of title +and non-infringement, and implied warranties or conditions of merchantability +and fitness for a particular purpose; + +ii) effectively excludes on behalf of all Contributors all liability for +damages, including direct, indirect, special, incidental and consequential +damages, such as lost profits; + +iii) states that any provisions which differ from this Agreement are offered +by that Contributor alone and not by any other party; and + +iv) states that source code for the Program is available from such +Contributor, and informs licensees how to obtain it in a reasonable manner on +or through a medium customarily used for software exchange. + +When the Program is made available in source code form: + +a) it must be made available under this Agreement; and + +b) a copy of this Agreement must be included with each copy of the Program. + +Contributors may not remove or alter any copyright notices contained within +the Program. + +Each Contributor must identify itself as the originator of its Contribution, +if any, in a manner that reasonably allows subsequent Recipients to identify +the originator of the Contribution. + +4. COMMERCIAL DISTRIBUTION + +Commercial distributors of software may accept certain responsibilities with +respect to end users, business partners and the like. While this license is +intended to facilitate the commercial use of the Program, the Contributor who +includes the Program in a commercial product offering should do so in a +manner which does not create potential liability for other Contributors. +Therefore, if a Contributor includes the Program in a commercial product +offering, such Contributor ("Commercial Contributor") hereby agrees to defend +and indemnify every other Contributor ("Indemnified Contributor") against any +losses, damages and costs (collectively "Losses") arising from claims, +lawsuits and other legal actions brought by a third party against the +Indemnified Contributor to the extent caused by the acts or omissions of such +Commercial Contributor in connection with its distribution of the Program in +a commercial product offering. The obligations in this section do not apply +to any claims or Losses relating to any actual or alleged intellectual +property infringement. In order to qualify, an Indemnified Contributor must: +a) promptly notify the Commercial Contributor in writing of such claim, and +b) allow the Commercial Contributor to control, and cooperate with the +Commercial Contributor in, the defense and any related settlement +negotiations. The Indemnified Contributor may participate in any such claim +at its own expense. + +For example, a Contributor might include the Program in a commercial product +offering, Product X. That Contributor is then a Commercial Contributor. If +that Commercial Contributor then makes performance claims, or offers +warranties related to Product X, those performance claims and warranties are +such Commercial Contributor's responsibility alone. Under this section, the +Commercial Contributor would have to defend claims against the other +Contributors related to those performance claims and warranties, and if a +court requires any other Contributor to pay any damages as a result, the +Commercial Contributor must pay those damages. + +5. NO WARRANTY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON +AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER +EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR +CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A +PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the +appropriateness of using and distributing the Program and assumes all risks +associated with its exercise of rights under this Agreement , including but +not limited to the risks and costs of program errors, compliance with +applicable laws, damage to or loss of data, programs or equipment, and +unavailability or interruption of operations. + +6. DISCLAIMER OF LIABILITY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY +CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION +LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE +EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY +OF SUCH DAMAGES. + +7. GENERAL + +If any provision of this Agreement is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of the +remainder of the terms of this Agreement, and without further action by the +parties hereto, such provision shall be reformed to the minimum extent +necessary to make such provision valid and enforceable. + +If Recipient institutes patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Program itself +(excluding combinations of the Program with other software or hardware) +infringes such Recipient's patent(s), then such Recipient's rights granted +under Section 2(b) shall terminate as of the date such litigation is filed. + +All Recipient's rights under this Agreement shall terminate if it fails to +comply with any of the material terms or conditions of this Agreement and +does not cure such failure in a reasonable period of time after becoming +aware of such noncompliance. If all Recipient's rights under this Agreement +terminate, Recipient agrees to cease use and distribution of the Program as +soon as reasonably practicable. However, Recipient's obligations under this +Agreement and any licenses granted by Recipient relating to the Program shall +continue and survive. + +Everyone is permitted to copy and distribute copies of this Agreement, but in +order to avoid inconsistency the Agreement is copyrighted and may only be +modified in the following manner. The Agreement Steward reserves the right to +publish new versions (including revisions) of this Agreement from time to +time. No one other than the Agreement Steward has the right to modify this +Agreement. The Eclipse Foundation is the initial Agreement Steward. The +Eclipse Foundation may assign the responsibility to serve as the Agreement +Steward to a suitable separate entity. Each new version of the Agreement will +be given a distinguishing version number. The Program (including +Contributions) may always be distributed subject to the version of the +Agreement under which it was received. In addition, after a new version of +the Agreement is published, Contributor may elect to distribute the Program +(including its Contributions) under the new version. Except as expressly +stated in Sections 2(a) and 2(b) above, Recipient receives no rights or +licenses to the intellectual property of any Contributor under this +Agreement, whether expressly, by implication, estoppel or otherwise. All +rights in the Program not expressly granted under this Agreement are +reserved. + +This Agreement is governed by the laws of the State of New York and the +intellectual property laws of the United States of America. No party to this +Agreement will bring a legal action under this Agreement more than one year +after the cause of action arose. Each party waives its rights to a jury trial +in any resulting litigation. diff --git a/README.md b/README.md new file mode 100644 index 0000000..947b9af --- /dev/null +++ b/README.md @@ -0,0 +1,155 @@ +# ring-homogeneous-auth-middleware + +A Clojure library designed to homogenise many different auth middleware. + +## Usage + +Generally each auth middleware add the auth informations to the ring-request +hash-map. + +So for example a ring-jwt-auth middleware will add a `:jwt` field +containing some informations about the identity and auth details. + +Another middleware could also be used, for example one might want +to accept JWT and long term API keys. The other middleware could then +add a `:api-key-infos` field to the hash-map whose value could be +some other kind of information. + +This middleware is a simple way to merge all those different informations +in a centralized and normalized way. +The middelware takes multiple _extractors_ as parameters. +An extractor is a function that given a ring-request extract an `IdentityInfo` or nil. + +An `IdentityInfo` is defined as: + +```clojure +(s/defschema User + "An User should be understood as a unique entity able to be identified. + An user must have an unique id and also a name. + + An user could also contain many meta fields that could be provided as meta + data by some authentication layer. Typically, an email, a phone number, etc... + " + (st/merge + {:id s/Str + :name s/Str} + ;; could contain other meta datas (email, address, phone number, etc...) + {s/Keyword s/Any})) + +(s/defschema Group + "A Group can be understood as a Community of People, an Organization, a + Business, etc... + + Mainly this should provide a way to filter document for an organization. + + A group must have an unique identifier and a name. + + A group could also have some meta informations. For example, a physical + address, an Identity Provider URL, etc.." + (st/merge + {:id s/Str + :name s/Str} + ;; could contain other meta datas (Identity Provider URL, etc...) + {s/Keyword s/Any})) + +(def Role + "What are the roles of the user. + + Mainly this should provide a way to filter route access. + + Typical values are: :admin :user :read-only etc... " + s/Keyword) + +(s/defschema IdentityInfo + "An IdentityInfo provide the information to identify and determine the + permissions relative to some request. + + It provide an user, a set of groups and a set of roles. + + It is important to note that roles aren't associated to an user but to an + IdentityInfo. This enable the same user to provide different roles via + different API-Key for example. + + An IdentityInfo while having some mandatory informations could also contains + some other informations generally for dealing with technical details and ease + the debugging." + (st/merge + {:user User + :groups #{Group} + :roles #{Role}} + {s/Keyword s/Any})) +``` + +Then the middleware will passe the ring request through all extractors and the +first return successful extractor will add an `:identity-info` field to the ring +request. + +It is used that way: + +```clojure +(def extractors [jwt-extractor api-key-extractor]) + +(let [app ((wrap-fn extractors) handler)] + ...) +``` + +Where here are some example of extractors: + +```clojure +;; Extractor code example for some JWT + +(s/defn extract-identity-infos :- IdentityInfo + [jwt-info] + {:id {:id (:sub jwt-info) + :name (:sub jwt-info)} + :groups #{{:id (:org_guid jwt-info) + :name (:org_name jwt-info)}} + :roles (if (= "true" + ;; this test handle the case when :user_admin is a string + ;; and when its a boolean + (str (:user_admin jwt-info))) + #{:admin :user} + #{:user}) + :auth-type :jwt}) + +(s/defn jwt-extractor :- (s/maybe IdentityInfo) + [req] + (some-> req + :jwt + extract-identity-infos)) + +;; Extractor code example for API Key considering thay :api-key-info field +;; already contains an IdentityInfo + +(s/defn api-key-extractor :- (s/maybe IdentityInfo) + [req] + (some-> req + :api-key-infos + (assoc :auth-type :api-key))) +``` + +Furthermore this middleware also provides the ability to destructure information +if you use compojure-api. +Typically you could: + +~~~clojure +(GET "/foo" [] + :identity-info [id-info] + (... do something with id-info ...)) +~~~ + +and also + +~~~clojure + ;; only user with the role :admin could access this route +(GET "/foo" [] + :roles-filter #{:admin} + ...) +~~~ + +## License + +Copyright © 2017 Cisco + +Distributed under the Eclipse Public License either version 1.0 or (at +your option) any later version. diff --git a/doc/intro.md b/doc/intro.md new file mode 100644 index 0000000..cdb79c4 --- /dev/null +++ b/doc/intro.md @@ -0,0 +1,3 @@ +# Introduction to ring-homogeneous-auth-middleware + +TODO: write [great documentation](http://jacobian.org/writing/what-to-write/) diff --git a/project.clj b/project.clj new file mode 100644 index 0000000..839b085 --- /dev/null +++ b/project.clj @@ -0,0 +1,11 @@ +(defproject threatgrid/ring-homogeneous-auth-middleware "0.0.1" + :description "A simple middleware to deal with multiple auth middlewares" + :url "http://github.com/threatgrid/ring-homogeneous-auth-middleware" + :license {:name "Eclipse Public License - v 1.0" + :url "http://www.eclipse.org/legal/epl-v10.html" + :distribution :repo} + :dependencies [[org.clojure/clojure "1.8.0"] + [metosin/ring-http-response "0.8.2"] + [metosin/compojure-api "1.1.9"] + [metosin/schema-tools "0.9.1"] + [prismatic/schema "1.1.3"]]) diff --git a/src/ring_homogeneous_auth_middleware/core.clj b/src/ring_homogeneous_auth_middleware/core.clj new file mode 100644 index 0000000..ba5cecc --- /dev/null +++ b/src/ring_homogeneous_auth_middleware/core.clj @@ -0,0 +1,77 @@ +(ns ring-homogeneous-auth-middleware.core + "This ns provide a middleware that could be used to merge potentially multiple + auth middleware effects. + + Given a list of functions taking a ring request and returning a (s/maybe IdentityInfo) + The `wrap-auths-fn` returns a middleware the add the first non nil response + from those functions in the :identity-info key of the ring-request. + + Some helpers are also provided for compojure-api usage. + " + (:require [ring-homogeneous-auth-middleware.schemas :refer [IdentityInfo]] + [clojure.set :as set] + [compojure.api.meta :as meta] + [schema.core :as s])) + +(s/defn get-identity-info :- (s/maybe IdentityInfo) + "Given a ring request and and a couple auth-key auth-info->identity-info. + We return the identity-info if possible" + [request + [auth-key auth-infos->identity-info]] + (when-let [auth-infos (get request auth-key)] + (auth-infos->identity-info auth-infos))) + +(s/defn wrap-auths-fn + "You should provide a list of [[AuthExtractor]]s your ring request should have + a :auth key in them." + [auth-extractors] + (fn [handler] + (fn [request] + (let [identity-info + (->> auth-extractors + (map #(% request)) + (remove nil?) + first) + new-request (if identity-info + (assoc request :identity-info identity-info) + request)] + (handler new-request))))) + +;; COMPOJURE-API Restructuring + +;; Add the :identity-info in the route description +(defmethod meta/restructure-param + :identity-info [_ id-infos acc] + (let [schema (meta/fnk-schema id-infos) + new-letks [id-infos (meta/src-coerce! schema :identity-info :string)]] + (update-in acc [:letks] into new-letks))) + +;; Add the :roles-filter +;; to compojure api params +;; it should contains a set of hash-maps +;; example: +;; +;; ~~~ +;; (POST "/foo" [] :roles-filter #{:admin}) +;; ~~~ +;; +;; Will be accepted only for requests having a role in the authorized set. + +(defn check-roles-filter! + [authorized-roles request-roles] + (when-not (set? authorized-roles) + (throw (ex-info ":roles-filter argument in compojure-api must be a set!" {}))) + (when-not (and (set? request-roles) + (set/intersection authorized-roles request-roles)) + (ring.util.http-response/unauthorized! + {:msg "You don't have the required credentials to access this route"}))) + +(defmethod compojure.api.meta/restructure-param + :roles-filter [_ authorized acc] + (update-in + acc + [:lets] + into + ['_ `(check-roles-filter! + ~authorized + (:identity-info ~'+compojure-api-request+))])) diff --git a/src/ring_homogeneous_auth_middleware/schemas.clj b/src/ring_homogeneous_auth_middleware/schemas.clj new file mode 100644 index 0000000..75e23d6 --- /dev/null +++ b/src/ring_homogeneous_auth_middleware/schemas.clj @@ -0,0 +1,60 @@ +(ns ring-homogeneous-auth-middleware.schemas + (:require [schema.core :as s] + [schema-tools.core :as st])) + + +(s/defschema User + "An User should be understood as a unique entity able to be identified. + An user must have an unique id and also a name. + + An user could also contain many meta fields that could be provided as meta + data by some authentication layer. Typically, an email, a phone number, etc... + " + (st/merge + {:id s/Str + :name s/Str} + ;; could contain other meta datas (email, address, phone number, etc...) + {s/Keyword s/Any})) + +(s/defschema Group + "A Group can be understood as a Community of People, an Organization, a + Business, etc... + + Mainly this should provide a way to filter document for an organization. + + A group must have an unique identifier and a name. + + A group could also have some meta informations. For example, a physical + address, an Identity Provider URL, etc.." + (st/merge + {:id s/Str + :name s/Str} + ;; could contain other meta datas (Identity Provider URL, etc...) + {s/Keyword s/Any})) + +(def Role + "What are the roles of the user. + + Mainly this should provide a way to filter route access. + + Typical values are: :admin :user :read-only etc... " + s/Keyword) + +(s/defschema IdentityInfo + "An IdentityInfo provide the information to identify and determine the + permissions relative to some request. + + It provide an user, a set of groups and a set of roles. + + It is important to note that roles aren't associated to an user but to an + IdentityInfo. This enable the same user to provide different roles via + different API-Key for example. + + An IdentityInfo while having some mandatory informations could also contains + some other informations generally for dealing with technical details and ease + the debugging." + (st/merge + {:user User + :groups #{Group} + :roles #{Role}} + {s/Keyword s/Any})) diff --git a/test/ring_homogeneous_auth_middleware/core_test.clj b/test/ring_homogeneous_auth_middleware/core_test.clj new file mode 100644 index 0000000..248d110 --- /dev/null +++ b/test/ring_homogeneous_auth_middleware/core_test.clj @@ -0,0 +1,80 @@ +(ns ring-homogeneous-auth-middleware.core-test + (:require [ring-homogeneous-auth-middleware.core :as sut] + [ring-homogeneous-auth-middleware.schemas :refer [IdentityInfo]] + [clojure.test :as t :refer [is use-fixtures]] + [schema.test :refer [deftest]] + [schema.core :as s])) + +(use-fixtures :once schema.test/validate-schemas) + +;; Extractor code example for some JWT + +(s/defn extract-identity-info :- IdentityInfo + [jwt-info] + {:user {:id (:sub jwt-info) + :name (:sub jwt-info)} + :groups #{{:id (:org_guid jwt-info) + :name (:org_name jwt-info)}} + :roles (if (= "true" + ;; this test handle the case when :admin is a string + ;; and when its a boolean + (str (:admin jwt-info))) + #{:admin :user} + #{:user}) + :auth-type :jwt + :jwt jwt-info}) + +(s/defn jwt-extractor :- (s/maybe IdentityInfo) + [req] + (some-> req + :jwt + extract-identity-info)) + +;; Extractor code example for API Key + +(s/defn api-key-extractor :- (s/maybe IdentityInfo) + [req] + (some-> req + :api-key-infos + (assoc :auth-type :api-key))) + +;; Tests + +(deftest wrap-auths-test + (let [base-request {:server-port 8080 + :server-name "localhost" + :remote-addr "127.0.0.1" + :uri "/" + :scheme :http + :request-method :get + :protocol "HTTP/1.1" + :headers {}} + + jwt {:admin true + :sub "testuser@cisco.com" + :org_name "IROH Testing" + :org_guid "00000000-0000-0000-00000000000000000" + :nbf 1487167750 + :jti "aaaaaaaa-aaaa-aaaa-aaaaaaaaaaaaaaaaa" + :iat 1487168050 + :exp 1487772850} + + id-info {:user {:id "testuser@cisco.com" + :name "testuser@cisco.com"} + :groups #{{:id "00000000-0000-0000-00000000000000000" + :name "IROH Testing"}} + :roles #{:admin :user} + :auth-type :jwt + :jwt jwt} + + request-jwt (assoc base-request :jwt jwt) + request-api-key (assoc base-request :api-key-infos id-info) + app ((sut/wrap-auths-fn [jwt-extractor api-key-extractor]) identity)] + (is (nil? (:identity-info (app base-request))) + "without any :jwt nor :api-key there shouldnt be any identity-info") + (is (= (:identity-info (app request-jwt)) + id-info) + "Should provide identity-info from a jwt field") + (is (= (:identity-info (app request-api-key)) + (assoc id-info :auth-type :api-key)) + "Should provide identity-info from a api-key field")))