Policy Enforcement Point for EOEPCA project
Explore the docs »
Report Bug
·
Request Feature
- Table of Contents
- Getting Started
- Dependencies
- Configuration
- Usage & functionality
- Developer documentation
- Roadmap
- Contributing
- License
- Contact
- Acknowledgements
To get a local copy up and running follow these simple steps.
This is an example of how to list things you need to use the software and how to install them.
- Get into EOEPCA's development environment
vagrant ssh
- Clone the repo
git clone https://github.com/EOEPCA/um-pep-engine.git
- Change local directory
cd um-pep-engine
The PEP is written and tested for python 3.6.9, and has all dependencies listed in src/requirements.txt
The PEP gets all its configuration from the file located under config/config.json
.
The parameters that are accepted, and their meaning, are as follows:
- realm: 'realm' parameter answered for each UMA ticket. Default is "eoepca"
- auth_server_url: complete url (with "https") of the Authorization server.
- proxy_endpoint: "/path"-formatted string to indicate where the reverse proxy should listen. The proxy will catch any request that starts with that path. Default is "/pep"
- service_host: Host for the proxy to listen on. For example, "0.0.0.0" will listen on all interfaces
- service_port: Port for the proxy to listen on. By default, 5566. Keep in mind you will have to edit the docker file and/or kubernetes yaml file in order for all the prot forwarding to work.
- s_margin_rpt_valid: An integer representing how many seconds of "margin" do we want when checking RPT. For example, using 5 will make sure the provided RPT is valid now AND AT LEAST in the next 5 seconds.
- check_ssl_certs: Toggle on/off (bool) to check certificates in all requests. This should be forced to True in a production environment
- use_threads: Toggle on/off (bool) the usage of threads for the proxy. Recommended to be left as True.
- debug_mode: Toggle on/off (bool) a debug mode of Flask. In a production environment, this should be false.
- resource_server_endpoint: Complete url (with "https" and any port) of the Resource Server to protect with this PEP.
- client_id: string indicating a client_id for an already registered and configured client. This parameter is optional. When not supplied, the PEP will generate a new client for itself and store it in this key inside the JSON.
- client_secret: string indicating the client secret for the client_id. This parameter is optional. When not supplied, the PEP will generate a new client for itself and store it in this key inside the JSON.
Use directly from docker with
docker run --publish <configured-port>:<configured-port> <docker image>
Where configured-port is the port configured inside the config.json file inside the image. The default image is called eoepca/um-pep-engine:latest.
If this is running in a development environment without proper DNS setup, add the following to your docker run command:
--add-host <auth-server-dns>:<your-ip>
When launched, the PEP will answer to all requests that start with the configured path. These answers will come in the form of UUMA tickets (if there are no RPT provided, or an invalid one is used). In case the request is accompained by an "Authorization: Bearer <valid_RPT>", the PEP will make a request to the resource server, for the resource located exactly at the path requested (minus the configured at config), and return the resource's server answer.
Examples, given the example values of:
- path configured: "/pep"
- PEP is at pep.domain.com/pep
- Resource server is at remote.server.com
Token | Request to PEP | PEP Action | PEP answer |
---|---|---|---|
No RPT | pep.domain.com | None (request does not get to PEP endpoint) | None (the PEP doesn't see this request) |
No RPT | pep.domain.com/pep/thing | Generate ticket for "/thing" | 401 + ticket |
Valid RPT for "/thing" | pep.domain.com/pep/thing | Request to remote.server.com/thing | Contents of remote.server.com/thing |
Valid RPT for "/thing" | pep.domain.com/pep/different | Generate ticket for "/different" | 401 + ticket |
INVALID RPT for "/thing" | pep.domain.com/pep/thing | Generate ticket for "/thing" | 401 + ticket |
No RPT | pep.domain.com/pep/thing/with/large/path | Generate ticket for "/thing/with/large/path" | 401 + ticket |
Valid RPT for "/thing/with/large/path" | pep.domain.com/pep/thing/with/large/path | Request to remote.server.com/thing/with/large/path | Contents of remote.server.com/thing/with/large/path |
At the moment, the PEP will auto register a resource for the sake of demoing it's capabilities, using the create
function of the UMA handler. This can be deleted if unwanted, or expanded to dinamically register resources. Note that the UMA library used allows for full control over resources (create, delete, etc) and could be used to help in that functionality expansion.
The PEP uses the following endpoints from a "Well Known Handler", which parses the Auth server's "well-known" endpoints:
- OIDC_TOKEN_ENDPOINT
- UMA_V2_RESOURCE_REGISTRATION_ENDPOINT
- UMA_V2_PERMISSION_ENDPOINT
- UMA_V2_INTROSPECTION_ENDPOIN
The internal UMA handler works with an in-memory list of resources at self.registered_resources
, and uses that to get it's data.
This can be expanded to a better database, by replacing the functions update_resources_from_as
and add_resource_to_cache
, which control how this cache is refreshed and written to, respectively
See the open issues for a list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Distributed under the Apache-2.0 License. See LICENSE
for more information.
Project Link: https://github.com/EOEPCA/um-pep-engine
- README.md is based on this template by Othneil Drew.