Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Policy Server and Policy Server Proxy installation and configuration

Prerequisites

Hardware requirements

The minimum hardware requirements for the server hosting the marketplace are:

  • number of cores: 1

  • RAM: 2 GB

  • disk: 0.5 GB

Software requirements

Pre-installation steps

Make sure you review the Compatibility Matrix to ensure that the version is compatible with the other components.

Deployment steps

There are two ways to install and run the Policy Server: using Docker Compose or the Docker Engine.

Option 1 - Use Docker Compose to install and run the Policy Server

To install and configure the Policy Server, perform the following steps:

  1. The Policy Server repository is located here.

  1. Change the current directory to docker-compose .

  1. Copy .env.example to .env

  1. Edit the .env file to set environment variables specific to your configuration (please refer to the Environment Variables chapter for how to set them).

  1. Start the Policy Server service

The Policy Server will start in a Docker container and will be accessible via HTTP on port 8001 on the host system.

Option 2 - Use Docker to install and run the Policy Server

To install and configure the marketplace, perform the following steps:

  1. The Policy Server repository is located here.

  1. Copy .env.example to .env

  1. Edit the .env file to set environment variables specific to your configuration (please refer to the Environment Variables chapter for how to set them).

  1. Start the Policy Server service.

The Policy Server will start in a Docker container and will be accessible via HTTP on port 8001 on the host system.

Post installation steps

  • Deploy the policy server behind a reverse proxy responsible for TLS termination and secure request forwarding. The proxy should enforce HTTPS for all external traffic and route decrypted requests to the internal application port.

  • Place the policy server in a network environment that allows outbound communication to the configured OE Node and SSI Verifier.

Environment Variables

Operation Mode

The Policy Server component can run in two modes:

  • as an actual Policy Server: implements the Policy Server functionality, as described here;

  • as a Policy Server Proxy: implements the Policy Server Proxy functionality, as described here.

Note: While both modes can run within the same component, deploying them on separate servers is recommended to clearly isolate front‑end traffic from back‑end traffic.

MODE_PS

Description: Indicates whether Policy Server mode is enabled.

  • Value "1": the Policy Server mode is enabled

  • Value "0": the Policy Server mode is disabled

Values: string ("1" or "0")

Example: "1"

Default Value: N/A

MODE_PROXY

Description: Indicates whether Policy Server Proxy mode is enabled.

  • Value "1": the Policy Server Proxy mode is enabled

  • Value "0": the Policy Server Proxy mode is disabled

Values: string ("1" or "0")

Example: "1"

Default Value: N/A

OE Node

OCEAN_NODE_URL

Description: Sets the base URL of the OE Node used by the policy server. The policy server will receive authorization requests from this OE Node and will send back either an authorization response (allow/deny) or other messages received from the Verifier. Make sure the OE Node has the corresponding POLICY_SERVER_URL variable set to the policy server's URL.

Values: string (URL)

Example: https://ocean-node-vm3.oceanenterprise.io/

Default Value: N/A

SSI Verifier

AUTH_TYPE

Description: Sets the type of authorization used by the policy server. The only possible value now is waltid, meaning that the authorization is based on the walt.id Identity Suite components.

Values: string

Example: waltid

Default Value: waltid

WALTID_VERIFIER_URL

Description: Sets the base URL of the verifier component used by this policy server. For an access request to an asset, the policy server forwards the requested credentials and the verification policies to the verifier component, which initiates a presentation session.

Values: string (URL)

Example: https://verifier2.demo.oceanenterprise.io/

Default Value: N/A

Policy Server Proxy

WALTID_VERIFY_RESPONSE_REDIRECT_URL

Description: Sets the redirect URL for the verify calls performed by the SSI Wallet. The URL must include the base URL of the Policy Server Proxy, followed by /verify/\$id.

Values: string (URL)

Example: https://psproxy1.demo.oceanenterprise.io/verify/\$id/

Default Value: N/A

WALTID_VERIFY_PRESENTATION_DEFINITION_URL

Description: Sets the redirect URL for the presentation definition calls performed by the SSI Wallet. The URL must include the base URL of the Policy Server Proxy, followed by /pd/\$id.

Values: string (URL)

Example: https://psproxy1.demo.oceanenterprise.io/pd/\$id/

Default Value: N/A

Default Verification Policies

The Policy Server can be configured to apply additional static verification policies beyond those provided by the OE Node in a verification request. The verification policies can be applied to the Verifiable Credential presented by the SSI Wallet or to the Verifiable Presentation that embeds the Verifiable Credentials submitted by the SSI Wallet.

The list of static verification policies is available here.

DEFAULT_VC_POLICIES

Description: Sets the default static policies applied to the Verifiable Credentials submitted by the SSI Wallet for verification.

Values: list of strings

Example: "expired","signature","revoked-status-list","not-before"

Default Value: []

DEFAULT_VP_POLICIES

Description: Sets the default static policies applied to the Verifiable Presentation submitted by the SSI Wallet for verification.

Values: list of strings

Example: "expired","signature","revoked-status-list","not-before"

Default Value: []

SSI Verification Response

WALTID_SUCCESS_REDIRECT_URL

Description: Sets the redirect URL to return when all verification policies are passed.

Values: string (URL)

Example: "https://example.com/success?id=$id"

Default Value: ""

WALTID_ERROR_REDIRECT_URL

Description: Sets the redirect URL to return when a verification policy failed.

Values: string (URL)

Example: "https://example.com/error?id=$id"

Default Value: ""

Action Validation based on web3 address

This group of variables configures the policy server to validate certain OE Node actions by checking the Web3 addresses of both the node and the consumer initiating the request.

When configured with a Policy Server, the OE Node calls it to validate certain actions, passing the OE Node's address from which the action request was received and the consumer's address that initiated the request.

The following actions are validated against the lists described in this section: encrypt, decrypt, initiate, download, and startCompute.

POLICY_SERVER_NODE_ACCESS_LIST

Description: Sets the list of OE Nodes web3 addresses from which the action requests are accepted.

The policy server compiles the list of accepted nodes by merging the list in this environment variable and the list retrieved from POLICY_SERVER_NODE_ACCESS_LIST_URL. If the resulting list is null, action validation based on the OE Node's address is disabled. If it's not null, only action requests coming from nodes in this list are accepted.

Values: list of strings (comma separated)

Example: "0x1111,0x2222"

Default Value: null

POLICY_SERVER_NODE_ACCESS_LIST_URL

Description: Sets the URL from where the list of node web3 addresses from which the action requests are accepted is loaded. The web3 addresses listed here must be separated by a new line character (one address per line).

The policy server compiles the list of accepted nodes by merging the list retrieved from this variable and the list defined in POLICY_SERVER_NODE_ACCESS_LIST. If the resulting list is null, action validation based on the OE Node's address is disabled. If it's not null, only action requests coming from nodes in this list are accepted.

Values: string (URL)

Example: https://raw.githubusercontent.com/MBadea17/testdata/refs/heads/main/trustedNodes

Default Value: null

POLICY_SERVER_CONSUMER_ACCESS_LIST

Description: Sets the list of consumer web3 addresses from which the action requests are accepted.

The policy server compiles the list of accepted consumers by merging the list in this environment variable and the list retrieved from POLICY_SERVER_CONSUMER_ACCESS_LIST_URL. If the resulting list is null, action validation based on the consumer's address is disabled. If it's not null, only action requests coming from consumers in this list are accepted.

Values: list of strings (comma separated)

Example: "0x3333,0x4444"

Default Value: null

POLICY_SERVER_CONSUMER_ACCESS_LIST_URL

Description: Sets the URL from where the list of consumers' web3 addresses from which the action requests are accepted is loaded. The web3 addresses listed here must be separated by a new line character (one address per line).

The policy server compiles the list of accepted consumers by merging the list retrieved from this variable and the list defined in POLICY_SERVER_CONSUMER_ACCESS_LIST. If the resulting list is null, action validation based on the consumer's address is disabled. If it's not null, only action requests coming from consumers in this list are accepted.

Values: string (URL)

Example: https://raw.githubusercontent.com/MBadea17/testdata/refs/heads/main/trustedNodes

Default Value: null

Logs

ENABLE_LOGS

Description: Indicates whether the logging is enabled.

  • Value "1": logging is enabled

  • Value "0": logging is disabled

Values: string ("1" or "0")

Example: "1"

Default Value: "0"

TCP Port

PORT

Description: Defines the port on which the application listens inside the container. In the docker-compose.yml file, the host port 8001 is mapped to the default container port (3000). In case you changed the default value, make sure you update the port mapping in the docker-compose.yml file.

Values: number

Example: 3000

Default Value: 3000

API Requests Authentication

POLICY_SERVER_API_KEY

Description: Defines the key used by the Policy Server to authenticate requests. If no value is provided, request authentication is disabled. If a key is provided, use the same key in the POLICY_SERVER_API_KEY variable of the corresponding OE Node.

Values: string

Example: mrgcorhTzA1Ey2WRhZAK8tkw4zBrIgQ757toUz3fXvfHh8Ua

Defaul Value: null (request authentication disabled)

ADMIN_API_KEY

Description: Sets the API key that protects the administrative endpoints of the Policy Server. The caller must set this value in the X-API-KEY header to be authenticated. If the value is null, key authentication is disabled.

The administrative endpoints of the Policy Server are:

  • listAcceptedNodes: list the web3 addresses of the accepted OE Nodes (from POLICY_SERVER_NODE_ACCESS_LIST and POLICY_SERVER_NODE_ACCESS_LIST_URL)

  • listAcceptedConsumers: list the web3 addresses of the accepted consumers (from POLICY_SERVER_CONSUMER_ACCESS_LIST and POLICY_SERVER_CONSUMER_ACCESS_LIST_URL)

  • reloadAcceptedNodes : reload the lists from POLICY_SERVER_NODE_ACCESS_LIST_URL

  • reloadAcceptedConsumers : reload the lists from POLICY_SERVER_CONSUMER_ACCESS_LIST_URL.

Values: string

Example: abcd1234

Default Value: null

HTTPS connection

Set the following environment variables to enable HTTPS connections on the Policy Server.

Note: The Policy Server start commands shown in this guide mount the certs directory from the repository into the container at /etc/ssl/certs/. To enable HTTPS with minimal setup, place your certificate files in this directory and adjust the environment variable to reference the correct certificate file name.

HTTP_CERT_PATH

Description: Sets the location where the TLS certificate of the Policy Server resides. If the value is null, the HTTPS connection is not enabled. Make sure that the referenced file includes both the digital certificate and the intermediate certificate.

Please note that the

Values: string

Example: /etc/ssl/certs/cert.pem

Default Value: null

HTTP_KEY_PATH

Description: Sets the location where the private key file of the TLS certificate resides. If the value is null, the HTTPS connection is not enabled.

Values: string

Example: /etc/ssl/certs/key.pem

Default Value: null

PreviousSSI Stack installation and configuration

Last updated