Manage Oracle Access Governance Agent for Indirect Integrations
In some cases, an orchestrated 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 orchestrated system.
Register and Download the Oracle Access Governance Agent
To enable an orchestrated system to connect to Oracle Access Governance, you need to enter integration details and credentials for the system and build an agent specific to your environment.
Prerequisites
Prerequisites for installation and running of an agent.
The following prerequisites should be met in order to install and run an agent.
- The agent management script supports docker and podman as the container runtime. The agent management script auto-detects the container run time. If both are present, podman is selected.
- The container runtime (docker/podman) should be configured to be run as a non-root user, the same as that which is used to install the agent.
- Utilities:
The agent requires the following operation system utilities:
- unzip
- sed
- awk
- crontab
Note:
The agent installation user should have permission to use each of these utilities. - JDK: Agent requires JDK 11.0.x.
- Enable processes for the OS user that starts the agent to 'linger'
after the user's session is terminated. If this option is not enabled, when you
terminate the user's session the agent process will stop and you will see errors
when trying to communicate between Oracle Access Governance, the agent, and your orchestrated system.
- To check if linger is enabled for your OS user check for a
file with the same name as the user in the
/var/lib/systemd/linger
directory. If the file exists then this option is enabled:ls /var/lib/systemd/linger/oracle/<myuser>
- To enable linger for your OS user enable the systemd linger
behavior:
loginctl enable-linger <myuser>
- To check if linger is enabled for your OS user check for a
file with the same name as the user in the
- Minimum disk space required for the agent should be:
- 4GB freespace for the directory configured as the volume for the agent.
- 5GB freespace for the docker/podman home.
The minimum values above include disk space consumed during upgrade, in the process of which, a backup is created and a new agent image is downloaded and loaded.
Sizing Virtual Machine/Host
The table below suggests values for sizing your orchestrated system agent VM or host for small, medium, and large scale implementations.
Parameter | Description | Small Scale | Medium Scale | Large Scale |
---|---|---|---|---|
CPU Cores |
Number of CPU Cores. |
2 |
4 |
8 |
Memory |
Amount of memory (GB) |
16 |
32 |
64 |
Install Oracle Access Governance Agent
A step-by-step process to install the Oracle Access Governance Agent with sample commands to run:
Verify Agent
Details how to verify the installation and operation of the orchestrated system agent.
- In the Oracle Access Governance Console, select the
icon to display the navigation menu.
- In the Oracle Access Governance Console, select Service Administration → Orchestrated Systems from the navigation menu.
- On the Orchestrated Systems screen, the orchestrated system shows a status of Waiting for initial integration. Click on Manage → Troubleshooting Checklist.
- 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.
- 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> \
--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 \
--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
Perform this step only if absolutely necessary, as this can cause failures in the communication between the agent and the Oracle Access Governance service. If you perform this step and you see failures, immediately upgrade the agent by following the steps mentioned in the Upgrade the Agent example in Agent Example Usage.
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
Custom Jar Support
- Download the driver jar and place it in the
customJarsDirectory
path as specified in theconfig.json
. For example,config.json
may contain an entry,customJarsDirectory : /app/data/customJars
, where/app
is the agent volume. - Calculate the checksum of the downloaded driver jar
using
SHA-512
. - On the Oracle Access Governance Console, go to Service Administration and then Orchestrated Systems.
- On the Connected Systems page, select Manage integration for your orchestrated system.
- Under Configurations, select the Manage button on the Integration Settings tile.
- Update the orchestrated system configuration in the
Custom Jar Details field. Provide the driver
jar name and the checksum in the format
<jarName>::<checksum>
.For DB2 connected system, sample value in Custom Jar Detailsdb2jcc.jar::c8520f145b428b1133b771bb2c70a6f0f546c9f0655f9de5de2e7b64d5ede786911ad50b543846154fe373dead78d38fb6dded560e0de4c4e8ccbbf0a06b6c1e
- Click Save.
Agent Management Operations
Lists details of the operations that the agent can perform and related parameter descriptions.
The orchestrated 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 |
---|---|---|
|
|
Use |
|
|
Use Use |
|
|
|
|
|
|
|
|
|
|
|
The following changes require an upgrade.
The following changes will trigger a reconfigure operation which is handled by the agent framework.
For more information, refer Upgrade an Agent. |
|
Lists the following details of the agent:
|
|
|
Enables automatic upgrade by performing the following tasks:
|
|
|
Disables automatic upgrades by removing the auto-upgrade
|
Agent Parameters
Parameters
Parameter Name | Description | Mandatory | Default Value | Argument | Argument shorthand |
---|---|---|---|---|---|
__AGENT_ID__ |
Agent ID with which the agent container will run. |
No |
|
|
|
Agent Package Location | Local Agent package location with the package name. |
Yes |
--agentpackage |
|
|
Volume |
Directory to persist agent data such as configuration, wallet, and logs. |
Yes |
|
|
|
New Container with start and restart |
Create a new container. This parameter does not need a value.. |
No |
|
|
|
Custom configuration |
Provide custom configurations through a property file. |
No |
|
|
|
Auto Upgrade |
Use this parameter with install operation to setup auto upgrade of the agent. |
No |
|
|
|
Custom configuration is provided to the script via the
config.properties
file that has the following format:
idoConfig.httpClientConfiguration.connectionPool.maxPerRoute=15
idoConfig.httpClientConfiguration.connectionPool.maxTotal=15
idoConfig.httpClientConfiguration.connectTimeoutInSeconds=300
idoConfig.httpClientConfiguration.keepAliveTimeoutInSeconds=300
idoConfig.httpClientConfiguration.readResponseTimeoutInSeconds=300
idoConfig.httpClientConfiguration.proxyUri=
idoConfig.httpClientConfiguration.proxyUserName=
idoConfig.httpClientConfiguration.proxyUserPassword=
idoConfig.logLevel=info
idoConfig.maxJobRunningTimeInMinutes=180
idoConfig.numberOfPartition=3
idoConfig.numberOfOperationsPerPoll=5
idoConfig.numberOfOperationsWorkerThread=5
idoConfig.pollPauseTimeInMills=500
idoConfig.heartBeatIntervalInSeconds=30
idoConfig.sparkMaxResultSizeInGB=2
idoConfig.sparkExecutorMemoryInGB=2
Tuning Runtime Configuration
The table below lists the parameters for fine tuning the runtime configuration of the orchestrated system agent, and suggests specific values for small, medium, and large scale implementations.
Details of how to configure these parameters can be found in Agent Parameters.
Parameter | Description | Small Scale | Medium Scale | Large Scale |
---|---|---|---|---|
idoConfig.sparkMaxResultSizeInGB |
Limit of total size of serialized results of all partitions for each action (e.g. collect) in bytes. Should be at least 1M, or 0 for unlimited. Jobs will be aborted if the total size is above this limit. Having a high limit may cause out-of-memory errors in driver (depends on spark.driver.memory and memory overhead of objects in JVM). Setting a proper limit can protect the driver from out-of-memory errors. |
2 |
5 |
7 |
idoConfig.sparkExecutorMemoryInGB |
Amount of additional memory to be allocated per executor process, in MiB unless otherwise specified. This is memory that accounts for things like VM overheads, interned strings, other native overheads, etc. |
2 |
5 |
7 |
idoConfig.numberOfPartition |
Number of partitions. |
3 |
5 |
7 |
Troubleshooting Oracle Access Governance Agent
Learn how to address error messages and other problems you may see when configuring or using the Oracle Access Governance Agent.
Unexpected Agent Shutdown Due To Resource Constraints
If you start to hit resource limits on memory, CPU, or disk, the agent may unexpectedly shutdown. In order to bring the agent back up again cleanly you should restart the agent after rectifying the underlying issue.
restart
command rectifying the underlying
issue.curl https://raw.githubusercontent.com/oracle/docker-images/main/OracleIdentityGovernance/samples/scripts/agentManagement.sh -o agentManagement.sh ; sh agentManagement.sh \
--volume <PERSISTENT_VOLUME_LOCATION> \
--newcontainer \
--restart
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.