{"id":13506043,"url":"https://github.com/telefonicaid/fiware-pep-steelskin","last_synced_at":"2026-01-23T14:13:18.222Z","repository":{"id":19227266,"uuid":"22461729","full_name":"telefonicaid/fiware-pep-steelskin","owner":"telefonicaid","description":"Telefonica's implementation of the FIWARE PEP GE","archived":false,"fork":false,"pushed_at":"2025-08-28T13:53:13.000Z","size":1979,"stargazers_count":0,"open_issues_count":34,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-08-28T19:46:41.417Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telefonicaid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES_NEXT_RELEASE","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,"zenodo":null}},"created_at":"2014-07-31T08:14:19.000Z","updated_at":"2025-08-01T13:06:12.000Z","dependencies_parsed_at":"2024-01-13T19:24:16.056Z","dependency_job_id":"a9e9f547-5b8f-4d9a-96e7-4fd573c12d2e","html_url":"https://github.com/telefonicaid/fiware-pep-steelskin","commit_stats":{"total_commits":889,"total_committers":26,"mean_commits":34.19230769230769,"dds":0.515185601799775,"last_synced_commit":"677f8605e0d1e317d1e96c282f2d5457b59291a0"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/telefonicaid/fiware-pep-steelskin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-pep-steelskin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-pep-steelskin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-pep-steelskin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-pep-steelskin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telefonicaid","download_url":"https://codeload.github.com/telefonicaid/fiware-pep-steelskin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telefonicaid%2Ffiware-pep-steelskin/sbom","scorecard":{"id":873011,"data":{"date":"2025-08-11","repo":{"name":"github.com/telefonicaid/fiware-pep-steelskin","commit":"d0447ab7173ed1308f01b2c157d9fd61b660e962"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.1,"checks":[{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":10,"reason":"all changesets reviewed","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":5,"reason":"7 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 5","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:47: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:62: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:64: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:71: update your workflow using https://app.stepsecurity.io/secureworkflow/telefonicaid/fiware-pep-steelskin/ci.yml/master?enable=pin","Warn: containerImage not pinned by hash: docker/Dockerfile:23","Warn: npmCommand not pinned by hash: docker/Dockerfile:83-96","Warn: npmCommand not pinned by hash: docker/entrypoint.sh:58","Warn: npmCommand not pinned by hash: .github/workflows/ci.yml:68","Warn: npmCommand not pinned by hash: .github/workflows/ci.yml:33","Warn: npmCommand not pinned by hash: .github/workflows/ci.yml:54","Info:   0 out of   7 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 third-party GitHubAction dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned","Info:   0 out of   5 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: GNU Affero General Public License v3.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: GHSA-9wx4-h78v-vm56"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-24T04:53:45.190Z","repository_id":19227266,"created_at":"2025-08-24T04:53:45.190Z","updated_at":"2025-08-24T04:53:45.190Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273703311,"owners_count":25152999,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-08-01T01:00:33.608Z","updated_at":"2026-01-23T14:13:18.214Z","avatar_url":"https://github.com/telefonicaid.png","language":"JavaScript","funding_links":[],"categories":["FIWARE Catalogue"],"sub_categories":["Security"],"readme":"# fiware-pep-steelskin\n\n[![FIWARE Security](https://nexus.lab.fiware.org/static/badges/chapters/security.svg)](https://www.fiware.org/developers/catalogue/)\n[![License: APGL](https://img.shields.io/github/license/telefonicaid/fiware-pep-steelskin.svg)](https://opensource.org/licenses/AGPL-3.0)\n[![Quay badge](https://img.shields.io/badge/quay.io-fiware%2Fpep--steelskin-grey?logo=red%20hat\u0026labelColor=EE0000)](https://quay.io/repository/fiware/pep-steelskin)\n[![Docker badge](https://img.shields.io/badge/docker-telefonicaiot%2Ffiware--pep--steelskin-blue?logo=docker)](https://hub.docker.com/r/telefonicaiot/fiware-pep-steelskin)\n\u003cbr/\u003e\n[![CI](https://github.com/telefonicaid/fiware-pep-steelskin/workflows/CI/badge.svg)](https://github.com/telefonicaid/fiware-pep-steelskin/actions?query=workflow%3ACI)\n[![Coverage Status](https://coveralls.io/repos/github/telefonicaid/fiware-pep-steelskin/badge.svg?branch=master)](https://coveralls.io/github/telefonicaid/fiware-pep-steelskin?branch=master)\n![Status](https://nexus.lab.fiware.org/static/badges/statuses/incubating.svg)\n\n## Index\n\n* [Overview](#overview)\n* [Deployment](#deployment)\n* [Usage](#usage)\n* [Administration](#administration)\n* [Configuration](#configuration)\n* [API With Access Control](#apiaccesscontrol)\n* [Rules to determine the Context Broker action from the request](#rules)\n* [Rules to determine the Perseo action from the request](#rulesPerseo)\n* [Rules to determine the Keypass Access Control action from the request](#rulesKeypass)\n* [Customizing PEP Proxy for other components](#customizing)\n* [License](#licence)\n* [Development documentation](#development)\n\n## \u003ca name=\"overview\"/\u003e Overview\nThe Policy Enforcement Point (PEP) is a proxy meant to secure independent FiWare components, by intercepting every request sent to the component, validating it against the Access Control component. This validation is based in several pieces of data:\n\n* User token: comes from the OAuth authorization server and is taken from the `x-auth-token` header.\n* ServiceId: is read from the `fiware-service` header and identifies the protected component.\n* SubserviceId: is read from the `fiware-servicepath` header and identifies further divisions of the service.\n* Action: the PEP guess the action for a particular request by checking the path or inspecting the body. The logic for performing such actions depends on the component that is being secured, so the PEP will need a plugin for each of this components.\n\nCommunication with the Access Control is based on the [XACML protocol](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html).\n\nAlong this document, the term IDM (Identity Manager) will be used, as a general term to refer to the server providing user and role creation and authentication. The currently supported IDM is Keystone; a Keyrock IDM option is provided as well, but it may be deprecated in the near future.\n\nThree other documents provide further information about the PEP Proxy:\n\n* [Operations Manual](operations.md): provides information on logs and alarms.\n* [Architecture information](architecture.md): provides further information on how the PEP works and is structured.\n* [Keystone installation](keystoneInstallation.md): provides an example of Keystone installation with services and subservices\n that can be used to test the PEP Proxy and play with its features.\n\n## \u003ca name=\"deployment\"/\u003e Deployment\n### Dependencies\nThe PEP Proxy is standard Node.js app and doesn't require more dependencies than the Node.js interpreter and the NPM package utility.\n\nJust checkout this directory and install the Node.js dependencies using:\n\n```\nnpm install --production\n```\n\nThe proxy should be then ready to be configured and used.\n\n### With Docker\nThere are automatic builds of the development version of the Steelskin PEP Proxy published in Docker hub. In order to install\nusing the docker version, just execute the following:\n```\ndocker run -p 11211:11211 -p 1026:1026 -e LOG_LEVEL=DEBUG -e AUTHENTICATION_HOST=\u003cKeystone-host\u003e -e ACCESS_HOST=\u003cAccess-control-host\u003e -e TARGET_HOST=\u003cOrion-host\u003e telefonicaiot/fiware-pep-steelskin\n```\nThis command will create a docker container with a PEP Steelskin running, using \u003cKeystone-host\u003e for token validation and\nauthentication, \u003cAccess-control-host\u003e for access control and redirecting allowed requests to \u003cOrion-host\u003e. Remember there\nare more environment variables you can use to tailor Steelskin configuration to suit your needs; you can find the complete\nlist in the configuration section below.\n\nTake note that this command expose two ports: the 1026 port for component requests and the administration port, 11211.\n\n### Build your own Docker image\nThere is also the possibility to build your own local Docker image of the PEP component.\n\nTo do it, follow the next steps once you have installed Docker in your machine:\n\n1. Navigate to the path where the component repository was cloned.\n2. Launch a Docker build\n    * Using the default NodeJS version of the operating system used defined in FROM keyword of Dockerfile:\n    ```bash\n    sudo docker build -f Dockerfile .\n    ```\n    * Using an alternative NodeJS version:\n    ```bash\n    sudo docker build --build-arg NODEJS_VERSION=0.10.46 -f Dockerfile .\n    ```\n### Using PM2\n\nThe PEP within the Docker image can be run encapsulated within the [pm2](http://pm2.keymetrics.io/) Process\nManager by adding the `PM2_ENABLED` environment variable.\n\n```console\ndocker run --name pep -e PM2_ENABLED=true -d fiware/fiware-pep-steelskin\n```\n\nUse of pm2 is **disabled** by default. It is unnecessary and counterproductive to add an additional process manager if\nyour dockerized environment is already configured to restart Node.js processes whenever they exit (e.g. when using\n[Kubernetes](https://kubernetes.io/))\n\n\n### Using Node Inspection\n\nThe PEP within the Docker image can be run with [node inspection](https://nodejs.org/en/docs/guides/debugging-getting-started/) by adding the `INSPECT_ENABLED` environment variable.\n\n```console\ndocker run --name pep -e INSPECT_ENABLED=true -d fiware/fiware-pep-steelskin\n```\n\nUse of node inspection is **disabled** by default.\n\n### Undeployment\nIn order to undeploy the proxy, if it was installed directly from the GIT repositories, just kill the process and remove the directory.\n\n### Configuration\nAssuming the PEP Proxy is deployed directly from the source code, it won't add itself as a service, and the running ports should be configured manually. This configuration will involve two steps:\n* Changing the port of the Context Broker to a different internal port (not open to external connections). Refer to the Orion Context Broker Deployment Manual for instructions on how to do it.\n* Changing the port of the proxy to listen in the Context Broker original port, and to redirect to the new one. This parameters can be changed in the config.js file in the root folder.\nOnce configured, the service can be started as a demon with the following comand:\n\n```\nnohup bin/pep-proxy.js \u0026\u003e pep-proxy.log\u0026\n```\n\n### Activate service\nThe proxy service is disabled once its installed. In order to enable it, use the following command:\n```\nservice pepProxy start\n```\n\n### Log Rotation\nIndependently of how the service is installed, the log files will need an external rotation (e.g.: the logrotate command) to avoid disk full problems. \n\n\n## \u003ca name=\"usage\"/\u003e Usage\nIf the PEP Proxy is not started as a service, it can be started executing the following command from the project root:\n\n```\nbin/pep-proxy.js\n```\n\nOnce the PEP Proxy is working, it can be used to enforce both authentication and authorization over the protected component (e.g. Orion Context Broker). In order to enforce both actions, the PEP Proxy has to be connected to an [Identity Manager](https://github.com/ging/fi-ware-idm) server and an [Access Manager](https://github.com/telefonicaid/fiware-keypass) server. Next sections will show some examples of both processes.\n\nNote that, in order for a request to be authorized through the Access Control, it's mandatory that it contains all of the following headers:\n* **x-auth-token**: should contain a valid user token, generated by the IDM.\n* **fiware-service**: should contain the name of a service created in the IDM and the user must have access to it.\n* **fiware-servicepath**: should contain a route to a subservice, begining with a slash '/' symbol.\n\nThis headers are used by the IDM and Access Control systems to make the decisions about the request, so if any of them are missing, the request will not progress any further, and will be rejected with a 400 HTTP error code. For a detailed explanation of the returned errors, please refer to the [API Error codes](errorcodes.md).\n\nThe proxy can also work in an authentication-only mode (using the `config.access.disable` flag), in which case the `fiware-service` and `fiware-servicepath` headers can be marked as optional, or checked anyway for validity (controlled by the `config.authentication.checkHeaders` flag). Header checking cannot be disabled for PEP Proxies performing authorization processes.\n\n### Authentication\n\nThe authentication process is based on OAuth v2 tokens. The PEP Proxy expects all the requests to have a header `x-auth-token` containing a valid access token from the IDM. All the requests without this requirement are rejected with a 401 error. \n\nPEP Proxy currently supports two possible authentication authorities: Keyrock IdM and Openstack Keystone. The following sections show how to retrieve a token with each of this authentication technologies. The module can be configured using the config.authentication.module option.\n\n#### Keyrock IdM\n\nIn order to get an access token to send with the request, a user can send a request to the IDM, with its user and password (here shown as a curl request):\n\n```\ncurl -i --user \u003cserverUser\u003e:\u003cserverPassword\u003e -X POST -H \"Content-Type: application/x-www-form-urlencoded\" https://\u003cidmHostName\u003e/oauth2/token -d 'grant_type=password\u0026username=\u003ctheUserName\u003e\u0026password=\u003ctheUserPassword\u003e'\n```\n\nIf the user and password are correct, the response will be like the following:\n\n```\n{\n    \"access_token\":\"O-OqiBR1AbZk7qfyidF3AwMeBY253xYEpUdkv\",\n    \"refresh_token\":\"Ny0OwE19230QfftxXYGwwgOLafa5v2xnI5t6HWdQ\",\n    \"token_type\":\"bearer\",\n    \"expires_in\":2591999\n}\n```\n\nThe `access_token` field contains the required token. \n\nThe must be used also to assign roles to each user. For details about role creation and assign, check the IDM API.\n\n#### Keystone\nIn order to get its access token, a user can send the following request to Keystone:\n```\ncurl http://localhost:5000/v3/auth/tokens \\\n    -s \\\n    -i \\\n    -H \"Content-Type: application/json\" \\\n    -d '\n{\n    \"auth\": {\n        \"identity\": {\n            \"methods\": [\n                \"password\"\n            ],\n            \"password\": {\n                \"user\": {\n                    \"domain\": {\n                        \"name\": \"SmartCity\"\n                    },\n                    \"name\": \"alice\",\n                    \"password\": \"password\"\n                }\n            }\n        }\n    }\n}'\n```\nThe token can be found in the `X-Subject-Token` header of the response:\n```\nX-Subject-Token: MIIC3AYJKoZIhvcNAQcCoIICzTCCAskCAQExCTAHBgUrDgMCGjCCATIGCSqGSIb3DQEHAaCCASMEggEfeyJ0b2tlbiI6IHsiaXNzdWVkX2F0IjogIjIwMTQtMTAtMTBUMTA6NTA6NDkuNTMyNTQyWiIsICJleHRyYXMiOiB7fSwgIm1ldGhvZHMiOiBbInBhc3N3b3JkIl0sICJleHBpcmVzX2F0IjogIjIwMTQtMTAtMTBUMTE6NTA6NDkuNTMyNDkxWiIsICJ1c2VyIjogeyJkb21haW4iOiB7ImlkIjogImY3YTViOGUzMDNlYzQzZThhOTEyZmUyNmZhNzlkYzAyIiwgIm5hbWUiOiAiU21hcnRWYWxlbmNpYSJ9LCAiaWQiOiAiNWU4MTdjNWUwZDYyNGVlNjhkZmI3YTcyZDBkMzFjZTQiLCAibmFtZSI6ICJhbGljZSJ9fX0xggGBMIIBfQIBATBcMFcxCzAJBgNVBAYTAlVTMQ4wDAYDVQQIDAVVbnNldDEOMAwGA1UEBwwFVW5zZXQxDjAMBgNVBAoMBVVuc2V0MRgwFgYDVQQDDA93d3cuZXhhbXBsZS5jb20CAQEwBwYFKw4DAhowDQYJKoZIhvcNAQEBBQAEggEAKRGV3uu8fiS7UNm47KhltSjlY1e7KnedUcD-mdwz6Asbo7X9hbtljy1ml9gGcuMf6vX4tycx4goRyMARPS7YKROd0evZtnYArIyx0IrmwDaqodwp8BxBCxFgHRZtCwzHvZFEaUcClydQq7HJvBfTgTwH4v1aJkMyK8wLMP-CYyiZSfCIWPVnoB9I3P56jeKHkmcryYLgT2I-AwDBj1zd9HPzUjyQuNj5rCMkJjvz-A9-hef6AMMZuYPMIYdkei+deq86O1qFuo7PpO2SA7QWkqjcsKs9v+myvHhLrBre9GLP2hP1rc4D67lSL2XB1UY20mc6FNIVIErxT0DOSXltXQ==\nVary: X-Auth-Token\nContent-Type: application/json\nContent-Length: 287\nDate: Fri, 10 Oct 2014 10:50:49 GMT\n\n{\n  \"token\": {\n    \"issued_at\": \"2014-10-10T10:50:49.532542Z\",\n    \"extras\": {},\n    \"methods\": [\n      \"password\"\n    ],\n    \"expires_at\": \"2014-10-10T11:50:49.532491Z\",\n    \"user\": {\n      \"domain\": {\n        \"id\": \"f7a5b8e303ec43e8a912fe26fa79dc02\",\n        \"name\": \"SmartValencia\"\n      },\n      \"id\": \"5e817c5e0d624ee68dfb7a72d0d31ce4\",\n      \"name\": \"alice\"\n    }\n  }\n}\n```\n\nFor details on user and role creation, check the Keystone API.\n\n### Authorization\n\nOnce the user is authenticated, the PEP Proxy will ask the Access Control for its permissions. In order for the request to be accepted, at least one rule has to match the request information and the user roles. \n\nRules are defined in [XACML](https://www.oasis-open.org/committees/xacml/). The particular rules will depend on each case and are left to the authorization designer. The following document shows a typical rule explained for the use case of a Context Broker:\n\n```\n\u003cPolicy xsi:schemaLocation=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17\n    http://docs.oasis-open.org/xacml/3.0/xacml-core-v3-schema-wd-17.xsd\"\n        PolicyId=\"policy03\"\n        RuleCombiningAlgId=\"urn:oasis:names:tc:xacml:3.0:rule-combining-algorithm:deny-unless-permit\"\n        Version=\"1.0\" xmlns=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17\"\n        xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\u003e\n\n  \u003cTarget\u003e\n    \u003cAnyOf\u003e\n      \u003cAllOf\u003e\n        \u003cMatch MatchId=\"urn:oasis:names:tc:xacml:1.0:function:string-regexp-match\"\u003e\n          \u003cAttributeValue\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\n              \u003efrn:contextbroker:551:833:.*\u003c/AttributeValue\u003e\n          \u003cAttributeDesignator\n              AttributeId=\"urn:oasis:names:tc:xacml:1.0:resource:resource-id\"\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\n              MustBePresent=\"true\"\n              Category=\"urn:oasis:names:tc:xacml:3.0:attribute-category:resource\" /\u003e\n        \u003c/Match\u003e\n      \u003c/AllOf\u003e\n    \u003c/AnyOf\u003e\n  \u003c/Target\u003e\n\n  \u003cRule RuleId=\"policy03rule01\" Effect=\"Permit\"\u003e\n\n    \u003cCondition\u003e\n      \u003cApply FunctionId=\"urn:oasis:names:tc:xacml:1.0:function:string-equal\"\u003e\n        \u003cApply FunctionId=\"urn:oasis:names:tc:xacml:1.0:function:string-one-and-only\"\u003e\n          \u003cAttributeDesignator\n              AttributeId=\"urn:oasis:names:tc:xacml:1.0:action:action-id\"\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\n              MustBePresent=\"true\"\n              Category=\"urn:oasis:names:tc:xacml:3.0:attribute-category:action\" /\u003e\n        \u003c/Apply\u003e\n        \u003cAttributeValue\n            DataType=\"http://www.w3.org/2001/XMLSchema#string\"\n            \u003eread\u003c/AttributeValue\u003e\n      \u003c/Apply\u003e\n    \u003c/Condition\u003e\n  \u003c/Rule\u003e\n\n\u003c/Policy\u003e\n\n```\n\nAll the rules are associated to a service ID (the value of the `fiware-service` header) and a subservice. When the request arrives to the Access Control, the later will retrieve all the permissions for the user roles, each one represented by a XACML policy. All the policies are applied then in order to find any that would let the request be executed.\n\nIn the example, the policy states the following: \"if the resource has the prefix `frn:contextbroker:551:833:` and the action `read` the request would be allowed\". This policy will allow read access over all the resources in subservice `833` of the service `551` to the roles that have it assigned. The meaning of the term resource will depend on the component which is being protected by the particular access rules. E.g.: for Orion Context Broker, the resources will be the entities of the CB; for each entity, the Policy Enforcement Point of the CB will generate a FRN, composed of the aforementioned prefix plus the identifier of the entity itself. \n\nAnother example could be this the following:\n\n```\n\u003cPolicy xsi:schemaLocation=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17\n    http://docs.oasis-open.org/xacml/3.0/xacml-core-v3-schema-wd-17.xsd\"\n        PolicyId=\"policy02\"\n        RuleCombiningAlgId=\"urn:oasis:names:tc:xacml:3.0:rule-combining-algorithm:deny-unless-permit\"\n        Version=\"1.0\" xmlns=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17\"\n        xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\u003e\n\n  \u003cTarget\u003e\n    \u003cAnyOf\u003e\n      \u003cAllOf\u003e\n        \u003cMatch MatchId=\"urn:oasis:names:tc:xacml:1.0:function:string-equal\"\u003e\n          \u003cAttributeValue\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\u003eadmin\u003c/AttributeValue\u003e\n          \u003cAttributeDesignator\n              AttributeId=\"urn:oasis:names:tc:xacml:1.0:subject:subject-id\"\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\n              MustBePresent=\"false\"\n              Category=\"urn:oasis:names:tc:xacml:1.0:subject-category:access-subject\" /\u003e\n        \u003c/Match\u003e\n        \u003cMatch MatchId=\"urn:oasis:names:tc:xacml:1.0:function:string-regexp-match\"\u003e\n          \u003cAttributeValue\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\u003efrn:contextbroker:551:833:.*\u003c/AttributeValue\u003e\n          \u003cAttributeDesignator\n              AttributeId=\"urn:oasis:names:tc:xacml:1.0:resource:resource-id\"\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\n              MustBePresent=\"true\"\n              Category=\"urn:oasis:names:tc:xacml:3.0:attribute-category:resource\" /\u003e\n        \u003c/Match\u003e\n      \u003c/AllOf\u003e\n    \u003c/AnyOf\u003e\n  \u003c/Target\u003e\n\n  \u003cRule RuleId=\"policy02rule01\" Effect=\"Permit\"\u003e\n\n    \u003cCondition\u003e\n      \u003cApply FunctionId=\"urn:oasis:names:tc:xacml:1.0:function:string-equal\"\u003e\n        \u003cApply FunctionId=\"urn:oasis:names:tc:xacml:1.0:function:string-one-and-only\"\u003e\n          \u003cAttributeDesignator\n              AttributeId=\"urn:oasis:names:tc:xacml:1.0:action:action-id\"\n              DataType=\"http://www.w3.org/2001/XMLSchema#string\"\n              MustBePresent=\"true\"\n              Category=\"urn:oasis:names:tc:xacml:3.0:attribute-category:action\" /\u003e\n        \u003c/Apply\u003e\n        \u003cAttributeValue\n            DataType=\"http://www.w3.org/2001/XMLSchema#string\"\u003ewrite\u003c/AttributeValue\u003e\n      \u003c/Apply\u003e\n    \u003c/Condition\u003e\n  \u003c/Rule\u003e\n\n\u003c/Policy\u003e\n\n```\n\nIn this example, only those users with `subjectId` (user's role) \"admin\" may write on resources of tenant 511 and subservice 833.\n\nAny number of policies can be included in the Access Control for each pair (tenant, subject). If any of the policies can be applied to the request and `Permit` the request, then the global result is a `Permit`. If none of the policies can be applied (no target exist for the tenant, subservice and subject of the request) the result will be `NotApplicable`. If there are policies that can be applied but all of them deny the access, the result will be a `Deny`.\n\n## \u003ca name=\"administration\"/\u003e Administration\n\n#### Start service\nTo start the service, use either the service command:\nservice pepProxy start\n\nOr just the launch script:\n```\n/etc/init.d/pepProxy start\n```\nFor testing purposes it might be interesting to launch the process directly without the service. That can be done executing the following command from the project root directory:\n```\n./bin/pepProxy\n```\n\nTake into account that when the process is executed manually the system configuration for the script (in /etc/sysconfig/pepProxy) is not loaded and the default configuration (in /opt/pepProxy/config.js) is used. \n\n#### Stop service\nTo stop the service, use either the service command:\n```\nservice pepProxy stop\n```\nOr just the launch script:\n```\n/etc/init.d/pepProxy stop\n```\n### How to check service status\n#### Checking the process is running\nThe status of the process can be retrieved using the service command:\n```\nservice pepProxy status\n```\nIt also can be checked with ps, using a filter with the command name:\n```\nps -ef | grep \"bin/pepProxy\"\n```\nIn both cases a result of 0 (echoing $?) indicates the process is supposed to be running, and an error otherwise.\n#### Checking that the port is listening\nThe following command:\n```\nnetstat -ntpl | grep 1026\n```\ncan be used to check the process is listening in the appropriate port (provided the port is the standard 1026). The result should resemble this line:\n```\ntcp   0   0  0.0.0.0:1026     0.0.0.0:*   LISTEN   12179/node\n```\n#### Checking the version in the Administration API\nThe PEP Proxy provides an Administration port that can be used to check whether the proxy is up and listening or down.\nThe administration API consists in a single `/version` path, that returns useful information from the proxy (currently just the listening port and version).\n\nExample of output:\n```\n{\n  \"version\": \"0.4.1-next\",\n  \"port\": 1026\n}\n```\n\n## \u003ca name=\"configuration\"/\u003e Configuration\nAll the configuration of the proxy is stored in the `config.js` file in the root of the project folder. The values set inside config.js operate as the default values for all the important pieces of configuration data, so it is important none of them are removed (you can change them to suit your needs, as long as they have a valid value).\n\nAnother way of configuring the component is through the use of environment variables, although less configuration options are exposed with this mechanism.\n\n### Basic Configuration\nIn order to have the proxy running, there are several basic pieces of information to fill:\n* `config.resource.proxy`: The information of the server proxy itself. Two ports must be configured for the proxy: `port` indicates in which port is the proxy listening for requests; `adminPort` indicates the administration port. E.g.:\n```\n{\n    port: 1026,\n    adminPort: 11211\n}\n```\n* `config.resource.original`: The address and port of the proxied server. E.g.:\n```\n{\n    host: 'localhost',\n    port: 10026\n},\n```\n* `config.access`: connection information to the selected Access Control PDP API. Includes a `disable` flag, to allow the proxy to work in authentication-only mode and a flag to activate accounting access in file. E.g.:\n```\n{\n    disable: false,\n    protocol: 'http',\n    host: 'localhost',\n    port: 7070,\n    path: '/pdp/v3',\n    account: false,\n    accountFile: '/tmp/pepAccount.log',\n    accountMode: 'all'\n}\n```\nAccounting log is only activated when account flag is true, and the logs are produced in a fixed INFO level for accessLogger, redardless of the pep log level.\nNote that accounting log is not rotated, so you should make sure you configure your own rotation system.\nAccounting access log include data about:\n* Attempt was right or not\n* Token\n* Origin\n* UserId\n* UserName\n* ServiceId\n* srv\n* SubServiceId\n* subsrv\n* Action\n* Path\n* Body (Truncated to 100 chars when is valid access)\n* Date\n* Query\nExample of access log:\n```\n\"Right Attempt | ResponseStatus=200 | Token=gAAAAABnBPgPrgwpcAkbQOZIryu5ADUIScyorN3vbPYbTJxTE5AF3RO1y25Tf-sL3EKzvfr_1U3u8IL8ylB4e4B_vD5yZjc9rnrSIqoiC77B7uZ1O1xZCyukq_MkjRxJLqA9yQ5lQtAQCC6ig7Kn5uPhpPD-mhVb7kyQjUw1QjtCiyP7UKXZvKU | Origin=172.17.0.22 | UserId=753b954985bf460fabbd6953c71d50c7 | UserName=adm1 | ServiceId=9f710408f5944c3993db600810e97c83 | srv=smartcity | SubServiceId=/ | subsrv=/ | Action=read | Path=/v2/entities | Query={\\\"limit\\\":\\\"15\\\",\\\"offset\\\":\\\"0\\\",\\\"options\\\":\\\"count\\\"} | Body={} | Date=2024-10-08T09:25:30.441Z\"\n```\n\nNote that the above format is not the same than the regular PEP log (although it is also based in fields separated by `|`, the fields themselves are not the same).\n\nAdditionally a file configAccessMatch could be provided to pep to check matches about some elements involved in current access, regardless is right or not right access. For example:\n* List for users involved\n* List of headers and values\n* List of subpaths in URL request\n* List of subqueries in query request\n* List of strings in body\n\nPEP reloads this file each time it changes without needing restarting PEP itself.\n\nThis is an example of file `configAccessMatch.js` (full path `/opt/fiware-pep-steelskin/configAccessMatch.js` i.e. in a docker image):\n\n```\n// Activity related with a list of users\nconfigAccessMatch.users = [\n    'cracker1', 'cracker2',\n];\n\n// Activity related with request which the following headers\nconfigAccessMatch.headers = [\n    { \"fiware-service\": \"smartcity\" },\n    { \"x-real-ip\": \"127.0.0.1\" }\n];\n\n// Activity related with request including the following subpaths\nconfigAccessMatch.subpaths = [\n    '/v1',\n];\n\n// Activity related with request including the following subqueries\nconfigAccessMatch.subqueries = [\n    'flowControl', 'options',\n];\n\n// Activity related with request including the following strings in body\nconfigAccessMatch.body = [\n    'legacy',\n];\n```\n\nWhen any of theses patterns matches in current access, message access is added with `MATCHED \u003celement\u003e \u003cvalue\u003e` , where `\u003celement\u003e` would be: `USER`, `HEADER \u003cheader-name\u003e`, `SUBPATH`, `SUBQUERY`, `BODY` and `\u003cvalue\u003e` the value which matches. For example:\n\n```\nRight Attempt MATCHED HEADER fiware-service smartcity | ResponseStatus=200 | Token=gAAAAABnBPgPrgwpcAkbQOZIryu5ADUIScyorN3vbPYbTJxTE5AF3RO1y25Tf-sL3EKzvfr_1U3u8IL8ylB4e4B_vD5yZjc9rnrSIqoiC77B7uZ1O1xZCyukq_MkjRxJLqA9yQ5lQtAQCC6ig7Kn5uPhpPD-mhVb7kyQjUw1QjtCiyP7UKXZvKU | Origin=172.17.0.22 | UserId=753b954985bf460fabbd6953c71d50c7 | UserName=adm1 | ServiceId=9f710408f5944c3993db600810e97c83 | srv=smartcity | SubServiceId=/ | subsrv=/ | Action=read | Path=/v2/entities | Query={\\\"limit\\\":\\\"15\\\",\\\"offset\\\":\\\"0\\\",\\\"options\\\":\\\"count\\\"} | Body={} | Date=2024-10-08T09:25:30.441Z\"\n```\nAccount log has three modes: `all`, `matched`, `wrong`. First one `all` includes right and wrong access regardles if matches or not. Second one `matched` includes all wrong and just rigth matches acess. And `wrong` mode only includes all wrong access, regardless is matches or not with patterns.\n\n* `config.componentName`: name of the component that will be used to compose the FRN that will identify the resource to be accessed. E.g.: `orion`.\n* `config.resourceNamePrefix`: string prefix that will be used to compose the FRN that will identify the resource to be accessed. E.g.: `fiware:`.\n* `config.bypass`: used to activate the administration bypass in the proxy. Valid values are `true` or `false`.\n* `config.bypassRoleId`: ID of the role that will be considered to have administrative rights over the proxy (so being transparently proxied without validation). Valid values are Role UUIDs. E.g.: `db50362d5f264c8292bebdb5c5783741`.\n* `config.dieOnRedirectError`: this flags changes the behavior of the PEP Proxy when an error is received when redirecting a request. If the flag is true, the PEP Proxy process is shut down immediately; if it is false, the behavior is the usual: generate a 501 Code error.\n* `config.bodyLimit`: Controls the maximum request body size allowed, in bytes. Default is 1 Mb\n* `config.localPDP`: Use local implementation for validate PDP (Policy Decision Point) or not. This validation is done by the logic in pdp.js file (out of scope of this documentation). Default is false\n\n### Authentication configuration\n* `config.authentication.checkHeaders`: when the proxy is working with the access control disabled (just user authentication), indicates whether the `fiware-service` and `fiware-servicepath` headers should be checked for existance and validity (checking: the headers exist, thy are not empty and the user is really part of the service and subservice mentioned in the header). This option is ignored when authorization is enabled, and considered to be `true` (as the headers constitute a mandatory part of the authorization process). Default value is `true`.\n* `config.authentication.module`: indicates what type of authentication server should be used: keystone or idm. The currently supported one (and default) is `keystone`.\n* `config.authentication.username`: username of the PEP proxy in the IDM. \n* `config.authentication.password`: password of the PEP proxy in the IDM.\n* `config.authentication.domainName`: (only meaningful for Keystone) name of the administration domain the PEP proxy user belongs to.\n* `config.authentication.retries`: as the authentication is based in the use of tokens that can expire, the operations against Keystone are meant to retry with a fresh token. This configuration value indicates how many retries the PEP should perform in case the communication against Keystone fails. The value `0` means the default will be used (default value is 3). The value `-1` implies that it should be retried forever.\n* `cacheTTLs`: the values in this object correspond to the Time To Live of the values of the different caches the PEP uses to cache requests for information in Keystone. The value is expressed in seconds and `0` value implies unlimited.\n* `config.authentication.options`: address, port and other communication data needed to communicate with the Identity Manager. Apart from the host and port, default values should be used. \n\n### Plugin configuration\nThe `config.js` file contains configuration parameter that lets the deployer decide what plugin the proxy should use in order to extract the action type from the request attributes: the `middleware` parameter. This object has two attributes:\n* `require`: indicating the route from the project folder to the module that contains the middleware.\n* `functions`: an array of the middlewares to execute from the selected module.\nAll the currently available plugins are in the folder `lib/plugins/`, and most of them implement a single middleware called `extractAction` (the name for Orion plugin is `extractCBAction`).\nThe following example should work for any plugin following this patterns:\n```\nconfig.middlewares = {\n    require: 'lib/plugins/perseoPlugin',\n\n    functions: [\n        'extractAction'\n    ]\n};\n```\nThe environment variables provide ways of configuring the plugin without taking care of this details.\n\n### Configuration based on environment variables\nSome of the configuration values for the attributes above mentioned can be overriden with values in environment variables. The following table shows the environment variables and what attribute they map to.\n\n| Environment variable            | Configuration attribute                                                   |\n|:--------------------------------|:--------------------------------------------------------------------------|\n| PROXY_PORT                      | config.resource.proxy.port                                                |\n| ADMIN_PORT                      | config.resource.proxy.adminPort                                           |\n| TARGET_HOST                     | config.resource.original.host                                             |\n| TARGET_PORT                     | config.resource.original.port                                             |\n| LOG_LEVEL                       | config.logLevel                                                           |\n| ACCESS_DISABLE                  | config.access.disable                                                     |\n| ACCESS_HOST                     | config.access.host                                                        |\n| ACCESS_PORT                     | config.access.port                                                        |\n| ACCESS_PROTOCOL                 | config.access.protocol                                                    |\n| ACCESS_ACCOUNT                  | config.access.account                                                     |\n| ACCESS_ACCOUNTFILE              | config.access.accountFile                                                 |\n| ACCESS_ACCOUNTMODE              | config.access.accountMode                                                 |\n| AUTHENTICATION_HOST             | config.authentication.options.host                                        |\n| AUTHENTICATION_PORT             | config.authentication.options.port                                        |\n| AUTHENTICATION_PROTOCOL         | config.authentication.options.protocol                                    |\n| AUTHENTICATION_CACHE_PROJECTIDS | config.authentication.cacheTTLs.projectIds                                |\n| AUTHENTICATION_CACHE_ROLES      | config.authentication.cacheTTLs.roles                                     |\n| AUTHENTICATION_CACHE_USERS      | config.authentication.cacheTTLs.users                                     |\n| AUTHENTICATION_CACHE_VALIDATION | config.authentication.cacheTTLs.validation                                |\n| PROXY_USERNAME                  | config.authentication.user                                                |\n| PROXY_PASSWORD                  | config.authentication.password                                            |\n| PROXY_PASSWORD                  | config.authentication.password                                            |\n| COMPONENT_NAME                  | config.componentName                                                      |\n| COMPONENT_PLUGIN                | config.middlewares and config.componentName if no COMPONENT_NAME provided |\n| BODY_LIMIT                      | config.bodyLimit                                                          |\n| AUTHORIZE_BY_LOCAL_PDP          | config.localPDP                                                           |\n\n### Component configuration\nA special environment variable, called `COMPONENT_PLUGIN` can be set with one of this values: `orion`, `perseo`, `keypass` and `rest`. This variable can be used to select what component plugin to load in order to determine the action of the incoming requests. This variable also rewrites `config.componentName` configuration paramenter.\n\n### SSL Configuration\nIf SSL Termination is not available, the PEP Proxy can be configured to listen HTTPS instead of plain HTTP. To activate the SSL:\n\n* Create the appropiate public keys and certificates and store them in the PEP Proxy machine.\n* In the `config.js` file, change the `config.ssl.active` flag to true.\n* In the same ssl object in the configuration, fill the path to the key and cert files.\n\n### Multi-instance configuration\nPEP Proxy is able to start multiple instances by adding and configuring certain files in `/etc/pepProxy.d` and using `pepProxy` service script\n\nIn order to start multiple instances of the proxy, just add one configuration file per instance in the `/etc/pepProxy.d` folder.\n\nIn its starting sequence, the `pepProxy` service looks for files in  `/etc/pepProxy.d` that begins with `pepproxy_` prefix and has `.conf` extension and start (or stop or status or restat) one process for file found.\n\nIt is important to change `PROXY_PORT` and `ADMIN_PORT` to one not used by other PEP intances/services. \n\n## \u003ca name=\"apiaccesscontrol\"/\u003e API With Access Control\nThe validation of each request si done connecting with the Access Control component, which, using the information provided by the PEP Proxy, decides whether the user can execute the selected action in this organization or not. The following is a summary of this interaction with some examples.\n\n\n### Request\nThe XACML Request maps the information extracted from the request and from the IDM (roles, organization and action) to XACML categories (`access-subject`, `resource` and `action`, respectively). \n```\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cRequest xmlns=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17\"\n         xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n         xsi:schemaLocation=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17 http://docs.oasis-open.org/xacml/3.0/xacml-core-v3-schema-wd-17.xsd\"\n         ReturnPolicyIdList=\"false\"\u003e\n    \u003c!-- X-Auth-Token--\u003e\n    \u003cAttributes Category=\"urn:oasis:names:tc:xacml:1.0:subject-category:access-subject\"\u003e\n        \u003cAttribute IncludeInResult=\"false\"\n                   AttributeId=\"urn:oasis:names:tc:xacml:1.0:subject:subject-id\"\u003e\n            \u003cAttributeValue\n                    DataType=\"http://www.w3.org/2001/XMLSchema#int\"\u003e511\u003c/AttributeValue\u003e\n        \u003c/Attribute\u003e\n    \u003c/Attributes\u003e\n    \u003c!-- fiware resource name being accessed: organization id --\u003e\n    \u003cAttributes\n            Category=\"urn:oasis:names:tc:xacml:3.0:attribute-category:resource\"\u003e\n        \u003cAttribute IncludeInResult=\"false\"\n                   AttributeId=\"urn:oasis:names:tc:xacml:1.0:resource:resource-id\"\u003e\n            \u003cAttributeValue DataType=\"http://www.w3.org/2001/XMLSchema#string\"\u003efrn:contextbroker:551:::\u003c/AttributeValue\u003e\n        \u003c/Attribute\u003e\n    \u003c/Attributes\u003e\n    \u003c!-- action performed --\u003e\n    \u003cAttributes\n            Category=\"urn:oasis:names:tc:xacml:3.0:attribute-category:action\"\u003e\n        \u003cAttribute IncludeInResult=\"false\"\n                   AttributeId=\"urn:oasis:names:tc:xacml:1.0:action:action-id\"\u003e\n            \u003cAttributeValue DataType=\"http://www.w3.org/2001/XMLSchema#string\"\u003ecreate\u003c/AttributeValue\u003e\n        \u003c/Attribute\u003e\n    \u003c/Attributes\u003e\n\u003c/Request\u003e\n```\n\n### Response\nThe XACML Response returns a `Decision` element that can have the following values: “Permit”, “Deny”, “NotApplicable” or “Indeterminate”. The subset of allowable values understood by the PEP Proxy is:\n* `Permit`: allows the request to continue its way to the Context Broker.\n* `Deny`: rejects the request, returning a 403 error to the requestor.\n\n\n```\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cResponse xmlns=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17 http://docs.oasis-open.org/xacml/3.0/xacml-core-v3-schema-wd-17.xsd\"\u003e\n    \u003cResult\u003e\n        \u003cDecision\u003ePermit\u003c/Decision\u003e\n    \u003c/Result\u003e\n\u003c/Response\u003e\n```\n## \u003ca name=\"rules\"/\u003e Rules to determine the Context Broker action from the request\n\n### Available actions\n\nThis is the list of actions available for the Context Broker. For every action, the abbreviature is also shown (will be used in some of the following tables). \n\n| Action | Abbreviature |\n| ------ |:------------:|\n| create | C            |\n| update | U            |\n| delete | D            |\n| read | R            |\n| subscribe | S            |\n| register | Reg           |\n| discover | Dis            |\n| N/A | - |\n\n#### NGSIv2\n| Method | Path                                                                                    | Action |\n| ------ |:--------------------------------------------------------------------------------------- | ---:|\n| GET    | /v2                                                                                     | R |\n| GET    | /v2/entities                                                                            | R |\n| GET    | /v2/entities/{entityId}                                                                | R |\n| GET    | /v2/entities/{entityId}/attrs                                                          | R |\n| POST   | /v2/entities                                                                           | C |\n| PATCH  | /v2/entities/{entityId}/attrs                                                          | U |\n| POST   | /v2/entities/{entityId}/attrs                                                          | U |\n| POST   | /v2/entities/{entityId}/attrs?options=append                                           | C |\n| DELETE | /v2/entities/{entityId}                                                                | D |\n| PUT    | /v2/entities/{entityId}/attrs                                                          | U |\n| GET    | /v2/entities/{entityId}/attrs/{attrId}                                                 | R |\n| PUT    | /v2/entities/{entityId}/attrs/{attrId}                                                 | U |\n| DELETE | /v2/entities/{entityId}/attrs/{attrId}                                                 | D |\n| GET    | /v2/entities/{entityId}/attrs/{attrId}/value                                           | R |\n| PUT    | /v2/entities/{entityId}/attrs/{attrId}/value                                           | U |\n| GET    | /v2/types                                                                              | R |\n| GET    | /v2/types/{typeId}                                                                     | R |\n| GET    | /v2/subscriptions                                                                      | R |\n| POST   | /v2/subscriptions                                                                      | C |\n| GET    | /v2/subscriptions/{subscriptionId}                                                     | R |\n| PATCH  | /v2/subscriptions/{subscriptionId}                                                     | U |\n| DELETE | /v2/subscriptions/{subscriptionId}                                                     | D |\n| POST   | /v2/op/query                                                                           | R |\n| POST   | /v2/op/update                                                                          | (*) |\n\n(*) It depends on the `actionType` (within payload):\n\n* update: U\n* append: C\n* appendStrict: C\n* delete: D\n* replace: U\n\nOperations marked with a slash, \"-\" are now deprecated. All those operations will be tagged with the special action \"N/A\". If you want to allow them anyway, just add a rule to the Access Control allowing the \"N/A\" action for the desired roles.\n\n## \u003ca name=\"rulesPerseo\"/\u003e Rules to determine the Perseo CEP action from the request\n\nThe available actions are:\n* **readRule**: to get working rules in CEP\n* **writeRule**: to modify rules in CEP (create, delete, update)\n* **notify**: to fire rules (if appropiate) with an event notification\n\nThe following tables show the map from method and path of the request to the action. \n\n### Notifications\n| Method | Path |  Action |\n| ------ |:-----|:------------|\n| POST   | /notices | notify|\n\n### Rules\n| Method | Path        | Action| \n| ------ |:-------------|:-----------|\n| GET    | /rules      | readRule  |\n| GET    | /rules/{id} | readRule  |\n| POST   | /rules      | writeRule |\n| DELETE | /rules/{id} | writeRule |\n\n### Visual Rules\n| Method | Path    |  Action |\n| ------ |:--------|:------------|\n| GET    | /m2m/vrules          | readRule |\n| GET    | /m2m/vrules/{id}       | readRule |\n| POST   | /m2m/vrules          | writeRule |\n| DELETE | /m2m/vrules/{id}     | writeRule |\n| PUT    | /m2m/vrules/{id}       | writeRule |\n\n## \u003ca name=\"rulesKeypass\"/\u003e Rules to determine the Keypass Access Control action from the request\nThe available actions are:\n* **createPolicy**: to create a new policy for a subject in Keypass.\n* **listPolicies**: to list all the policies belonging to a subject.\n* **deleteSubjectPolicies**: to remove all the policies for a particular subject.\n* **deleteTenantPolicies**: to remove all the policies for all the subjects of a tenant.\n* **readPolicy**: to get the policy body for a particular policy.\n* **deletePolicy**: to remove a single policy of a subject.\n\nThe following table show the map from method and path of the request to the action.\n\n| Method | Path        | Action|\n| ------ |:-------------|:-----------|\n| POST    | /pap/v1/subject/{subjectId}      | createPolicy  |\n| GET    | /pap/v1/subject/{subjectId}       | listPolicies  |\n| DELETE    | /pap/v1/subject/{subjectId}       | deleteSubjectPolicies  |\n| DELETE    | /pap/v1      | deleteTenantPolicies  |\n| GET    | /pap/v1/subject/{subjectId}/policy/{policyId}      | readPolicy  |\n| DELETE    | /pap/v1/subject/{subjectId}/policy/{policyId}      | deletePolicy  |\n\n## \u003ca name=\"customizing\"/\u003e Customizing PEP Proxy for other components\nMost of the code of the proxy (i.e. the extraction of user data, the communication with the Keystone Proxy and the proxy process itself) will execute exactly the same for all the components. The exception is the rule to determine the action the request is trying to perform. To address this behavior and possible actions different customizations of the proxy could need, the proxy allows for the introduction of middlewares in the validation process.\n\n### Middleware definition\nThe middlewares are quite similar to the ones used by the Connect (or Express) framework. A middleware is a function that receives three parameters:\n\n* req: The object representing the incoming HTTP request. Along with all the request information, the request is used to store the information for the validation process (i.e. attributes `userId` with the user token, `organization` with the organization extracted from the headers and `action` that should be filled in by the middlewares).\n* res: The object representing the response. This object can be used to stop the request pipeline due to conditions defined by the specific component (although it is advisable to use a `next(error)` call with a custom error to allow the error to be handled by the proxy).\n* next: Callback used to call the next middleware in the chain. In the current version, it is required that the call to the next middleware contains both the request and response objects (this behavior is not the same as the one in Connect middlewares). If the first parameter in the call is an error, the request will be rejected. If the first parameter is null or undefined, the request will continue through the validation process. This is an example of a call to next that lets the request follow through:\n\n```\nnext(null, req, res);\n```\n\n### Middleware configuration\nThe middlewares must be defined inside a Node.js module. They can be configured using the `config.middlewares` object of the `config.js` file. This object contains two attributes:\n\n* `require`: path to the module that contains the middlewares, from the project root. The system currently supports only modules defined inside the fiware-pep-steelskin project (or in accessible folders).\n* `functions`: list of the middlewares to load. The names in this list must be exported functions of the module selected in the previous attribute.\n\n### Generic REST Middleware\nFor standard REST APIs that make use exclusively of the POST, PUT, DELETE and GET methods with their CRUD meaning, the PEP Proxy provides a generic plugin that maps those methods to actions in the access request. To configure it, put the following lines in the middleware section of the PEP Proxy installation:\n\n```\nconfig.middlewares = {\n   require: 'lib/services/restPlugin',\n   \n   functions: [\n     'extractAction'\n   ]\n};\n```\nIn order to add more expression power to the authorization rules created in the Access Control component, the Generic REST Plugin adds a new element to the FRN: the URL of the resource is appended to the existing elements in the FRN.\n\n### URL Table Generic middleware\nFor applications that require a mapping between URLs and Method to actions when the REST Middleware is not enough, a plugin generator based on tables is provided. In order to use this plugin, create a new plugin file and import the `./urlTablePlugin` module. This module contains just one function, `extractAction`, that takes a mapping table and generates a middleware function that extract the action of a request based on it. \n\nThe mapping table has to have one row for each action to check indicating:\n* Request **Method**\n* **URL** pattern (using regular expressions)\n* **Action** name\nWhenever a request arrives to the plugin with the selected method and a URL that matches the URL expression, the action will be assigned to the request.\n\nAn example of use of the `urlTablePlugin` can be found in the Perseo plugin.\n\n## \u003ca name=\"licence\"/\u003e License\n\nOrion FiWare Policy Enforcement Point is licensed under Affero General Public License (GPL) version 3.\n\n## \u003ca name=\"development\"/\u003e Development documentation\n### Project build\nThe project is managed using npm.\n\nFor a list of available task, type\n```bash\nnpm run\n```\n\nThe following sections show the available options in detail.\n\n### Testing\n[Mocha](http://visionmedia.github.io/mocha/) Test Runner + [Should.js](https://shouldjs.github.io/) Assertion Library.\n\nThe test environment is preconfigured to run BDD testing style.\n\nModule mocking during testing can be done with [proxyquire](https://github.com/thlorenz/proxyquire)\n\nTo run tests, type\n\n```bash\nnpm test\n```\n\n### Coding guidelines\njshint\n\nUses provided .jshintrc flag file.\nTo check source code style, type\n\n```bash\nnpm run lint\n```\n\n### Continuous testing\n\nSupport for continuous testing by modifying a src file or a test.\nFor continuous testing, type\n\n```bash\nnpm run test:watch\n```\n\nIf you want to continuously check also source code style, use instead:\n\n```bash\nnpm run watch\n```\n\n### Code Coverage\nIstanbul\n\nAnalizes the code coverage of your tests.\n\nTo generate an HTML coverage report under `site/coverage/` and to print out a summary, type\n\n```bash\n# Use git-bash on Windows\nnpm run test:coverage\n```\n\n### Clean\n\nRemoves `node_modules` and `coverage` folders, and  `package-lock.json` file so that a fresh copy of the project is restored.\n\n```bash\n# Use git-bash on Windows\nnpm run clean\n```\n\n### Releasing\nThe project contains a script to aid in the releasing process. This script is located in the `scripts/build` folder. In\norder to create a new release, just invoke the script, from the project root folder, with the following line:\n```\nscripts/build/release.sh \u003cNEW_VERSION\u003e \u003cRELEASE_TYPE\u003e\n```\nUsually, `RELEASE_TYPE` will be `sprint`. This release procedure will do the following steps:\n* Change the version in package.json to the selected version.\n* Create a branch `release/0.6.0` and a tag `0.6.0` from `master`.\n* Add the `-next` suffix to the version in master and clean the `CHANGES_NEXT_RELEASE` file.\n\nFor other release types, check the command help.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelefonicaid%2Ffiware-pep-steelskin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelefonicaid%2Ffiware-pep-steelskin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelefonicaid%2Ffiware-pep-steelskin/lists"}