hexa-org/policy-orchestrator

Hexa Policy Orchestrator enables you to manage all of your access policies consistently across software providers.

Table of Contents

• Hexa Policy Orchestrator
  • Getting Started
    • Build the Hexa image
    • Run the Policy Orchestrator
  • Application descriptions
    • Example workflow
  • Getting involved

Hexa Policy Orchestrator

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.

Getting Started

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 git@github.com:hexa-org/policy-orchestrator.git

Prerequisites

Install the following dependencies.

• Go 1.22 - Needed to compile and install
• Docker Desktop - Needed to run docker-compose configuration

Task: Build the Hexa Orchestrator image

Build the Hexa Orchestrator Docker containers...

cd demo
sh ./build.sh

Task: Run the Policy Orchestrator

These 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.yml

When 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 up

Application Descriptions

Docker 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-orchestrator to 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-agent server retrieves policies from the hexa-opaBundle-server instance 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 http://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: alice@hexaindustries.io, bob@hexaindustries.io, carol@hexaindustries.io, and gerry@hexaindustries.io
    • 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.

Configuration

TLS Support

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:

1. Locks the directory to avoid conflict with other server instances
2. Look for an existing CA key pair
3. If not found, generates a new key pair
4. 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.
5. 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.

OAuth2 Support

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.

Environment Variables

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: http://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: http://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: http://admin.hexa.org:8884/redirect

Example Workflow

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):

Getting involved

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.

• Backlog

Here are a few additional resources for those interested in contributing to the Hexa project:

• Contributing
• Code of Conduct
• Development
• Security

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.