Installation

PlainID Authorization Agent - Standalone Deployment

Prerequisites

You should start with setting up a user for the installation. We recommend creating a dedicated user, e.g. plainid, this user will be used for the installation and management of the deployment.

1. Create the plainid user and set permissions:

useradd plainid -U
passwd plainid

2. Create the installation folder for the PAA installation (e.g. /opt/plainid):

mkdir /opt/plainid

3. Set up permissions:

sudo visudo

This will open the sudoers configuration file, you need to add the following under the root entry:

plainid ALL=(ALL) NOPASSWD:ALL

4. Save the configuration file, exit, and run the following command:

sudo chown -Rf plainid.plainid /opt/plainid

Installation guide

1. Export the following environment variables:

• Edit the init/aliases file, and add the following lines:

export PLAINID_HOME=PATH # The plainid-paa folder path (or unzip to /opt/plainid)
export JAVA_HOME=localtion of java JDK # (needed if `PLAINID_HOME` path is not /opt/plainid , or you want to use a custom JDK version)
export CLIENT_SECRET_KEY=YOUR_AUTH_SECRET # Agent Secret key (can be found under the Hybrid Agent Keys tab)
export TENANT_ID=YOUR_TENANT_ID # Tenant Id (can be found under the Hybrid Agent Keys tab)
export PAA_ID=YOUR_PAA_ID # Policy Authorization Agent Id (can be found under the Policy Authorization Agents tab)

2. Source the aliases file by using the source command
3. Run start_plainid_paa - to start the application
4. Run pid_status - to check the status of the application

Logs can be found in the /logs folder

Aliases

Default Ports

Runtime SSL Configuration

1. Convert the private key and certificate to a pkcs12 format using the following open SSL command:

openssl pkcs12 -export \
    -in "combined.pem" \
    -inkey "privkey.pem" \
    -out "certtemp.p12" -passout pass:"plainid" \
    -name "plainid"

2. Create a keystore.jks file using keytool from Java JDK:

   $JAVA_HOME/bin/keytool -importkeystore \
    -srckeystore "certtemp.p12" -srcstoretype PKCS12 \
    -srcstorepass "plainid" \
    -destkeystore "keystore.jks" \
    -deststorepass "plainid" \
    -destkeypass "plainid" \
    -alias "plainid"

3. Export environment variable to provide the keystore configuration

export HTTP_SSL_ENABLED=true # to enable ssl over http
export HTTP_SSL_KEYSTORE_PATH="./keystore.jks" # - path to the keystore.jks file
export HTTP_SSL_KEYSTORE_PASSWORD=plainid # keystore password

Exporting Environment Variables

Provide UUID Attribute Type support

export RUNTIME_SUPPORT_UUID_ASSET_ATTRIBUTE=true # to enable support uuid asset attribute
export RUNTIME_SUPPORT_UUID_IDENTITY_ATTRIBUTE=true # to enable support uuid identity attribute

Allow the IP and Time to be included in cache key

export RUNTIME_INCLUDE_IP_HEADER_IN_SCOPE_CACHE_KEY=false # to enable including ip from header in scope cache calculation
export RUNTIME_INCLUDE_REQUEST_TIME_IN_SCOPE_CACHE_KEY=false # to enable including current time in scope cache calculation

Obtaining Private Keys from the Secret Management Service

The secrets-mgmt service is not enabled/deployed by default. Runtime parameters are required to configure to the connection to the secrets-mgmt:

Recommended System Requirements

Consider increasing the available RAM, CPU, and disk space for more demanding use cases (e.g. Caching large amounts of data).

FAQ

• Getting Error -bash: ../plainid/**/bin/**.sh: Permission denied when running plainid_paa_start
  
• Run the command find . -type f -exec chmod 755 {} + inside the plainid folder and try again

Upgrading an Existing Installation to a New Version

Please note the upgrade from v2.x to v5.x is considered a minor upgrade due to a new, time-based versioning scheme

When upgrading to a new minor version (like v2.0.0 -> v5.2309.0) it is done without introducing breaking changes.

Upgrade from 2.X to 5.2309.X

• Stop the currently installed PlainID PAA:
  stop_plainid_paa
• Delete the currently installed PAA directory
• Load the new alias file using source command
• Set the relevant environment variables according to the local environment, Tenant ID, and PAA ID.
  • Make sure to include any additional configurations made prior to the upgrade.
• Run start_plainid_paa to start the new PAA

Upgrading an existing installation to a new major version

When upgrading to a new major version (like v1.2.3 -> v2.0.0) indicates that there is an incompatible breaking change that requires manual actions.

Upgrade from 1.X to 2.X

• Stop the currently installed PlainID PAA:
  stop_plainid_paa
• Delete the currently installed PAA directory
• Load the new alias file using source command
• Set the relevant environment variables according to the local environment, Tenant ID, and PAA ID.
• Run start_plainid_paa to start the new PAA

The remote URL has been changed from:

PAA Service Configurations

Ensure you make the following changes in both applications.yaml files in the Agent and PIP-Operator "conf" files:

• Redis

  • Locate the Spring Redis service configuration and add the username parameter:

      - spring:
          redis:
              username: ${REDIS_USER:} 
  

• Secrets Management

  • Add the following block to configure Secrets Management:

  secretMgmtClient:
    url: ${SECRET_MGMT_CLIENT_URL:http://127.0.0.1:8072/1.0/secrets/list}
    apiClient:
      timeoutSeconds: ${SECRET_MGMT_CLIENT_API_CLIENT_TIMEOUT_SECONDS:30}
    cacheManager:
      durationSeconds: ${SECRET_MGMT_CLIENT_CACHE_MANAGER_DURATION_SECONDS:3600}