Run Local Authorization Microservice

Run the authorization microservice, the policy decision point (PDP), as a container next to your application. This guide explains why you would run it locally, then walks through running, configuring, and monitoring it.

Why Run Authorization Locally?

A local Policy Decision Point (PDP) changes where decisions happen: inside your infrastructure instead of in Permit's cloud.

1. Performance

The PDP evaluates every decision locally, next to your application, so checks never make a network round trip to the Permit cloud. Run it as a sidecar on the same host and the check goes over the loopback interface, so there is no network latency at all: the request never reaches a network.

A well-configured local PDP answers thousands of checks per second with sub-millisecond latency, and under 10ms at p95 end to end from your application. Some customers serve millions of decisions a day from a single PDP instance. Your own figures depend on policy complexity, the amount of data the PDP holds, and the host it runs on.

2. Security and data residency

The data your policies evaluate can stay in your infrastructure, which helps you meet data residency requirements. You control where the PDP runs and who can reach it.

3. Reliability

Checks are answered by the PDP in your network, so decisions don't depend on Permit's availability. You run and scale the PDP like any other service in your infrastructure.

4. Full policy support

A local PDP supports every policy model: RBAC, ABAC, and ReBAC. OPAL pushes policy changes to it as you make them.

Running the Authorization Microservice

1

Pull the Docker Container

Pull the latest PDP container from Docker Hub:

docker pull permitio/pdp-v2:latest

note

If you haven't installed Docker yet, get it here.

2

Run the Container

Launch the PDP container with your API key:

docker run -it -p 7766:7000 \
  --env PDP_DEBUG=True \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  permitio/pdp-v2:latest

The PDP now listens on localhost:7766 for authorization requests.

tip

Check that the container is running:

docker ps
docker logs <container_id>

3

Advanced Configuration Options

Debug Mode

Enable detailed logging for troubleshooting:

docker run -it -p 7766:7000 \
  --env PDP_DEBUG=True \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_OPA_DECISION_LOG_CONSOLE=True \
  permitio/pdp-v2:latest

With these settings, the PDP:

Logs decisions to the console: every authorization decision and its outcome (PDP_OPA_DECISION_LOG_CONSOLE).

Logs in debug detail: more detail about errors and about how policies are evaluated (PDP_DEBUG).

Custom Port Configuration

Map the PDP ports to match your infrastructure:

docker run -it -p 7766:7000 -p 8181:8181 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  permitio/pdp-v2:latest

The container exposes two ports:

• 7766: The main PDP API port
• 8181: The OPA API port for direct policy queries

tip

You can interact directly with the OPA API on port 8181 for advanced policy queries and debugging.

Decision Log Settings

Tune decision logging:

docker run -it -p 7766:7000 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_OPA_DECISION_LOG_ENABLED=True \
  --env PDP_OPA_DECISION_LOG_MIN_DELAY=1 \
  permitio/pdp-v2:latest

Monitoring and Debugging

1

Health Checks

Monitor your PDP's health status through the health endpoint:

http://localhost:7766/health

Use it for container liveness and readiness checks.

2

Metrics

Read metrics from the metrics endpoint:

http://localhost:7766/metrics

Scrape it with your monitoring stack to track request latency, decision counts, and errors. See Monitoring PDPs.

3

API Documentation

View the complete PDP API documentation through the ReDoc interface:

http://localhost:7766/redoc

It lists every endpoint with its request and response format.

What did you learn?

In this walkthrough, you learned how to:

• Set up and run a local authorization microservice
• Configure PDP options for your needs
• Monitor and debug your authorization layer
• Access detailed metrics and health information

What's next? 🎉

• Create user and resource attributes
• Define your first User and Resource Sets
• Create your ABAC policy rules

Great job! You're now running local authorization.