{"id":13787867,"url":"https://github.com/build-security/opa-express-middleware","last_synced_at":"2025-05-12T02:30:35.139Z","repository":{"id":40708954,"uuid":"307418670","full_name":"build-security/opa-express-middleware","owner":"build-security","description":"Node.JS Express middleware for working with the Open Policy Agent","archived":false,"fork":false,"pushed_at":"2023-03-05T14:59:40.000Z","size":1477,"stargazers_count":56,"open_issues_count":11,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-21T12:44:52.545Z","etag":null,"topics":["authorization","express","express-middleware","nodejs","opa"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/build-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-26T15:30:48.000Z","updated_at":"2025-02-09T20:14:16.000Z","dependencies_parsed_at":"2024-08-03T21:01:23.890Z","dependency_job_id":null,"html_url":"https://github.com/build-security/opa-express-middleware","commit_stats":{"total_commits":26,"total_committers":7,"mean_commits":"3.7142857142857144","dds":0.5,"last_synced_commit":"7cda4fdd0915d58f8573f4d75b99955a6946defe"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/build-security%2Fopa-express-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/build-security%2Fopa-express-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/build-security%2Fopa-express-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/build-security%2Fopa-express-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/build-security","download_url":"https://codeload.github.com/build-security/opa-express-middleware/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253662530,"owners_count":21944090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authorization","express","express-middleware","nodejs","opa"],"created_at":"2024-08-03T21:00:32.481Z","updated_at":"2025-05-12T02:30:34.869Z","avatar_url":"https://github.com/build-security.png","language":"JavaScript","funding_links":[],"categories":["Language and Platform Integrations"],"sub_categories":["Node.js"],"readme":"\n# opa-express-middleware\n\u003cp align=\"center\"\u003e\u003cimg src=\"Logo-build.png\" class=\"center\" alt=\"build-logo\" width=\"30%\"/\u003e\u003c/p\u003e\n\n## Abstract\n[build.security](https://docs.build.security/) provides simple development and management for your organization's authorization policy.\nopa-express-middleware is a Node.js Express middleware intended for performing authorization requests against build.security PDP(Policy Decision Point)/[OPA](https://www.openpolicyagent.org/).\n\n## Data Flow\n\u003cp align=\"center\"\u003e \u003cimg src=\"Data%20flow.png\" alt=\"drawing\" width=\"60%\"/\u003e\u003c/p\u003e\n\n## Usage\n\nBefore you start we recommend completing the onboarding tutorial.\n\n---\n**Important note**\n\nTo simplify the setup process, the following example uses a local [build.security PDP instance](https://docs.build.security/policy-decision-points-pdp/pdp-deployments/standalone-docker-1).\nIf you are already familiar with how to run your PDP, You can also run a pdp on you environment (Dev/Prod, etc).\n\nIn that case, don't forget to change the **hostname** and the **port** in your code.\n\n---\n\n### Simple usage\n```js\nconst express = require('express');\nconst bodyParser = require('body-parser');\nconst extAuthz = require('@build-security/opa-express-middleware');\nconst port = 3000;\n\nconst app = express();\n\nconst extAuthzMiddleware = extAuthz.authorize((req) =\u003e ({\n    port: 8181,\n    hostname: 'http://localhost',\n    policyPath: '/authz/allow',\n}));\n\n\napp.use(bodyParser.json(), extAuthzMiddleware);\n\napp.listen(port, () =\u003e {\n  console.log(`Now listening on http://localhost:${port}`)\n});\n```\n### Mandatory configuration\n 1. `hostname`: The hostname of the Policy Decision Point (PDP)\n 2. `port`: The port at which the OPA service is running\n 3. `policyPath`: Full path to the policy (including the rule) that decides whether requests should be authorized\n\n### Optional configuration\n 1. `allowOnFailure`: Boolean. \"Fail open\" mechanism to allow access to the API in case the policy engine is not reachable. **Default is false**.\n 2. `includeBody`: Boolean. Whether or not to pass the request body to the policy engine. **Default is true**.\n 3. `includeHeaders`: Boolean. Whether or not to pass the request headers to the policy engine. **Default is true**\n 4. `timeout`: Integer. Amount of time to wait before request is abandoned and request is declared as failed. **Default is 1000ms**.\n 5. `enable`: Boolean. Whether or not to consult with the policy engine for the specific request. **Default is true**\n 6. `enrich`: Object. An object to attach to the request that is being sent to the policy engine. **Default is an empty object {}**\n\n### Advanced example\nThe following example will:\n- consult with the policy engine only for GET requests\n- add a field named \"serviceId\" with the value 1 to the request\n- provide route parameters to the PDP as input. (For this to work, the middleware can't be applied globally using `app.use`)\n- an endpoint can declare the required permission the client needs in order to access it\n```js\nconst express = require('express');\nconst bodyParser = require('body-parser');\nconst extAuthz = require('@build-security/opa-express-middleware');\n\nconst app = express();\n\nconst extAuthzMiddleware = extAuthz.authorize((req) =\u003e ({\n    port: 8181,\n    hostname: 'http://localhost',\n    policyPath: '/authz/allow',\n    enable: req.method === \"GET\",\n    enrich: { serviceId: 1 }\n}));\n\napp.use(bodyParser.json());\n\napp.get('/region/:region/users/:userId', extAuthz.permissions('user.read'), extAuthzMiddleware, (req, res) =\u003e {\n    res.send('allowed');\n});\n```\n\n### PDP Request example\n\nThis is what the input received by the PDP would look like.\n\n```\n{\n   \"input\":{\n      \"request\":{\n         \"method\":\"GET\",\n         \"query\":{\n            \n         },\n         \"path\":\"/region/israel/users/buildsec\",\n         \"scheme\":\"http\",\n         \"host\":\"localhost\",\n         \"body\":{\n            \n         },\n         \"headers\":{\n            \"host\":\"localhost:3000\",\n            \"user-agent\":\"curl/7.64.1\",\n            \"accept\":\"*/*\"\n         }\n      },\n      \"source\":{\n         \"port\":56038,\n         \"ipAddress\":\"::1\"\n      },\n      \"destination\":{\n         \"port\":3000,\n         \"ipAddress\":\"::1\"\n      },\n      \"resources\":{\n         \"attributes\":{\n            \"region\":\"1\",\n            \"userId\":\"2\"\n         },\n         \"permissions\":[\n            \"user.read\"\n         ]\n      },\n      \"serviceId\":1\n   }\n}\n```\n\nIf everything works well you should receive the following response:\n\n```\n{\n    \"decision_id\":\"ef414180-05bd-4817-9634-7d1537d5a657\",\n    \"result\":true\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuild-security%2Fopa-express-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuild-security%2Fopa-express-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuild-security%2Fopa-express-middleware/lists"}