OCI User Access Review Made Easy

I’m sure we can all agree, adopting a cloud strategy is awesome. The opportunities and benefits it affords are many. However cloud governance is an ongoing problem that plagues security, compliance, and management teams, which cloud vendors like Oracle are continually trying to solve.

If you’re reading this, you’ve probably been asked, or heard at least once:

Who has access to what in our environment?

Any Security / Compliance Manager

The answer should be easy and simple. However the reality is likely lots of manual time & work, spreadsheets, and endless clicking in a cloud console. If you’re doing this manually then I agree, it’s time that you could be dedicating to more important tasks.

The challenge in trying to answer these questions:

  • What users exist and what groups do they belong to?
  • What does my OCI tenancy compartment structure look like?
  • What policies have users explicitly created?
  • What permissions do users have in my tenancy?
  • Are there any excessive / non-compliant policies & permissions in my tenancy?

is that these complex relationships can’t be easily represented and interpreted in a table-like format. In the OCI ecosystem:

  • users can be federated with an Identity Provider and can belong to one or many federated, or local IAM groups,
  • policies can be defined for “any-user” or for a group,
  • policies are inherited meaning they apply to all sub-compartments from which the policies are applied.

To make things easier I’ve created a solution using Oracle tools and services to simplify the auditing of OCI tenancies and user permissions called “Peek”.

Peek comprises of a Docker container with MySQL, the OCI-CLI & a Ruby script and uses an Oracle APEX Instance to view the data and visualise these complex relationships. Here’s a short video that demonstrates and explains Peek in action:

Running Peek yourself, is easy, and can be set up in as little as 20 minutes. However before we begin there are a few pre-requisites which you’ll need:

Installing Peek into Oracle APEX

First we’ll install and configure the Peek application into your APEX instance. If you don’t have an existing APEX instance, you can create one via the OCI Console.

  1. Create an APEX instance with default settings E.g. Database Version 19c, 1 OCPU, 1TB Storage, or settings that you wish to use.
  2. Log in to your APEX instance with the ADMIN user password you specified during creation.
  3. Click “Create Workspace” and enter
    1. Database User: PEEK
    2. Password: <a strong password>
    3. Workspace Name: PEEK
  4. Click “Sign in to PEEK”, which is shown in the green alert box at the top of the page.
  5. Enter your user credentials created during Step 3.
  6. Download the Peek application ZIP file from Github https://github.com/scotti-fletcher/peek-apex/blob/main/peek-apex-1.0.zip
  7. Select “Import” from the App Builder drop down menu.
  8. Select the downloaded file, ensure File Type “Database Application, Page or Component Export” is selected and click Next.
  9. The File Import Confirmation will display, click Next.
  10. The Install Database Application will be displayed, you can accept all default values. Click “Install Application”.
  11. The Install Application confirmation will display, click Next.
  12. Click Install.
  13. Click “Edit Application”.
  14. Select “SQL Scripts” from the SQL Workshop drop down menu.
  15. Download the Peek application database script from Github https://github.com/scotti-fletcher/peek-apex/blob/main/peek-apex-db.sql
  16. Edit the SQL file and update the values of p_email_address and p_web_password to those you’d like to use. It’s highly recommended you choose a new, unique, strong password.
  17. Click Upload, Select the file you downloaded in Step 15 and edited in Step 16, enter “Install” into Script Name, and click Upload.
  18. Click the Run button on the uploaded script.
  19. Click “Run Now”.
  20. Click “Manage Users and Groups” from the top right menu.
  21. Click the API user.
  22. Click “Group Assignments”
  23. Select all “oracle.dbtools.role.autorest.*” groups from the left list box and add them to the right list box.
  24. Click “Apply Changes”
  25. To confirm your APEX ORDS RESTful services are configured correctly you can run:
    curl -i -k --user API:<password from Step 16> https://<your apex hostname>/ords/peek/grant/
    and you should receive a HTTP 200 response with a JSON body.

If you have an Oracle Identity Domain Cloud Service

This part is optional. However if you are using IDCS, to map and visualise the IDCS / IAM Group relationships we must configure IDCS to allow our Docker container to retrieve the information from the IDCS API.

Note: Oracle Identity Cloud Service is in the process of becoming OCI IAM Identity Domains. I will update this guide to include Identity Domain specific instructions in the near future.

  1. Log in to your Oracle Identity Cloud Service console.
  2. Select Applications from the left-hand menu.
  3. Click “Add”, and select “Confidential Application” to create a new Application.
  4. Name the Application “Peek”, optionally provide a description and click “Next”.
  5. Select “Configure this application as a client now” and check the “Client Credentials” checkbox. Note the checkboxes are on the left side of the word.
  6. Scroll down to “Grant the client access to Identity Cloud Service Admin APIs” and click Add.
  7. Select “Audit Administrator” and click Add.
  8. Scroll up and click Next.
  9. On the “Expose API’s to Other Applications” page leave “Skip for later” selected and click Next.
  10. On the “Web Tier Policy” page leave “Skip for later” selected and click Next.
  11. Click Finish, Your Client ID and Client Secret will be displayed. Note these down in a text file for later and click Close.
  12. Click “Activate”. This is important otherwise your API calls will fail.

Gathering Required Input Values

Before we run the Docker container we first need to gather a few additional details which are required by the Ruby script running in the docker container, specifically:

  • Your OCI Tenancy OCID.
  • The OCI IAM URL.
  • The URL for your APEX Instance.
  • The credentials you created for the APEX API user.
  • The full path to your local directory where your OCI config and .pem key exists.

And, if you have an IDCS Instance:

  • The previously created IDCS Client ID.
  • The previously created IDCS Secret.
  • The URL of your IDCS instance.
  • The OCID of your IDP integration.

Below are instructions on how to obtain these values. I suggest noting them values down in a text file as we will be passing these values as environment variables to our Docker container.

To find your OCI Tenancy OCID

In the OCI Console, navigate to “Identity & Security” and click Compartments. Your Tenancy OCID should be the first line, hover over the OCID and click Copy

In your text editor add a line:

OCI_TENANCY_OCID = <value from clipboard>

To find your IAM URL

Your IAM URL will be https://identity.<oci-region>.oraclecloud.com. You will need to replace “<oci-region>” with one of the regions you are subscribed. As an example my URL looks like https://identity.ap-sydney-1.oraclecloud.com

After making the substitution, add the line to your text editor:

OCI_IAM_URL = https://identity.<oci-region>.oraclecloud.com

To find your APEX URL

Click “Launch Apex” from the OCI console, and copy the Hostname from your web browser address bar. As an example the URL looks like https://yj6g7sq14zvoj-peek.adb.ap-sydney-1.oraclecloudapps.com. Note that there should be no trailing forward slash at the end.

Add this line to your text file:


To find your OCI config Directory

The OCI CLI config typically lives in ~/.oci/. The config file must contain a DEFAULT profile which will be used by the Docker container. The ~/.oci/ directory must also contain the .pem key. If you have multiple profiles in your ~/.oci/config file you may wish to create a separate directory with just the config and .pem key just for this activity. As an example my ~/.oci/ directory looks like:

scott@scott-mac ~ % ls -alh /Users/scott/.oci 
drwxr-xr-x   6 scott  staff   192B 15 Jun 14:59 .
drwxr-x---+ 58 scott  staff   1.8K 20 Jun 11:55 ..
-rw-------@  1 scott  staff   1.7K  7 Apr 15:12 mykey.pem
-rw-------@  1 scott  staff   610B 15 Jun 14:59 config

Note that I’m using the full path to the Directory, and I’ll use this full path when mounting this directory to the Docker container.

If you don’t have federation configured you can skip ahead to Running Peek Docker container

To find your IDCS URL

In the OCI Console, navigate to “Identity & Security” and click Federation, click your Federation Provider, as an example mine is called OracleIdentityCloudService.

Copy the Hostname (without the path) from the “Oracle Identity Cloud Service Console” URL displayed. As an example it looks like https://idcs-5dfhhd61c419aad5d31c8.identity.oraclecloud.com

Add this line to your text editor:


To find your IDP ID

To obtain your IDP ID run the OCI-CLI command:

oci iam identity-provider list --protocol SAML2 --compartment-id <your tenancy OCID>

which will return a JSON response, in it is an “id” field. As an example it looks like ocid1.saml2idp.oc1..aaaaaaaaosb62razrasjddsjdsjjsdsbto655kdfvow5ipfb4i7yina

Add this line to your text file:

IDP_ID = <your IDP OCID>

Lastly add these values to your text file:

IDCS_CLIENT_ID = <Client ID from Step 11>
IDCS_SECRET = <Secret from Step 11>

Running Peek Docker container

Before we run the Docker container, you’ll need to ensure you have all the correct values in your text file. It should contain the following values:

APEX_PASSWORD=<Password from Step 16>
APEX_URL=<Your APEX Hostname>

#If you're using IDCS
IDCS_CLIENT_ID=<Client ID from Step 11>
IDCS_SECRET=<Secret from Step 11>
IDCS_URL=<Your IDCS Hostname>

Pull the Docker container by running the command

 docker pull scottfletcher/oci-peek:latest

Launch the Peek Docker container from the image with the command:

docker run -it --name peek \
--mount type=bind,source=/Full/Path/To/.oci/,target=/root/.oci/,readonly \
-e OCI_TENANCY_OCID=<from text file> \
-e OCI_IAM_URL=<from text file> \
-e APEX_URL=<from text file> \
-e APEX_PASSWORD=<from text file> \
-e IDCS_URL=<from text file> \
-e IDP_ID=<from text file> \
-e IDCS_CLIENT_ID=<from text file> \
-e IDCS_SECRET=<from text file> \

Note: You’ll need to replace the /Full/Path/To/.oci/ value to your local directory as explained earlier. Also ensure there are no spaces between your key name, the equals sign, and the value as shown.

The Docker container will start and the information will populate to your APEX Instance. Populating Users & Groups takes approximately 5-10 minutes, after which time you’ll be able to see those results in your APEX application:

Viewing users in Peek APEX Application

Depending on the number of users, groups, compartments and policies in your tenancy the entire process may take an hour or so to complete.

After mapping the users and groups, compartments and policies the visualisation tree will begin populating. As each user’s permission tree is created, it is pushed to APEX via API and you can start your User Access Review.

When the process has completed, the Ruby script in the container will terminate and you’ll be able to see that in the Docker output in your terminal. You can then stop the Docker container.

To re-run the process, simply start another docker container. All previous results stored in the APEX database will be removed and new results populated.

For more information on how to view and interpret the data in Peek, I recommend watching the video at the beginning of this post.

Some final comments

  • Use strong, randomly-generated passwords as described in this post. Also be conscious of where credentials are stored, and who has access to them.
  • As a security practitioner, I would always recommend reviewing code before running it. The code for the script lives in /peek in the Docker container
  • If you have any issues, would like some help interpreting the results please feel free to contact me at scott.fletcher@oracle.com.
  • Lastly, I’ll be updating the solution to work with IAM Identity Domains in the next release. If you’d like to use Peek before then, please let me know in the comments.

I hope you’ve found this post helpful and Peek a useful tool to help with your OCI User Access Review.

Monitoring External Oracle Database in OCI

The  OCI Observability & Management (O&M) platform gives you the ability to also manage your Oracle Database targets that reside on-premise or hosted on an external platform to OCI.

In order to deploy this, please ensure you have met the prerequisites:

  • Install the O&M Management Agent
  • Enable the Services for Agent Plugin :
    1. DB Management
      –  lifecycle database management capabilities for monitoring, performance management, tuning, and administration
    2. Operations Insights
      – analyze and forecast database performance and resource consumption

There are 2 Types of Deployments are available that can be Registered as External Databases

  • Option 1: Multitenant Architecture – Register Container Databases (CDB) and Pluggable Databases (PDB)
  • Option 2: Non-Multitenant Architecture – Register Non-Container Database (NCDB)

In this example we will show you how to register for:

Option 1: External Databases for the Multitenant Architecture.

Continue reading “Monitoring External Oracle Database in OCI”

Ingesting Logs into OCI Logging Analytics (via Agent Based Deployment)

Logs are often voluminous can be challenging to navigate through, but it can be a gold mine of valuable data to help administrators troubleshoot and identify issues or trends for operational activities.

To overcome the burden of manually eye-balling millions or (even billions) of rows in log records, bringing that data into OCI Logging Analytics (which is part of the Observability & Manageability Portfolio) will allow administrators to get quick insights, to reduce the time to isolate issues, minimising downtime and prevent impact to end users.

Continue reading “Ingesting Logs into OCI Logging Analytics (via Agent Based Deployment)”

OCI Observability & Management Platform (O&M) – Agent Based Monitoring

There are various ways you can bring telemetry and operational data into OCI Observability & Management (O&M) to proactively monitor and gain operational insights into your IT fleet.

Example of ways you can do this are:

  • Service Connector Hub – Route and move data from one OCI service to Another OCI Service (eg. OCI Logging to Logging Analytics)
  • API Call – Collect data from files stored on Object Storage or Upload Log data on demand
  • Agent Based – Deployment of Agent on Host

If you have targets you want to monitor on-premise or in the cloud (OCI, AWS, Azure etc…) and you have access to the VM or Compute instance (ie. you can SSH or Remote Desktop to the host), then an Agent based method will allow you to collect and bring that data into unified platform in O&M.

In this example we will show how you can deploy Agent based method (on Linux OS) so you can leverage the O&M services including:

  • Logging Analytics
  • DB Management
  • Operations Insights
  • Java Management Service

1 – NETWORK COMMUNICATION (For External Targets to OCI)

NOTE: The additional network communication setup is not required if the targets you are monitoring are within your OCI tenancy account.


For Setup Compartments, IAM Groups and Policies

Please also check the following tasks has been completed.

NOTE: You may need to contact your OCI administrator to grant you the appropriate permissions.


  1. From OCI Console navigate to:


2. Specify details and Click on CREATE

  • Key Name (eg. oci-reg-key)
  • Compartment (eg. shared_resources)

3. Review Key and Download Key to File (eg. oci-reg-key.txt)

NOTE: Your Key File will be in the format of <Key Name>.txt. Copy it to your target host.

4. Download Agent by clicking on the Agent for your OS (eg. Agent for LINUX) and copy to your target host

Alternatively you can download the agent file using wget:
wget https://objectstorage.<oci-region>.oraclecloud.com/n/idtskf8cjzhp/b/installer/o/Linux-x86_64/latest/oracle.mgmt_agent.rpm 

wget https://objectstorage.ap-sydney-1.oraclecloud.com/n/idtskf8cjzhp/b/installer/o/Linux-x86_64/latest/oracle.mgmt_agent.rpm 


1. Login to the host and locate the downloaded agent file oracle.mgmt_agent.rpm

$ sudo rpm -ivh oracle.mgmt_agent.rpm
Preparing...                          ################################# [100%]
Checking pre-requisites
        Checking if any previous agent service exists
        Checking if OS has systemd or initd
        Checking available disk space for agent install
        Checking if /opt/oracle/mgmt_agent directory exists
        Checking if 'mgmt_agent' user exists
        Checking Java version
                JAVA_HOME is not set or not readable to root
                Trying default path /usr/bin/java
                Java version: 1.8.0_271 found at /usr/bin/java
Updating / installing...
   1:oracle.mgmt_agent-201113.1621-1  ################################# [100%]

Executing install
        Unpacking software zip
        Copying files to destination dir (/opt/oracle/mgmt_agent)
        Initializing software from template
        Creating 'mgmt_agent' daemon
        Agent Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log.0

        Setup agent using input response file (run as any user with 'sudo' privileges)
                sudo /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=[FULL_PATH_TO_INPUT.RSP]

Agent install successful

2. Verify that the agent has been installed.

$ rpm -qa|grep mgmt_agent

3. Copy the Downloaded key file (eg. oci-reg-key.txt)

$ cp oci-demo-key.txt /tmp/input.rsp
$ chmod 755 /tmp/input.rsp

4. Update the parameter CredentialWalletPassword with your own password in the input.rsp file and then save file.

CredentialWalletPassword = YourP8ssW0rd123!

5. Then execute the setup script to install the agent

$ sudo /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=/tmp/input.rsp

6. When completed, check status of agent on host

For Oracle Linux 6: sudo /sbin/initctl status mgmt_agent
For Oracle Linux 7 or later: sudo systemctl status mgmt_agent

$ sudo systemctl status mgmt_agent
● mgmt_agent.service - mgmt_agent
   Loaded: loaded (/etc/systemd/system/mgmt_agent.service; enabled; vendor preset: disabled)
   Active: active (running) since Thu 2020-12-03 05:20:43 GMT; 6min ago
  Process: 3072 ExecStart=/opt/oracle/mgmt_agent/agent_inst/bin/agentcore start sysd (code=exited, status=0/SUCCESS)
 Main PID: 3148 (wrapper)
   Memory: 248.5M
   CGroup: /system.slice/mgmt_agent.service
           ├─3148 /opt/oracle/mgmt_agent/agent_inst/bin/./wrapper /opt/oracle/mgmt_agent/agent_inst/bin/../config/wrapper.conf wrapper.syslog.ident=mgmt_agent wrapper.pidfile=/opt/oracle/mgmt_agent/agent_inst/bin/../log/mgmt_agent.pid wrapper.daemonize=TRU...
           └─3163 /usr/java/jre1.8.0_271-amd64/bin/java -Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=5 -Djava.security.egd=file:///dev/./urandom -XX:+HeapDumpOnOutOfMemoryError -Xmx512m -Djava.library.path=../../201113.1621/lib -classpath...

Dec 03 05:20:31 oma-host systemd[1]: Starting mgmt_agent...
Dec 03 05:20:31 oma-host agentcore[3072]: Starting mgmt_agent...
Dec 03 05:20:38 oma-host agentcore[3072]: Waiting for mgmt_agent.........
Dec 03 05:20:43 oma-host systemd[1]: Started mgmt_agent.


  1. In OCI Console, navigate to:

    Then click on the link to drill into the Agent (eg. Agent (snoopy))

2. Click on the Deploy Plug-Ins button

3. Choose the Plug-ins to deploy for your agent.

NOTE: If the plug-in is greyed out, then the plug-in is already enabled.

Now you should be ready to configure your service for:

For further details please visit:

%d bloggers like this: