Installing PlainID’s Policy Authorization Agent (PAA) on your local machine is essential for testing and development environments. This comprehensive guide will walk you through the entire process of setting up PAA locally using Docker Desktop, Kubernetes, Minikube, and Helm, while creating custom YAML configurations instead of relying on the default PlainID values.yaml file.

The Policy Authorization Agent serves as a critical component in PlainID’s identity and access management ecosystem, enabling secure policy enforcement in distributed environments. By installing PAA locally, developers and administrators can test policies, troubleshoot configurations, and validate integrations before deploying to production environments.

Before beginning the PlainID PAA installation process, ensure your local machine meets all the necessary requirements. These prerequisites are fundamental for a successful deployment and smooth operation of your local testing environment.

Your system must have the following components installed and configured:

1. Docker Desktop – Container platform for running PAA components
2. Kubernetes – Container orchestration system
3. Minikube – Local Kubernetes cluster for development
4. Helm – Kubernetes package manager for PAA deployment
5. PlainID Tenant – Active tenant with PAA creation permissions
6. Docker Account – Account with access to PlainID repositories

These tools work together to create a robust local testing environment where you can deploy and test your PlainID PAA configurations safely.

Docker Desktop forms the foundation of your local PAA installation. Navigate to the official Docker website and download the latest version of Docker Desktop compatible with your operating system. Docker Desktop provides the containerization platform necessary for running PAA components in isolated environments.

After installation, ensure Docker Desktop is running and properly configured. You can verify the installation by opening a command prompt and running docker –version. This command should return the installed Docker version, confirming successful installation.

Docker Desktop will serve as the runtime environment for your Minikube cluster and all PAA-related containers, making it an essential component for local testing scenarios.

The next crucial step involves installing the Kubernetes ecosystem tools required for PAA deployment. These tools include Kubernetes CLI (kubectl), Minikube for local cluster management, and Helm for package management.

Installing Chocolatey Package Manager

First, install Chocolatey, a powerful package manager for Windows that will streamline the installation of our required tools. Open PowerShell with Administrator privileges by searching for “PowerShell” in your Start menu and selecting “Run as administrator.”

Execute the following command to install Chocolatey:

Set-ExecutionPolicy Bypass -Scope Process -Force

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072

Invoke-Expression ((New-Object System.Net.WebClient).DownloadString(‘https://community.chocolatey.org/install.ps1’))

This command temporarily bypasses execution policies, sets secure protocols, and downloads the Chocolatey installation script. The installation process will configure Chocolatey on your system, enabling easy package management for subsequent installations.

Verifying Chocolatey Installation

After installation completes, verify Chocolatey is working correctly:

choco –version

This command should display the installed Chocolatey version, confirming successful installation.

Installing Helm for PAA Package Management

With Chocolatey installed, proceed to install Helm, which will manage your PAA deployment:

choco install kubernetes-helm

Helm serves as the package manager for Kubernetes, allowing you to deploy complex applications like PAA using pre-configured charts. The installation includes kubectl (Kubernetes CLI) automatically, providing command-line access to your Kubernetes cluster.

Installing Minikube for Local Kubernetes Cluster

Install Minikube to create a local Kubernetes cluster for PAA testing:

choco install minikube -y

The -y flag automatically confirms the installation, streamlining the process. Minikube creates a single-node Kubernetes cluster on your local machine, perfect for development and testing scenarios.

Verifying All Installations

Confirm each tool installed successfully by checking their versions:

kubectl version –client

helm version

minikube version

Each command should return version information, confirming proper installation and configuration.

Creating a Policy Authorization Agent within your PlainID tenant is essential before proceeding with local installation. The PAA serves as the bridge between your local environment and PlainID’s cloud services, enabling secure policy enforcement and communication.

Tenant-Level PAA Creation

For organization-wide PAA deployment, navigate to your PlainID tenant settings. Access the Policy Authorization Agents tab within tenant settings, where you can create a new PAA instance. This approach creates a PAA that can be used across all environments within your tenant.

The tenant-level PAA provides broader scope and can be utilized by multiple environments, making it ideal for organizations with multiple development, staging, and production environments.

Environment-Specific PAA Creation

Alternatively, create environment-specific PAAs for more granular control. Navigate to your desired environment within the PlainID console, access Environment Settings, and locate the PAA tab. This approach creates PAAs dedicated to specific environments, providing better isolation and security.

Environment-specific PAAs offer enhanced security by limiting scope and ensuring each environment maintains its own authentication credentials and configuration parameters.

After creating your PAA, download the corresponding Helm chart that contains all necessary deployment configurations. Navigate to your newly created PAA within the PlainID console and locate the download option in the dropdown menu.

The Helm chart contains pre-configured templates, default values, and deployment specifications tailored for your specific PAA instance. Download the chart file and extract it to a dedicated folder on your local machine.

Open PowerShell and navigate to the extracted folder directory. This directory will serve as your working location for all subsequent PAA deployment commands and configuration modifications.

Before proceeding with PAA deployment, collect four critical values required for authentication and communication with PlainID services. These values establish secure connections between your local PAA instance and PlainID’s cloud infrastructure.

Required Configuration Values

You need the following four essential values:

1. PAA ID – Unique identifier for your PAA instance
2. Tenant ID – Your PlainID tenant identifier
3. Agent Secret Key – Authentication secret for secure communication
4. PlainID Hybrid URL – Regional connection endpoint

Locating PAA ID

The PAA ID is available where you created the PAA instance. Click on your created PAA within the PlainID console, and the PAA ID will be displayed in the popup window. Copy this value and save it securely for use in your configuration files.

Finding Tenant ID

Access your global tenant settings within the PlainID console. Navigate to Settings and locate the Hybrid Agent Keys section. Your Tenant ID is prominently displayed in this section. Copy this value for your configuration.

Obtaining Agent Secret Key

The Agent Secret Key is also located in the Hybrid Agent Keys section. Click the Edit button in the top-right corner of this section, then click Regenerate Value to create a new secret key.

Important: Copy the regenerated value immediately and click Save at the bottom of the page. Store this key securely, as regenerating it again may disrupt existing deployments. The Agent Secret Key can be reused across multiple deployments.

Determining PlainID Hybrid URL

Examine your current PlainID console URL to identify your regional deployment. Note the region code (us1, eu1, ca1, etc.) from your URL. This region code is crucial for constructing the correct hybrid connection URL for your PAA configuration.

Save all four values in a secure file for reference during the configuration process.

Docker authentication is required to access PlainID’s private container repositories. This step ensures your local environment can pull the necessary PAA container images during deployment.

Execute the following command in your PowerShell window:

docker login -u {YOUR_DOCKER_USERNAME}

Replace {YOUR_DOCKER_USERNAME} with your actual Docker Hub username.

The system will prompt for your Docker password. Enter your password, and you should see “Login Succeeded” confirmation. This authentication grants access to PlainID’s container repositories, enabling your local deployment to pull required images.

Initialize your local Kubernetes cluster using Minikube. In your PowerShell window (still navigated to the PAA Helm chart directory), execute:

minikube start

This command creates and starts a local Kubernetes cluster within Docker Desktop. The process may take several minutes as Minikube downloads necessary images and configures the cluster environment. Monitor the output for successful completion messages.

Once started, your Minikube cluster appears as a container in Docker Desktop, providing a local Kubernetes environment for PAA testing and development.

Instead of modifying PlainID’s default values.yaml file, create a custom configuration file with your specific settings. This approach maintains clean separation between default configurations and your customizations.

Execute the following PowerShell command to create your custom configuration file:

@”

# PlainID PAA Configuration

tenantId: “{ENTER_YOUR_TENANT_ID}”

agentSecretKey: “{ENTER_YOUR_AGENT_SECRET_KEY}”

paaId: “{ENTER_YOUR_PAA_ID}”

remoteApi: “wss://remote.{SPECIFY_REGION_HERE}.plainid.io/wstunnel”

# Docker registry authentication

imagePullSecrets:

– name: {ENTER_IMAGE_PULL_SECRET_NAME}

# Basic resource limits

resources:

limits:

cpu: 500m

memory: 512Mi

requests:

cpu: 250m

memory: 256Mi

# Redis configuration

redis:

enabled: true

auth:

enabled: false

master:

persistence:

enabled: false

resources:

limits:

cpu: 250m

memory: 256Mi

requests:

cpu: 100m

memory: 128Mi

redis-ha:

enabled: false

replicaCount: 1

“@ | Out-File -FilePath “values-final.yaml” -Encoding UTF8

Configuration Parameter Guidance

{ENTER_YOUR_TENANT_ID}: Enter the Tenant ID copied from Step 5 {ENTER_YOUR_AGENT_SECRET_KEY}: Enter the Agent Secret Key from Step 5 {ENTER_YOUR_PAA_ID}: Enter the PAA ID from Step 5 {SPECIFY_REGION_HERE}: Enter your region code (us1, eu1, ca1, etc.) {ENTER_IMAGE_PULL_SECRET_NAME}: Choose a descriptive name (e.g., “plainid-registry-secret”)

Important Notes:

• Remove curly braces {} when entering actual values
• Keep all values within double quotes “”
• Remember the image pull secret name for Step 10
• The file is named “values-final.yaml” – adjust subsequent commands if using a different name

This configuration file defines resource limits, Redis settings, and authentication parameters optimized for local testing environments.

Kubernetes namespaces provide logical separation and organization for your PAA deployment. Create a dedicated namespace for your PAA resources:

kubectl create namespace {ENTER_NAMESPACE_NAME}

{ENTER_NAMESPACE_NAME}: Choose a descriptive namespace name (e.g., “plainid-paa”, “paa-testing”)

Remember your chosen namespace name, as it will be used in all subsequent deployment commands. Namespaces help organize resources and provide scope isolation for your PAA deployment.

Kubernetes requires authentication credentials to pull images from private Docker repositories. Create a Docker registry secret within your namespace:

kubectl create secret docker-registry {ENTER_IMAGE_PULL_SECRET_NAME} `

–docker-server=https://index.docker.io/v1/ `

–docker-username={DOCKER_USERNAME} `

–docker-password={DOCKER_PASSWORD} `

–docker-email={DOCKER_EMAIL} `

–namespace={NAMESPACE_NAME}

Parameter Guidance

{ENTER_IMAGE_PULL_SECRET_NAME}: Use the same name specified in Step 8 {DOCKER_USERNAME}: Your Docker Hub username {DOCKER_PASSWORD}: Your Docker Hub password {DOCKER_EMAIL}: Email associated with your Docker account {NAMESPACE_NAME}: The namespace created in Step 9

Copy and paste the entire command with your values into PowerShell. This secret enables Kubernetes to authenticate with Docker Hub and pull PlainID’s PAA container images.

Deploy your PAA using Helm with your custom configuration file:

helm install plainid-paa . `

–namespace {ENTER_NAMESPACE} `

–values values-final.yaml

{ENTER_NAMESPACE}: Your namespace from Step 9

This command installs the PAA Helm chart using your custom configuration. The installation process creates all necessary Kubernetes resources, including deployments, services, and configuration maps.

Updating PAA Configuration

If you need to modify your configuration after deployment, edit the “values-final.yaml” file and run:

helm upgrade plainid-paa . `

–namespace {ENTER_NAMESPACE} `

–values values-final.yaml

This command updates your existing deployment with new configuration values without requiring complete reinstallation.

Monitor your PAA deployment progress by watching pod creation and status:

kubectl get pods -n {YOUR_NAMESPACE} –watch

{YOUR_NAMESPACE}: Your namespace from Step 9

This command displays real-time updates of pod status. Initially, you’ll see “ContainerCreating” status as Kubernetes pulls images and initializes containers. Allow several minutes for the process to complete.

Successful deployment shows all pods with “Running” status and “1/1” ready state. At this point, your PAA local installation is complete and ready for testing.

When encountering deployment issues, use these diagnostic commands to identify and resolve problems:

Checking Pod Status and Events

kubectl describe pod {POD_NAME} -n {NAMESPACE}

{POD_NAME}: Copy the exact pod name from kubectl get pods output {NAMESPACE}: Your deployment namespace

This command provides detailed information about pod status, events, and error messages.

Viewing Pod Logs

kubectl logs {POD_NAME} -n {NAMESPACE}

Use this command when pods are running but experiencing issues. Logs provide application-level error messages and debugging information.

Restarting Individual Pods

kubectl delete pod {POD_NAME} -n {NAMESPACE}

Deleting a pod triggers automatic recreation, effectively restarting the pod. This resolves many transient issues and applies configuration changes.

ImagePullBackOff Errors: Usually indicate authentication issues with Docker registry. Verify your Docker registry secret configuration and ensure your Docker account has access to PlainID repositories.

Pod Status 0/1: Indicates containers failing to start. Check pod logs and descriptions for specific error messages.

Connection Issues: Verify your PlainID hybrid URL, region settings, and network connectivity to PlainID services.

Best Practices for PAA Local Testing

To maximize the effectiveness of your local PAA installation, follow these best practices:

Resource Management

Monitor resource usage in Docker Desktop to ensure adequate CPU and memory allocation for your PAA deployment. Adjust resource limits in your values-final.yaml file based on your testing requirements.

Configuration Management

Maintain separate configuration files for different testing scenarios. Create multiple YAML files for various test environments, policy configurations, or deployment scenarios.

Security Considerations

Store authentication credentials securely and avoid committing secrets to version control systems. Use environment variables or secure storage solutions for sensitive configuration data.

Regular Updates

Keep your local environment updated with the latest PAA versions, Docker images, and Kubernetes tools to ensure compatibility and access to new features.

Congratulations on successfully installing PlainID PAA on your local machine! Your local testing environment is now ready for policy development, integration testing, and troubleshooting scenarios. This setup provides a safe, isolated environment where you can experiment with PlainID configurations without affecting production systems.

Your local PAA installation enables comprehensive testing of authentication policies, access control rules, and integration scenarios. Use this environment to validate configurations before deploying to staging or production environments, ensuring smooth and reliable policy enforcement across your organization.

Remember to regularly update your local environment and monitor resource usage to maintain optimal performance for your PAA testing activities.

In this guide, you’ll learn how to integrate Okta as an external identity provider (IdP) for PlainID, enabling seamless Single Sign-On (SSO) for your applications via OIDC (OpenID Connect). We’ll start from scratch, including creating an Okta developer account, setting up apps, configuring PlainID tenant settings, resolving common errors, and managing users, with detailed steps and explanations. 

Before we start, ensure you have: 

• A valid PlainID tenant (e.g., <company>.us1.plainid.io) 

• A PlainID admin account  

• Basic familiarity with SSO/IdP concepts helps, but is not required, this guide explains it all. 

Visit https://developer.okta.com/signup/ to create an account. 

You’ll be presented with three account types: 

Choose the Developer Account. This version is free and allows us to test OIDC integrations like we’ll do with PlainID. 

1. Go to Applications → Create App Integration 

2.  Select:

• Sign-in method: OIDC – OpenID Connect

• Application type: Web Application

• Click “Next”

3.  Set Web App Integration Settings: 

• App Name: PlainID SSO (Or any name you deem appropriate) 

• Grant type: Check Authorization Code 

• Sign-in redirect URI: Leave this blank for now. 

• Sign-out redirect URI: Leave blank for now. 

• Click Save to Generate 

After saving your app: 

• Scroll to the Login section under your app’s General settings 

• Click Edit 

Copy the Sign-in Redirect URI from your PlainID tenant (Read warning before this implementation): 

• Login to PlainID 

• Click the gear icon on the top-right > Settings 

• Go to Tenant IDP Settings 

• Set IDP Source to External IdP 

⚠️ Important Warning: 

If you switch to External IDP without a working redirect URI or admin access recovery plan, you may get locked out permanently. Always test with a second “backdoor” admin account configured for internal login before switching. 

Paste this in the Sign-in Redirect URI in Okta.

• Set Login initiated by to: App only 

Why This Is Important: 

When users log out of PlainID, the logout request is sent to Okta. Okta needs to know where to redirect users after logging out. If this isn’t configured correctly, users will get stuck with a 400 error like: 

Error: The ‘post_logout_redirect_uri’ parameter must be a Logout redirect URI in the client app settings 

How to Fix It: 

1. Go to your Okta developer portal 
2. Navigate to your application (e.g., “PlainID SSO”) 
3. Click the General tab 
4. Scroll down to the Login section 
5. Click Edit 
6. In the Sign-out redirect URIs, add the following: 

https://auth.us1.plainid.io/auth/realms/<PlainID-Company-Name>/broker/tenant_idp/endpoint/logout_response 

(Replace <PlainID-Company-Name> with your actual PlainID Company Name. The company name will be present in your PlainID url, e.g., https://trustaxisinc.us1.plainid.io, here “trustaxisinc” is the company name) 

7.  Save the changes 

8. Confirm Logout Is Working 

After doing this: 

• When users log out of PlainID, they will be securely redirected through Okta and returned cleanly without a 400 error. 

What Is It? 

Federation Broker Mode allows Okta to automatically assign users to apps based on their identity from external identity providers, but in this flow, you’re not assigning users explicitly because PlainID controls access. 

Problem: 

If Federation Broker Mode is enabled and you don’t assign users directly to the Okta app, users will get: 

You are not allowed to access this app. To request access, contact an admin. 

Fix: 

1. Go to Okta → Applications 
2. Open the PlainID SSO app 
3. Scroll to the bottom 
4. Click the Edit button (top-right of the section) 
5. Disable Federation Broker Mode 

This ensures Okta properly respects your OIDC flow via the PlainID side. 

After doing so, you can go to Assignments Tab in Application settings and add users to the app manually. 

Log into PlainID → Go to Tenant Settings → General Details & IDP Application Settings 

1. Scroll to the section titled General Details 
2. Find the field labeled Metadata URL 

In Okta, your Metadata URL is: 

https://<your-domain>/oauth2/default/.well-known/openid-configuration
 

(Replace <your-domain> with your actual Okta tenant domain, e.g., dev-66666666.okta.com) 

3.  Paste this Metadata URL into the field in PlainID 

4.  Click the Import button next to it 

What Happens After Clicking “Import” 

PlainID will automatically fetch and populate the following fields using the Metadata URL: 

• Authorization URL 
• Token URL 
• Logout URL 
• JWKS URL 
• Issuer 

This avoids manual entry errors and ensures consistency with your Okta configuration. 

Also Complete the Following: 

This claim determines which users are granted admin access in PlainID. 

Go to your Okta Security → API → Authorization Servers → default → Claims: 

1. Click Add Claim 
2. Name: admin 
3. Value type: Expression 
4. Value: true 
5. Token type: ID Token 
6. Scope: Any 
7. Include in token: Always 

Go to your Okta Security → API → default → Access Policies

• Name: Any
• Description: Any
• Assign to : All Clients
• And finally, add Rule

❌ Error: “400 Bad Request – Policy Evaluation Failed” 

Fix: Ensure the correct Authentication Policy is attached to the app, and it allows federated IdP access. 

❌ Error: “You are not allowed to access this app” 

Fix: You are likely not assigned to the application in Okta. Go to: 

• User Profile → Applications → Assign Applications → select your app 

Note: If Federation Broker Mode is enabled, direct assignment might not be needed, but you still need proper token claims. 

❌ Error: “Post_logout_redirect_uri must be in app settings” 

Fix: Go to the Okta app → General Settings and add the PlainID logout URL (or home URL) to Sign-out redirect URIs. 

Examples: 

• https://auth.us1.plainid.io/auth/realms/<PlainID-Company-Name>/broker/tenant_idp/endpoint/logout_response 

Visit: 

https://<company>.us1.plainid.io 

This should redirect you to Okta, authenticate you, and return you to PlainID logged in. 

For logout, ensure the logout flow uses the same Okta URLs you’ve added to the sign-out redirect URIs.

1. Go to Directory → People → Add Person 
2. Enter user details and ensure: 

• The user has the claim admin=true if you want them to access PlainID admin 
• The user can authenticate using configured method (password or MFA) 

Users will log in using the same flow, redirect from PlainID to Okta. 

By following this guide, you’ve fully integrated Okta as an external IdP for PlainID using OIDC. This guide solves login and logout errors, explains how to assign users and access rights, and ensures you’re ready for production-level federation. 

This setup is perfect for enterprises moving towards policy-based access control (PBAC), with centralized identity and access governance. 

Keywords:

PlainID Okta Integration, Okta as External IdP, SSO Federation Setup, OpenID Connect PlainID, Okta Identity Provider Guide