hexa-org / policy-mapper

Policy Mapper defines packages for use in mapping of Identity Policy between Hexa IDQL and other formats.

Hexa Policy Mapper Project

The Hexa Policy-Mapper Project provides administrative tools and development libraries for provisioning and mapping various policy systems into a common policy format known as IDQL. With Policy Mapper and IDQL, you can manage all your access policies consistently across software providers and cloud systems. The project includes a number of prebuilt integrations (we call them providers) as well as guidance on how to build your own providers.

This project provides:

• a GoLang SDK which can be used in open source and commercial implementations to leverage this community library.
• a Hexa CLI command line tool which can be used to provision policies to web accessible policy systems.
• a GoLang interface (policyprovider.Provider) enabling the development of new policy provisioning providers.

Tip

Policy-Orchestrator is available as a sample web server implementation that uses Policy-Mapper.

Note

This project is currently under initial development and documentation may be out of date.

Supported Provider Integrations

Policy Mapper supports the following capabilities:

Syntactical Mapping : Policy formats that have a parsable format or language, and can be represented in a "tuple" (subject, action, resource, conditions, scope) are considered "syntactical". Policy-Mapper can map these formats to and from IDQL JSON format. Examples include: IDQL, Cedar, GCP Bind among others.

RBAC API Mapping : Some systems do not directly have a policy language but support role or group based access control settings through an API.

Policy Provisioning : Policy Mapper combines a set of Providers that call APIs to retrieve and map access policy as well as be able to set policy.

Syntactical Mapping support is provided for:

• Google Bind Policy and Google Conditional Expression Language (CEL)
• AWS Verified Permissions and Cedar policy language including support for CEL

Provisioning support is provided for:

• Google Policy for IAP Secured Resources (Application Engine and Compute Engine)
• Amazon Verified Permissions
• OPA Open Policy Agent with Extensions to Support IDQL and an OPA Extension Plugin to support ABAC policy (conditions) processing
• Provisioning to RBAC based policy systems including (to be ported from hexa-org/policy-orchestrator):
  • Amazon
    • Cognito RBAC
    • API Gateway
  • Microsoft Azure

Getting Started

Installation

Install go 1.21, clone and build the project as follows:

git clone https://github.com/hexa-org/policy-mapper.git

cd policy-mapper

sh ./build.sh

Hexa CLI Tool

To test the Hexa SDK and or develop using scripts, use the Hexa CLI tool.

To run the Hexa CLI, simply type hexa at the command line once installed.

Note

Hexa CLI currently does not support filenames with spaces. Valid example: add gcp --file=my_key.json

Hexa Developer Documentation

To start using the Hexa Mapper SDK in your GoLang project, perform the following get command:

go get github.com/hexa-org/policy-mapper

For more details on how to map or provision policy in either console (shell) form or GoLang, see: Developer documentation.

Provider Documentation

Each provider in the providers directory structure has its own README.md that describes the provider and its capabilities and limitations.

Provider	Folder	Description	Type	Support
AWS AVP	providers/aws/avpProvider	Mapping to/from Cedar Policy language with Get/Set/Reconcile using AVP API	Syntactic Map	SDK,Console
AWS API Gateway	providers/aws/awsapigwProvider	Support for the Amazon API Gateway (experimental)	RBAC	SDK,Console
AWS Cognito	providers/aws/cognitoProvider	Virtual policy support using Cognito Userpools and Groups	RBAC	SDK,Console
Azure Provider	providers/azure/azureProvider	Support for Azure Application Role Policy	RBAC	SDK,Console
Google Cloud IAP Provider	providers/googlecloud/iapProvider	Mapping to/from Google Bind policy and IAP support for Google App Engine and GKE	Syntactic Map	SDK,Console
Open Policy Agent	providers/openpolicyagent	Integrates with Hexa Policy-OPA and interprets IDQL directly with conditions clause support	IDQL Interpreter	SDK,Console

policy-mapper's Issues

Enhance Cedar mapper to support when true

For some reason, the default policy generated by AVP often includes a when { true }; clause

permit(
  principal,
  action in [hexa_avp::Action::"ReadAccount",hexa_avp::Action::"Transfer",hexa_avp::Action::"Deposit",hexa_avp::Action::"Withdrawl"],
  resource
) when {
  true
};

The above when clause should be converted or just ignored.

When adding an OPA server, auto-adjust URL to bundle url

The Hexa cli currently expects the full bundle url. If just a host is provided, simply add it for the user.

Add Readme.md for /sdk

Fix inconsistency around actionUri vs. action_uri vs ActionUri (fix case in all attributes)

Discovered there were some migration issues between old and new policy formats.

Json attributes should all be lower initial case

OPA HTTP Client - Get Policy Not Using a Path

When using the Hexa CLI and using the OPA HTTP provider. The client actually tries to get policy from the Server URL root rather than <server-rood>/bundles/bundle.tar.gz

Research using a policy template for systems that are role or group based and don't have a policy structure

Fix issue with Kong type=existingfile being blank on second use

For some reason when kong type=existingfile is used, the value is kept blank after the first use (good or bad).

Remove use of existingfile for now.

Add Readme.md for examples/sdkExample

Adding documentation for the SDK example

Add OIDC Support Package for Policy-Mapper and Policy-Orchestrator

This enables web interface servers to establish user logins with OIDC.

Anticipated use by:

• Hexa Industries Demo
• Hexa Admin UI

Enhance Cedar Mapper to parse Policy Template

Currently generates an error when parsing:

permit(
    principal == ?principal,
    action in [hexa_avp::Action::"ReadAccount"],
    resource == ?resource
);

? is unexpected

Make OPA PAP information more readable

Currently we are just returning the encoded info. Return the decoded server URL to make it easier to tell which PAP goes where. :)

Update OPA Provider to assign Meta.PolicyId value if not assigned.

Current Policy-OPA project is using a version of IDQL that has Policy.ID. This has been moved to meta.policyId.

Because of the way the OPA Rego interpreter works, each IDQL policy installed needs to have an identifier.

See: Policy-OPA Issue#2.

Add Readme.md for examples/cel

Add Readme.md for providers/aws/awscognito

Adding documentation for the AWS Cognito provider

Add Sesison Support Package for Policy-Opa and Orchestrator

Move shared support pkgs from opa and orchestrator to mapper

Many of the support pkgs have similar code across all 3 packages and have become divergent.

This task moves shared packages to policy-mapper to avoid divergence.

Update documentation for GCP provider

OPA Provider - Token Based Authorization for HTTP Bundle Server

Add support for using authorization header values in addition to mutual TLS.

This is needed for AuthZen server.

Finalize Azure testing

OPA Provider MakeHexaBundle is not returning empty manifest and rego files

Appears to be a packaging problem where /resources tree not embedded with go code.

Need to use go:embed

Add Export Integration Function to Hexa CLI

The export function enables an administrator to export an existing integration to a json file that can be used by the web admin of Policy-Orchestrator

In particular Hexa CLI can be used to create itnegration files by doing the following:

hexa add opa http mybundle --cacert=ca-cert.pem --url=https://mybundlerserver:8889/
hexa export mybundle mybundleserver.json

Google IAP Provider Reporting wrong Name() value

Should be returning gcp_iap instead of google_cloud

... needed by policy-orchestrator

Enhance OPA Provider to allow custom http client for certs/tokens

Allow opaProvider to accept a custom http.Client. This allows the use of oauth2 client for token handling.

Migrate DemoConfig to Policy-Mapper

The orchestrator "democonfig" service is an implementation of a bundle server that can be used for testing.

This would be moved over to the "examples" directory of policy-mapper to let evaluators set up and run a bundle server and OPA server.

GCP IAP Provider - Make Resource_ID a URN rather than a raw identifier

Provide a little more context as to the type of resource. E.g. iap_proxy:backend:xyz

Switch to Cedar Parser

Currently Cedar where clause expression parsing is using Google CEL (because they are almost the same). In the dependencies update, the CEL parser is now failing to parse Cedar where clauses (see Hexa cli test suite).

Now that Cedar is published, it is time to switch to the Cedar libraries

SDK: Complete Provider Support of WithHttpClient Option

Occasionally for testing purposes and other integration work there is the need to initialize a custom HTTP Client when calling cloud APIs. For example, the custom client can mock the remote server and its responses.

This is currently implemented inside many of Hexa Providers but is not yet exposed through the SDK interface.

Add Client Authentication to OPA HTTP Integration

At present bundle updates via HTTP can only be done anonymously.

OPA Provider - Support for OAuth2 Client Credential flow for access to HTTP Bundle Servers

Currently the OPA HTTP Provider accepts a fixed authorization which can be a token for authorization with the HexaBundleServer.

The Policy-OPA AuthZen Server takes a certificate PEM to validate tokens provided.

This functionality would allow the provider client to authenticate to an OAuth2 server using the client credentials flow to receive a rotating token for access.

Note: #47 will allow this to be done outside the provider because an http.Client could be configured in the provider which handles token use and refreshing automatically. This enhancement means that each integration can have it's own client credential and OAuth2 server making it possible to connect to multiple provisioning domains while at the same time simplifying configuration inside of Policy-Orchestrator and Hexa CLI

Add Readme.md for providers/azure/azuretestsupport

Adding documentation for Azure test harness

Create guide for "How to write IDQL policies"

Add Readme.md for providers/azure/azad

Adding documentation for the Azure AD provider

Update OPA Provider to Conform with Current IDQL

Current OPA provider is downgrading to an old version of IDQL. Should be end-to-end IDQL 0.6

Add Support for IDQL Scopes

This adds support for Scopes which are obligations returned to a PEP. For example a SQL Filter, or IDQL Filter, or a set of attributes or columns allowed to be returned.

Use cases:

• SQL Servers (filters expressed as WHERE clauses)
• SCIM (use IDQL Filter expressions)
• LDAP (can convert IDQL filter to LDAP filter)

OPA Provider HTTP Bundle Has Wrong Structure

The OPA Provider Get Policies function is expecting OPA Bundle server to respond with a file structure of
/bundle/

Instead the current testBundleServer is returning
/default/bundle/

This causes an unexpected file not found error

Remove ProjectId from OpaProvider

Unlike projectid in AWS providers or GCP provider, projectid is never actually used. Instead the platform project is wrapped up in the bundle url and the access token.

This is important to simplify and avoid confusion.

Finalize Cognito testing

install Canary Bank on GCP

Add Readme.md for providers/azure/azurecommon

Adding documentation for the Azure common provider information

Publish hexaOpa image to docker hub

This is to publish hexaOpa image so that IDQL enhanced OPA can be easily deployed with docker-compose and on cloud platforms.

Fix Slice error in Options

When no credential is required (and thus not supplied), the hexa cli will panic building WithHttpOptions

Add Readme.md for examples/opa-server

Make sure there is a readme in every major directory

Finalize GCP testing

Finalize OPA Integration

Finalize OPA and integrate with Hexa console

Add Readme.md for /models

Adding documentation for the main models directory

Fix random test failures in hexa_policy_test.go

Issues with using pass by reference was causing occasional failures.

A for loop in hexa_policy was not resetting the reference but allowed random passes. By forcing direct use of objects, the reference problem is blocked.

Breaking change:
PolicyDif struct -> PolicyExist attribute is no longer passed by reference.

Add Readme.md for providers/aws/awscommon

Adding documentation for the AWS common provider info

Add Readme.md for providers/azure/azarm