1. Access Governance Cloud Service
  2. Integrate
  3. Getting Started with Integration
  4. Agent Administration

Agent Administration

Register and Download a Connected System Agent

In some cases, a connected system does not have a direct connection to Oracle Access Governance and requires an agent to enable data transfer between Oracle Access Governance and the connected system. To enable a connected system agent to connect to Oracle Access Governance, you need to enter connection details and credentials for the target system and build an agent specific to your environment.
  1. In a browser, navigate to the Oracle Access Governance service home page and log in as a user with the Administrator application role.
  2. On the Oracle Access Governance service home page, click on the Navigation Menu icon and select Service Administration and then Connected Systems.
  3. On the tile labeled Would you like to connect to an Identity Governance System, select the Add button.
  4. Click Close on the information pop-up to navigate to the Add an Identity Governance System page and begin the configuration.
  5. On the Select System step, select the tile for the connected system you want to configure the agent for, and then click Next.
  6. On the Enter Details step, enter the following details:
    • Name
    • Description

    Click Next.

  7. On the Configure step, enter connection details for the target system:

    Note:

    The connection details will differ depending on the type of connected system. Refer to the documentation for the connected system type you require for details.

    Integrate with Oracle Identity Governance

  8. On the Download Agent step, select the Download link and download the agent zip file to the environment in which the agent will run.

    The contents of the agent package will look similar to the following:

    agent-package-<version>.zip
    - config.json
    - wallet
        - cwallet.sso
        - cwallet.sso.lck
   - container-image
        - agent.tar.gz

Prerequisites

Prerequisites for installation and running of a connected system agent.

The following prerequisites should be met in order to install and run a connected system agent.

  1. Container runtime:

    The agent management script supports docker and podman as the container runtime. The agent management script auto-detects the container runtime. If both are present, podman is selected.

  2. Utilities:
    A connected system agent requires the following operation system utilities:
    1. unzip
    2. sed
    3. awk
  3. JDK

    A connected system agent requires JDK 11.0.x.

Agent Management Operations

Lists details of the operations that the agent can perform and related parameter descriptions.

The connected system agent can be managed using the agentManagement.sh script. This script can be downloaded from GitHub. The script supports docker and podman, it autodetects the container runtime available. If both are available, the script uses podman.

Operations

Operation Description Additional Information

--install
  • Installs the downloaded agent package to the specified volume.
  • Loads the container image.

Use --config to use a custom configuration.

--start
  • Starts the agent container.
  • Starts the agent daemon.

Use --newcontainer to start a new container.

Use --config to use a custom configuration.

--stop
  • Stops the agent daemon.
  • Stops the agent container.
  

--restart
  • Stops the agent daemon.
  • Stops the agent container.
  • Remove the agent container if newcontainer flag is set to true.
  • Starts the agent container.
  • Starts the agent daemon.
  

--uninstall
  • Stops the agent daemon.
  • Remove the agent container.
  • Clean up the volume.
  

--upgrade
  • Unzips new agent-package.zip in a temporary location.
  • Validates the package contents.
  • Loads the image from the new zip file.
  • Starts a temporary container using the new image and configuration.
  • If the temporary container has no issues then stop the container.
  • Stop the existing container.
  • Copy new configuration from the temporary location to the current location. This retains any customizations.
  • Starts the agent with the new image and configuration.
  • Starts the agent daemon.

The following changes require an upgrade where you will need to download the new agent package from the Oracle Access Governance Console, and invoke the upgrade operation.

  • Change in configuration (config.json
  • Connector bundle change
  • Change in Wallet
  • Change of agent image

The following changes will trigger a reconfigure operation which is handled by the agent framework.

  • Connector (same template version)
  • Connector (different template version)

--status
Lists the following details of the agent:
  • Agent ID
  • Container runtime and version
  • Agent package
  • Agent version
  • Install location
  • Agent state
  

--enableautoupgrade

Enables automatic upgrade by performing the following tasks:

  • Sets up a cron job to detect upgrades for any changes in target connectivity parameters, or in connector bundle code.
  • cron job runs every 24 hours and upgrades the agent automatically if required.
 

--disableautoupgrade

Disables automatic upgrades by removing the auto-upgrade cron job.

 

Install Agent on Target System

To install the downloaded agent into your local system, perform the following steps:
  1. Unzip the downloaded agent to your local location.

    Contents of the unzipped agent should be:

    agent-package-<version>.zip
  - config.json
  - wallet
      - cwallet.sso
      - cwallet.sso.lck
  - container-image
      - agent.tar.gz
  2. Run the management script with the following parameters:
    curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--agentpackage <PACKAGE_FULL_PATH>\
--install

    An example with default configuration would look like the following:

    curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--agentpackage /access-governance/agent-management/agent-package-<version>.zip \
--agentid myagent \
–-install

    An example with custom configuration would look like the following:

    curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--agentpackage /access-governance/agent-management/agent-package-<version>.zip \
--agentid myagent \
--config /access-governance/agent-management/config.properties \
–-install
  3. Start the agent with the following command:
    curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--start

    For example:

    curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--start

Verify Agent

Details how to verify the installation and operation of the connected system agent.

To verify the installation of the connected system agent, complete the following steps:
  1. In the Oracle Access Governance Console, select the Navigation Menuicon to display the navigation menu.
  2. In the Oracle Access Governance Console, select Service Administration → Connected Systems from the navigation menu.
  3. On the Connected Systems screen, the tile showing the Identity Data Orchestrator created in Install Agent on Target System shows a status of Waiting for initial connection. Click on Manage → Troubleshooting Checklist.
  4. The Activity Log at the bottom of the page will show the status of the Validate operation, Pending while the agent comes up. If the agent does not come up, check the agent install and operation logs for any issues.
  5. Once the agent has come up, the status of the Validate operation will show as Success.

Agent Example Usage

Displays examples of usage of the agent management script.

Once you have successfully installed and verified your agent, you can start to manage the lifecycle. The agentManagement.sh script provides support for the start, stop, restart, uninstall, and upgrade operations.

Start the Agent

You start the agent with the following command:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--start

For example:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--start

Stop the Agent

You stop the agent with the following command:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--stop

For example:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--stop

Restart the Agent

You restart the agent with the following command:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--restart

For example:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--restart

Uninstall the Agent

You uninstall the agent with the following command:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--uninstall

For example:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--uninstall

Upgrade the Agent

You upgrade the agent with the following command:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--agentpackage <NEW_PACKAGE_FULL_PATH> \
--upgrade

For example:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--agentpackage /access-governance/agent-management/agent-package-<version>.zip \
--upgrade

Enable Auto Upgrade

Enable auto upgrade with the following command:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh;  sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--enableautoupgrade

For example:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh;  sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--enableautoupgrade

Disable Auto Upgrade

Disable auto upgrade with the following command:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh;  sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--disableautoupgrade

For example:

curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh;  sh agentManagement.sh \
--volume /access-governance/agent-management/volume \
--disableautoupgrade