{"id":13903176,"url":"https://github.com/hexa-org/policy-orchestrator","last_synced_at":"2025-04-30T12:35:20.827Z","repository":{"id":38447700,"uuid":"444656703","full_name":"hexa-org/policy-orchestrator","owner":"hexa-org","description":"Hexa Policy Orchestrator enables you to manage all of your access policies consistently across software providers.","archived":false,"fork":false,"pushed_at":"2024-05-22T20:11:02.000Z","size":4385,"stargazers_count":92,"open_issues_count":45,"forks_count":16,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-05-22T20:38:56.977Z","etag":null,"topics":["cloud-native","policy-as-code","security"],"latest_commit_sha":null,"homepage":"https://hexaorchestration.org/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hexa-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-05T03:56:57.000Z","updated_at":"2024-05-27T22:54:53.082Z","dependencies_parsed_at":"2024-02-10T22:22:58.182Z","dependency_job_id":"d1dd6ce4-d3b8-4f95-9205-dd33358401b6","html_url":"https://github.com/hexa-org/policy-orchestrator","commit_stats":null,"previous_names":["hexa-org/almostopen"],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexa-org%2Fpolicy-orchestrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexa-org%2Fpolicy-orchestrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexa-org%2Fpolicy-orchestrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexa-org%2Fpolicy-orchestrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexa-org","download_url":"https://codeload.github.com/hexa-org/policy-orchestrator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235426493,"owners_count":18988420,"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":["cloud-native","policy-as-code","security"],"created_at":"2024-08-06T22:01:43.910Z","updated_at":"2025-01-24T11:09:09.198Z","avatar_url":"https://github.com/hexa-org.png","language":"Shell","funding_links":[],"categories":["security"],"sub_categories":[],"readme":"# Table of Contents\n\n- [Hexa Policy Orchestrator](#hexa-policy-orchestrator)\n * [Getting Started](#getting-started)\n + [Build the Hexa image](#task-build-the-hexa-orchestrator-image)\n + [Run the Policy Orchestrator](#task-run-the-policy-orchestrator)\n * [Application descriptions](#application-descriptions)\n + [Example workflow](#example-workflow)\n * [Getting involved](#getting-involved)\n\n![hexa-logo](docs/hexa-logo.svg)\n\n# Hexa Policy Orchestrator\n\n[![Build results](https://github.com/hexa-org/policy-orchestrator/workflows/build/badge.svg)](https://github.com/hexa-org/policy-orchestrator/actions)\n[![Go Report Card](https://goreportcard.com/badge/hexa-org/policy-orchestrator)](https://goreportcard.com/report/hexa-org/policy-orchestrator)\n[![codecov](https://codecov.io/gh/hexa-org/policy-orchestrator/branch/main/graph/badge.svg)](https://codecov.io/gh/hexa-org/policy-orchestrator)\n[![CodeQL](https://github.com/hexa-org/policy-orchestrator/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/hexa-org/policy-orchestrator/actions/workflows/codeql-analysis.yml)\n\nHexa Policy Orchestrator enables you to manage all of your policies consistently across software providers\nso that you can unify access policy management. The below diagram describes the current provider architecture.\n\n![Hexa Provider Architecture](docs/hexa-provider-architecture.svg \"hexa provider architecture\")\n\n## Getting Started\n\nThe Hexa project contains two applications, and demonstrates use of applications\nfrom [Policy-Opa](https://github.com/hexa-org/policy-opa)\n\n- Policy Orchestrator with policy translations\n- Demo Policy Administrator\n- Demo web application (Policy-OPA)\n- Hexa OPA Server and Bundle Server (Policy-OPA)\n\nTo get started with running these, clone or download the codebase from GitHub to your local machine:\n\n```bash\ncd $HOME/workspace # or similar\ngit clone git@github.com:hexa-org/policy-orchestrator.git\n```\n\n### Prerequisites\n\nInstall the following dependencies.\n\n- [Go 1.22](https://go.dev) - Needed to compile and install\n- [Docker Desktop](https://www.docker.com/products/docker-desktop) - Needed to run docker-compose configuration\n\n### Task: Build the Hexa Orchestrator image\n\nBuild the Hexa Orchestrator Docker containers...\n\n```bash\ncd demo\nsh ./build.sh\n```\n\n### Task: Run the Policy Orchestrator\n\nThese commands are to be run within the `demo` directory\n\nStart the shared KeyCloak and Postgres Server instance.\n\u003e [!Note]\n\u003e This is the same file found in [Hexa-OPA](https://github.com/hexa-org/policy-opa) project and only needs to be run\n\u003e once for both projects.\n\n```bash\ndocker-compose -f docker-compose.shared.yml\n```\n\nWhen Keycloak is up and running docker will also create a network called `hexa_network` which enables services in\ndocker-compose.yml to talk to services in the shared docker-compose.\n\n```bash\ndocker-compose up\n```\n\n## Application Descriptions\n\nDocker runs the following applications:\n\n- **hexa-orchestrator**\n\n Runs on [localhost:8885](http://localhost:8885/health). The main application service API\n that manages IDQL policy across various platforms and communicates with the\n various platform interfaces, converting IDQL policy to and from the respective\n platform types using the [Hexa Policy-Mapper](https://github.com/hexa-org/policy-mapper) SDK. This service uses TLS\n and is protected and uses JWT authorization tokens\n (see [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519)) for authenticating access.\n\n- **hexa-admin-ui**\n\n Runs on [localhost:8884](http://localhost:8884/). An example web application user-interface\n demonstrating the latest interactions with the policy orchestrator. Uses `hexa-orchestrator` to retrieve and provision\n policy.\n \u003cp/\u003e\n The Hexa Admin UI service uses the OAuth2 Client Credentials Grant Flow (see [RFC6749 Section 4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)) to authenticate to a token server (e.g. Keycloak) and obtain tokens for accessing\n the Hexa-Orchestrator API service using JWT tokens.\n\n- **hexa-industry-demo-app**\n\n Runs on [localhost:8886](http://localhost:8886/). A demo web application used to\n highlight enforcing of both coarse and fine-grained policy. The application\n integrates with platform authentication/authorization proxies,\n [Google IAP](https://cloud.google.com/iap) for example, for coarse-grained\n access and the [Open Policy Agent (OPA)](https://www.openpolicyagent.org/)\n for fine-grained policy access. In the docker-compose configuration, the server uses the Hexa-OPA-Server\n\n- **hexa-opa-agent**\n\n Runs on [localhost:8887](http://localhost:8887/). HexaOPA is\n an [IDQL extended](https://github.com/hexa-org/policy-opa) Open Policy Agent ([OPA](https://openpolicyagent.org))\n server used as an IDQL Policy Decision service. In this configuration, The `hexa-opa-agent` server retrieves policies\n from\n the `hexa-opaBundle-server` instance which is an OPA provisioning service.\n\n- **hexa-opaBundle-server**\n\n Runs on [localhost:8889](http://localhost:8889/health). An OPA HTTP Bundle server from which the OPA server can\n download policy bundles configured\n by Hexa-Orchestrator. See [OPA bundles][opa-bundles] for more info.\n\n- **keycloak** and **postgres**\n\n These two servers are used to provide an OAuth2 demonstration and testing environment for the Hexa\n demonstration environment. [Keycloak](https://www.keycloak.org) is pre-configured with a demonstration security \"\n realm\" called\n [Hexa-Orchestrator-Realm](http://localhost:8080/admin/master/console/#/Hexa-Orchestrator-Realm).\n\n - The Keycloak administrative interface can be accessed (after starting docker-compose.shared.yml) using the\n URL http://localhost:8080. The default administrative account is admin/not4u2no and the credential should be\n changed immediately. After logging in, select the \"Hexa-Orchestrator-Realm\" using the drop-down box in the\n upper-left corner.\n\n - This Hexa-Orchestrator-Realm contains role definitions and Client credential enabling Hexa Admin UI service to\n access the Hexa Orchestrator service. By\n default, a bootstrap admin user id and password are configured (see .env_development). It is strongly recommended\n that these be changed.\n\n - The realm also contains four test user account each with the password \"hexahexa\". These accounts are for\n demonstration purposes only.\n - Four test accounts: alice@hexaindustries.io, bob@hexaindustries.io, carol@hexaindustries.io, and\n gerry@hexaindustries.io\n - Each account is a member of a different group with different access rights to to the Hexa Industries Demo app\n\n\u003e [!Note]\n\u003e Keycloak is used for demonstration purposes and was selected as part of\n\u003e the [CNCF community](https://www.cncf.io/projects/keycloak/).\n\u003e Hexa-OPA and Hexa-Orchestrator projects can be configured to use other OIDC providers. See the Environment Variables\n\u003e section below.\n\n## Configuration\n\n### TLS Support\n\nIn the current release, except for the Hexa Admin UI, and Hexa Industries Demo application, all Hexa services now auto\nconfigure with TLS support. In general if HEXA_SERVER_KEY_PATH is not specified for a server, the startup code will do\nthe following:\n\n1. Locks the directory to avoid conflict with other server instances\n2. Look for an existing CA key pair\n3. If not found, generates a new key pair\n4. Generates a server TLS key pair using the DNS names specified. Note: in docker, it is best to give each server\n instance it's own key file name and DNS name.\n5. Releases the directory lock\n\n\u003e [!Note]\n\u003e The lock procedure is done to ensure only 1 set of keys is generated so that all servers will share the same\n\u003e self-signed key root.\n\nWhen a second server starts and obtains a lock, it will use the CA key pair generated by the first server to generate\nits own server\nkey pair.\n\nThe intent of this procedure to use TLS whenever possible and to make demonstrations and development easy to set up and\nconfigure. For production use, use externally generated keys from appropriate certificate authorities and assign the key\nfiles to paths using the appropriate environment variable.\n\n\u003e [!Tip]\n\u003e When installing in a cloud service provider that will be doing TLS termination, set the value of `HEXA_TLS_ENABLED`\n\u003e and\n\u003e `HEXA_AUTO_SELFSIGN` to false.\n\n### OAuth2 Support\n\nThe Hexa Administration Server currently supports unauthenticated access only and should be installed in a protected\nlocation. It\nwill be upgraded shortly to support Open Identify (OIDC) based authentication.\n\nThe Hexa Administration server now makes provisioning calls to Hexa Orchestrator over secured TLS communications using\nthe OAuth2 Client\nCredentials Grant ([RFC6749 Section 4.4](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4)). In the\ndocker-compose file, a demonstration configuration is set-up using [KeyCloak](https://keycloak.org)\nto authenticate client requests and issue tokens for accessing the Hexa Orchestration Service.\n\n\u003e [!Important]\n\u003e To facilitate easy setup for demonstration, Keycloak is preconfigured with a realm (Hexa_Orchestrator_Realm), and a\n\u003e client credential. The root\n\u003e password to Keylcloak and the `hexaclient` client secret should be changed! See\n\u003e Keycloak [documentation](https://www.keycloak.org/guides#server).\n\n### Environment Variables\n\n| Name | Default | Description |\n|-----------------------------------------------------------------------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| HEXA_TLS_ENABLED | false | Enable TLS if supported (default: False) |\n| HEXA_CERT_DIRECTORY | $HOME/.certs | Directory where PEM files are stored and generated |\n| HEXA_CA_KEYFILE | ca-key.pem | Private key PEM file used to generate self-signed TLS certs |\n| HEXA_CA_CERT | ca-cert.pem | Certificate Authority Public Key PEM file. Used to validate server certificates |\n| HEXA_SERVER_KEY_PATH | server-key.pem | Server private key file used to establish TLS services. |\n| HEXA_SERVER_CERT | server-cert.pem | TLS Public certificate file for establishing TLS services |\n| HEXA_SERVER_DNS_NAME | | Comma separated list of DNS names. Used when auto-generating a server TLS certificate |\n| HEXA_AUTO_SELFSIGN | true | When set to false, server will not attempt to auto generate self-signed certificaes |\n| HEXA_CERT_ORG, \u003cbr/\u003eHEXA_CERT_COUNTRY,\u003cbr/\u003eHEXA_CERT_PROV,\u003cbr/\u003eHEXA_CERT_LOCALITY | | Values to be used when generating TLS certificates |\n| HEXA_TOKEN_JWKSURL | \u003cnone\u003e | When using token based authentication, the URL of the JWKS endpoint |\n| HEXA_JWT_AUTH_ENABLE | false | Enable token based authentication |\n| HEXA_JWT_REALM | undefined | The OAuth2 realm - used in error message response to clients to indicate token issuer |\n| HEXA_JWT_AUDIENCE | orchestrator | The audience value that should be present in received tokens (used by Orchestrator API) |\n| HEXA_JWT_SCOPE | orchestrator | Token 'scope' claim value expected (e.g. `orchestrator`) |\n| HEXA_OAUTH_CLIENT_ID | | The OAuth ClientId value used by Admin UI at the OAuth Token Endpoint |\n| HEXA_OAUTH_CLIENT_SECRET | | OAuth Client secret used in the client credentials flow |\n| HEXA_OAUTH_CLIENT_SCOPE | | If supplied, the scope value to be passed in the Client Credentials Grant request |\n| HEXA_OAUTH_TOKEN_ENDPOINT | | The OAUTH2 Token endpoint URL used to execute the client credentials grant.\u003cbr/\u003eExample: \u003ctt\u003ehttp://keycloak:8080/realms/Hexa-Orchestrator-Realm/protocol/openid-connect/token\u003c/tt\u003e |\n| HEXA_OIDC_ENABLED\" | false | Enable OIDC Authentication in servers that support a web interface |\n| HEXA_OIDC_CLIENT_ID | ${HEXA_OAUTH_CLIENT_SECRET} | OIDC Client Id used when initiating OIDC OP Authorization Flow |\n| HEXA_OIDC_CLIENT_SECRET | ${HEXA_OAUTH_CLIENT_SECRET} | Secret associated with OIDC Client Id |\n| HEXA_OIDC_PROVIDER_NAME | \"OpenID Login\" | Login button display test used to indicate where login will occur |\n| HEXA_OIDC_PROVIDER_URL | \u003cnone\u003e | The OIDC Provider URL (well-known endpoint), if missing authentication will be disabled with warning\u003cbr/\u003eExample: \u003ctt\u003ehttp://keycloak:8080/realms/Hexa-Orchestrator-Realm\u003c/tt\u003e |\n| HEXA_OIDC_REDIRECT_URL | \"/redirect\" | The URL that the OpenId server will redirect back to get to the configured server. It is the URL that the end-user browser would use. Usually this URL must align with the configured redirect URL in the OpenID Provider services client configuration.\u003cbr/\u003eExample: \u003ctt\u003ehttp://admin.hexa.org:8884/redirect\u003c/tt\u003e |\n\n## Example Workflow\n\nFine-grained policy management with OPA.\n\nUsing the **hexa-admin-ui** application available via `docker-compose`, upload an\nOPA integration configuration file. The file describes the location of the IDQL\npolicy. An example integration configuration file may be found in\n[deployments/opa-server/example](demo/deployments/hexaOpaServer/example).\n\nOnce configured, IDQL policy for the **hexa-demo** application can be modified\non the [Applications](http://localhost:8884/applications) page. The\n**hexa-admin** communicates the changes to the **hexa-orchestrator**, or\n\"Policy Management Point (PMP)\", which then updates the **hexa-demo-config** bundle\nserver, making the updated policy available to the OPA server.\n\nOPA, the \"Policy Decision Point (PDP)\", periodically reads config from the\n**hexa-demo-config** bundle server and allows or denies access requests based on\nthe IDQL policy. Decision enforcement is handled within the **hexa-demo**\napplication or \"Policy Enforcement Point (PEP)\".\n\nThe Hexa Demo architecture may be visualized as follows (note: POSTGRES is no longer used by Hexa-Orchestrator and now\nuses a JSON based configuration file specified by `ORCHESTRATOR_CONFIG_FILE`):\n\n![Hexa Demo Architecture](docs/hexa-demo-architecture.svg \"hexa demo architecture\")\n\n## Getting involved\n\nTake a look at our [product backlog](https://github.com/orgs/hexa-org/projects/1)\nwhere we maintain a fresh supply of good first issues. In addition to\nenhancement requests, feel free to post any bugs you may find.\n\n- [Backlog](https://github.com/orgs/hexa-org/projects/1)\n\nHere are a few additional resources for those interested in contributing to the\nHexa project:\n\n- [Contributing](CONTRIBUTING.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Development](DEVELOPMENT.md)\n- [Security](SECURITY.md)\n\nThis [repository](https://github.com/hexa-org/policy-orchestrator) also includes\n[documentation](docs/infrastructure/README.md) for the current demo deployment\ninfrastructure.\n\n[opa-bundles]: https://www.openpolicyagent.org/docs/latest/management-bundles/\n\n\u003cfooter\u003e\n \u003cp\u003eThe Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, \n please see our \u003ca href=\"https://www.linuxfoundation.org/legal/trademark-usage\"\u003eTrademark Usage page\u003c/a\u003e.\n \u003c/p\u003e\n\u003c/footer\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexa-org%2Fpolicy-orchestrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexa-org%2Fpolicy-orchestrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexa-org%2Fpolicy-orchestrator/lists"}