Hexa Policy Orchestrator enables you to manage all of your policies consistently across software providers so that you can unify access policy management. The below diagram describes the current provider architecture.
The Hexa project contains two applications, and demonstrates use of applications from Policy-Opa
- Policy Orchestrator with policy translations
- Demo Policy Administrator
- Demo web application (Policy-OPA)
- Hexa OPA Server and Bundle Server (Policy-OPA)
To get started with running these, clone or download the codebase from GitHub to your local machine:
cd $HOME/workspace # or similar
git clone [email protected]:hexa-org/policy-orchestrator.gitInstall the following dependencies.
- Go 1.22 - Needed to compile and install
- Docker Desktop - Needed to run docker-compose configuration
Build the Hexa Orchestrator Docker containers...
cd demo
sh ./build.shThese commands are to be run within the demo directory
Start the shared KeyCloak and Postgres Server instance.
Note
This is the same file found in Hexa-OPA project and only needs to be run once for both projects.
docker-compose -f docker-compose.shared.ymlWhen Keycloak is up and running docker will also create a network called hexa_network which enables services in
docker-compose.yml to talk to services in the shared docker-compose.
docker-compose upDocker runs the following applications:
-
hexa-orchestrator
Runs on localhost:8885. The main application service API that manages IDQL policy across various platforms and communicates with the various platform interfaces, converting IDQL policy to and from the respective platform types using the Hexa Policy-Mapper SDK. This service uses TLS and is protected and uses JWT authorization tokens (see RFC7519) for authenticating access.
-
hexa-admin-ui
Runs on localhost:8884. An example web application user-interface demonstrating the latest interactions with the policy orchestrator. Uses
hexa-orchestratorto retrieve and provision policy.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 the Hexa-Orchestrator API service using JWT tokens.
-
hexa-industry-demo-app
Runs on localhost:8886. A demo web application used to highlight enforcing of both coarse and fine-grained policy. The application integrates with platform authentication/authorization proxies, Google IAP for example, for coarse-grained access and the Open Policy Agent (OPA) for fine-grained policy access. In the docker-compose configuration, the server uses the Hexa-OPA-Server
-
hexa-opa-agent
Runs on localhost:8887. HexaOPA is an IDQL extended Open Policy Agent (OPA) server used as an IDQL Policy Decision service. In this configuration, The
hexa-opa-agentserver retrieves policies from thehexa-opaBundle-serverinstance which is an OPA provisioning service. -
hexa-opaBundle-server
Runs on localhost:8889. An OPA HTTP Bundle server from which the OPA server can download policy bundles configured by Hexa-Orchestrator. See OPA bundles for more info.
-
keycloak and postgres
These two servers are used to provide an OAuth2 demonstration and testing environment for the Hexa demonstration environment. Keycloak is pre-configured with a demonstration security " realm" called Hexa-Orchestrator-Realm.
-
The Keycloak administrative interface can be accessed (after starting docker-compose.shared.yml) using the URL https://localhost:8080. The default administrative account is admin/not4u2no and the credential should be changed immediately. After logging in, select the "Hexa-Orchestrator-Realm" using the drop-down box in the upper-left corner.
-
This Hexa-Orchestrator-Realm contains role definitions and Client credential enabling Hexa Admin UI service to access the Hexa Orchestrator service. By default, a bootstrap admin user id and password are configured (see .env_development). It is strongly recommended that these be changed.
-
The realm also contains four test user account each with the password "hexahexa". These accounts are for demonstration purposes only.
- Four test accounts: [email protected], [email protected], [email protected], and [email protected]
- Each account is a member of a different group with different access rights to to the Hexa Industries Demo app
-
Note
Keycloak is used for demonstration purposes and was selected as part of the CNCF community. Hexa-OPA and Hexa-Orchestrator projects can be configured to use other OIDC providers. See the Environment Variables section below.
In the current release, except for the Hexa Admin UI, and Hexa Industries Demo application, all Hexa services now auto configure with TLS support. In general if HEXA_SERVER_KEY_PATH is not specified for a server, the startup code will do the following:
- Locks the directory to avoid conflict with other server instances
- Look for an existing CA key pair
- If not found, generates a new key pair
- Generates a server TLS key pair using the DNS names specified. Note: in docker, it is best to give each server instance it's own key file name and DNS name.
- Releases the directory lock
Note
The lock procedure is done to ensure only 1 set of keys is generated so that all servers will share the same self-signed key root.
When a second server starts and obtains a lock, it will use the CA key pair generated by the first server to generate its own server key pair.
The intent of this procedure to use TLS whenever possible and to make demonstrations and development easy to set up and configure. For production use, use externally generated keys from appropriate certificate authorities and assign the key files to paths using the appropriate environment variable.
Tip
When installing in a cloud service provider that will be doing TLS termination, set the value of HEXA_TLS_ENABLED
and
HEXA_AUTO_SELFSIGN to false.
The Hexa Administration Server currently supports unauthenticated access only and should be installed in a protected location. It will be upgraded shortly to support Open Identify (OIDC) based authentication.
The Hexa Administration server now makes provisioning calls to Hexa Orchestrator over secured TLS communications using the OAuth2 Client Credentials Grant (RFC6749 Section 4.4). In the docker-compose file, a demonstration configuration is set-up using KeyCloak to authenticate client requests and issue tokens for accessing the Hexa Orchestration Service.
Important
To facilitate easy setup for demonstration, Keycloak is preconfigured with a realm (Hexa_Orchestrator_Realm), and a
client credential. The root
password to Keylcloak and the hexaclient client secret should be changed! See
Keycloak documentation.
| Name | Default | Description |
|---|---|---|
| HEXA_TLS_ENABLED | false | Enable TLS if supported (default: False) |
| HEXA_CERT_DIRECTORY | $HOME/.certs | Directory where PEM files are stored and generated |
| HEXA_CA_KEYFILE | ca-key.pem | Private key PEM file used to generate self-signed TLS certs |
| HEXA_CA_CERT | ca-cert.pem | Certificate Authority Public Key PEM file. Used to validate server certificates |
| HEXA_SERVER_KEY_PATH | server-key.pem | Server private key file used to establish TLS services. |
| HEXA_SERVER_CERT | server-cert.pem | TLS Public certificate file for establishing TLS services |
| HEXA_SERVER_DNS_NAME | Comma separated list of DNS names. Used when auto-generating a server TLS certificate | |
| HEXA_AUTO_SELFSIGN | true | When set to false, server will not attempt to auto generate self-signed certificaes |
| HEXA_CERT_ORG, HEXA_CERT_COUNTRY, HEXA_CERT_PROV, HEXA_CERT_LOCALITY |
Values to be used when generating TLS certificates | |
| HEXA_TOKEN_JWKSURL | When using token based authentication, the URL of the JWKS endpoint | |
| HEXA_JWT_AUTH_ENABLE | false | Enable token based authentication |
| HEXA_JWT_REALM | undefined | The OAuth2 realm - used in error message response to clients to indicate token issuer |
| HEXA_JWT_AUDIENCE | orchestrator | The audience value that should be present in received tokens (used by Orchestrator API) |
| HEXA_JWT_SCOPE | orchestrator | Token 'scope' claim value expected (e.g. orchestrator) |
| HEXA_OAUTH_CLIENT_ID | The OAuth ClientId value used by Admin UI at the OAuth Token Endpoint | |
| HEXA_OAUTH_CLIENT_SECRET | OAuth Client secret used in the client credentials flow | |
| HEXA_OAUTH_CLIENT_SCOPE | If supplied, the scope value to be passed in the Client Credentials Grant request | |
| HEXA_OAUTH_TOKEN_ENDPOINT | The OAUTH2 Token endpoint URL used to execute the client credentials grant. Example: https://keycloak:8080/realms/Hexa-Orchestrator-Realm/protocol/openid-connect/token |
|
| HEXA_OIDC_ENABLED" | false | Enable OIDC Authentication in servers that support a web interface |
| HEXA_OIDC_CLIENT_ID | ${HEXA_OAUTH_CLIENT_SECRET} | OIDC Client Id used when initiating OIDC OP Authorization Flow |
| HEXA_OIDC_CLIENT_SECRET | ${HEXA_OAUTH_CLIENT_SECRET} | Secret associated with OIDC Client Id |
| HEXA_OIDC_PROVIDER_NAME | "OpenID Login" | Login button display test used to indicate where login will occur |
| HEXA_OIDC_PROVIDER_URL | The OIDC Provider URL (well-known endpoint), if missing authentication will be disabled with warning Example: https://keycloak:8080/realms/Hexa-Orchestrator-Realm |
|
| 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. Example: https://admin.hexa.org:8884/redirect |
Fine-grained policy management with OPA.
Using the hexa-admin-ui application available via docker-compose, upload an
OPA integration configuration file. The file describes the location of the IDQL
policy. An example integration configuration file may be found in
deployments/opa-server/example.
Once configured, IDQL policy for the hexa-demo application can be modified on the Applications page. The hexa-admin communicates the changes to the hexa-orchestrator, or "Policy Management Point (PMP)", which then updates the hexa-demo-config bundle server, making the updated policy available to the OPA server.
OPA, the "Policy Decision Point (PDP)", periodically reads config from the hexa-demo-config bundle server and allows or denies access requests based on the IDQL policy. Decision enforcement is handled within the hexa-demo application or "Policy Enforcement Point (PEP)".
The Hexa Demo architecture may be visualized as follows (note: POSTGRES is no longer used by Hexa-Orchestrator and now
uses a JSON based configuration file specified by ORCHESTRATOR_CONFIG_FILE):
Take a look at our product backlog where we maintain a fresh supply of good first issues. In addition to enhancement requests, feel free to post any bugs you may find.
Here are a few additional resources for those interested in contributing to the Hexa project:
This repository also includes documentation for the current demo deployment infrastructure.
The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.