This onboarding guide takes you through how to set up Oracle Cloud Infrastructure (OCI) with Workbench. This guide is for one device per OCI region. You will need to repeat this process if you are setting up devices in multiple regions. See the Multiple Region Configuration section for more information.
Prerequisites
- Make sure there is a user from your organization with Admin-level cloud access to the relevant cloud environment.
- Have an email address from your organization that can be used to associate with the IAM machine user you will create.
Before You Start
Resource Names
For ease of use, this guide provides suggested names for all region-specific and global resources you will create and that the polling policy will later reference. You may choose to deviate from the suggested names, but be sure to substitute your chosen names where applicable.
Multiple Region Configuration
If you are not onboarding multiple regions and you do not anticipate ever doing so, skip this section.
If you are onboarding multiple regions, please note:
- The cloud resources you will create in Steps 1-6 are region-specific and must be recreated per region. Note that because region-specific resources exist only in a specific region, for simplicity, you may reuse names.
- We recommend you reuse the Identity and Access Management (IAM) resources you will create in Steps 8-11 as they are global across all regions.
See below for more information on resource types and their availability in the console.
Region-specific resources:
- Bucket
- Retention policy
- Lifecycle policy
- Stream
- Rule
- Connector
Global resources:
- Compartment
- User
- User Group
- User key (tied exclusively to its user)
- Policy (note that the policy will list regional resources. This means that while you may use the same policy for each region, adding the additional regional resources to the policy will be mandatory.)
Quick Start
Setup includes the following steps (select any step for detailed instructions):
- Create a Bucket
- Set a Retention Rule
- Set a Lifecycle Policy Rule
- Create a Stream
- Create a Rule
- Create a Connector
- Confirm Your Bucket is Receiving Logs
- Create an Expel Machine User Group
- Create an Expel Log Polling Policy
- Create an Expel Machine User
- Create a User Key
- Add Oracle Cloud Infrastructure as a Security Device in Workbench
During the OCI configuration process, you will need to copy out and save a number of values as you add them or they are generated by OCI. Be sure to delete this file once your device is successfully added to Workbench, as it contains sensitive information. These values include, in the order they are created or generated:
- Region identifier
- OCID
- Messages Endpoint
- user
- fingerprint
- tenancy
- Base64-encoded user key
Knowing each of these values is necessary to successfully complete OCI configuration steps and to also add OCI as a Security Device in Workbench.
Step 1: Create a Bucket
In this step, you will create a bucket to store your audit logs.
- Log in to OCI.
- Make sure you are in the correct OCI region for your device.
- Note your region identifier and save it to a safe place for later use. To find your region identifier, select your region in the top right, then choose Manage regions and refer to the list.
- Navigate to Storage > Object Storage & Archive Storage and select Buckets.
- In the List scope section, select the root compartment if it is not already selected. Be sure to create the rest of your resources in this same root compartment.
- Select Create Bucket.
- On the Create Bucket screen, configure the following settings:
- Bucket Name - enter "Expel_Audit_Bucket".
- Default Storage Tier - leave as Standard, then select Emit Object Events.
- Leave all other defaults on this page as is.
- Select Create. Your new bucket appears in the list.
Step 2: Set a Retention Rule
Expel recommends implementing a Retention Rule Lock, meaning the lock cannot be disabled without bucket deletion. This ensures audit logs remain untouchable during the window Expel maintains to fetch and re-fetch logs.
- In the row for your new bucket, select the three dots menu on the right and choose View Bucket Details.
- Scroll down and select Retention Rules on the left side menu.
- Select Create Rule.
- On the Create Retention Rule screen, configure the following settings:
- Name - enter "Expel_Audit_Protection".
- Retention Rule Type - leave as Time-Bound.
- Retention Duration - set the Retention Time Amount to 7 days. Be sure to select this setting so that the rule can’t be reversed.
- Select Enable Retention Rule Lock.
- Leave the Scheduled Lock Time as it suggests or configure it how you wish.
- Select Create.
- Check the box to confirm you want to create a time-bound retention rule and select Create again.
Step 3: Set a Lifecycle Policy Rule
This step isn’t necessary for Expel functionality, but is highly recommended for cost control. Here you will create a rule to delete files outside of the retention window. For maximum reliability, Expel recommends a 14 day lifecycle.
- Scroll down and select Lifecycle Policy Rules on the left menu.
- Select Create Rule.
- On the Create Lifecycle Rule screen, configure the following settings:
- Name - enter "Delete_After_Expel_Window".
- Target - leave as Objects.
- Lifecycle Action - select Delete.
- Number of Days - enter "14".
- State - leave as Enabled.
- Select Create.
Step 4: Create a Stream
The stream you create here will function as a running log of all the files uploaded to the audit log bucket, helping our event poller to determine what it needs to download.
If you are onboarding a device in multiple regions, you will need to create a stream in each region. For simplicity, you can use the same stream name in each region, however, the associated stream ID (OCID) that is generated will be unique in each region.
- Navigate to Analytics & AI > Messaging > Streaming.
- Select Create Steam.
- On the Create Stream screen, configure the following settings:
- Stream Name - enter "Expel_Audit_Stream".
- Compartment - select the root compartment then choose Auto-Create a default stream pool. If you already have an existing stream pool, choose Select Existing Stream Pool > DefaultPool.
- Define Stream Settings - enter "168" for Retention and "1" for Number of Partitions.
- Select Create.
- In the list of streams, select the stream you just created.
-
Copy the following values and save them to a safe place for later use:
- OCID
- Messages Endpoint
Step 5: Create a Rule
This event rule will tell OCI which events belong in the stream you just created above.
- In the OCI search bar, search "Rules" and then select the Services > Rules result.
- Select Create Rule.
- Set the rule properties:
- Display Name - enter "Expel_Audit_Upload_Event".
- Description - enter "Triggers when files are uploaded to Expel Audit Bucket".
- In the Rule Conditions section:
- Condition - select Event Type.
- Service Name - select Object Storage.
- Event Type - select Object - Create and Object - Update.
- Select + Another Condition.
- Condition - select Attribute.
- Attribute Name - select bucketName.
- Attribute Values - enter "Expel_Audit_Bucket" and press Enter.
- In the Actions section:
- Action Type - select Streaming.
- Stream Compartment - select your root compartment.
- Stream - select Expel_Audit_Stream.
- Select Create Rule.
Step 6: Create a Connector
This connector will forward all the logs in this region’s audit log group to the Expel Audit Bucket.
- In the OCI search bar, search for "Connector Hub" and select the Connector Hub result.
- Select Create connector.
- Set the connector properties:
- Connector name - enter "Expel_Audit_Forwarder".
- Description - enter "Forwards audit log group to Expel Audit Bucket".
- Resource compartment - select your root compartment.
- In the Configure connector section:
- Source - select Logging.
- Target - select Object Storage.
- In the Configure source section:
- Compartment name - leave your root compartment selected.
- Log group - select _Audit.
- Select Include _Audit in subcompartments.
- Skip the Log filter task fields.
- Skip the Configure task section.
- In the Configure target section:
- Compartment - leave your root compartment selected.
- Bucket - select Expel_Audit_Bucket.
- Select Show additional options.
- Batch size (in MBs) - leave blank.
- Batch time (in milliseconds) - enter "60000".
- An alert banner appears. Select Create on the right side of the banner to create your policy.
- The alert banner changes to confirm the policy was created.
- In the Enable logs section, leave logs disabled.
- Select Create in the lower left to create your connector.
Step 7: Confirm Your Bucket is Receiving Logs
Note that it may take 5-10 minutes for resources to be created and for the bucket to populate.
- Navigate to Storage > Object Storage & Archive Storage and select Buckets.
- Select Expel_Audit_Bucket.
- In the Objects section, use the file explorer to verify that log files exist in the bucket. You can also look at the Last Modified time stamps on these files to further verify that the Connector is working.
Step 8: Create an Expel Machine User Group
This group will be used to associate the machine user you will soon create with the policy you will grant to the user. If you have already onboarded a device in another region using this guide, you can reuse the existing user group.
- Navigate to Identity & Security > Identity and select Domains.
- Select your domain (it may be "Default").
- Select Groups in the left menu.
- Select Create group.
- On the Create Group screen, configure the following settings:
- Name - enter "Expel_Machine_Users".
- Description - enter "Group with audit polling permissions".
- Select Create.
Step 9: Create an Expel Log Polling Policy
This will grant our machine user least privileges for its task. If you have already onboarded a device in another region using this guide, you can reuse the existing policy by appending a line allowing access to your new Stream ID. See the Reference section for an example of a policy with two regions.
- Navigate to Identity & Security > Identity and select Policies.
- Select Create Policy.
- On the Create Policy screen, configure the following settings:
- Name - enter "Allow_Expel_Log_Polling".
- Description - enter "Allow Expel to find and download new log files".
- Compartment - select your root compartment if it isn't already.
- In the Policy Builder section:
- Toggle on Show manual editor.
- Copy and paste the following policy into the editor, replacing <Your Stream ID> with the OCID of the stream you created in Step 4. If you deviated from the suggested resource names in this guide, be sure to substitute your names in the policy below.
Allow group 'Default'/'Expel_Machine_Users' to use stream-pull in tenancy where target.stream.id= '<Your Stream ID>'
Allow group 'Default'/'Expel_Machine_Users' to read buckets in tenancy where target.bucket.name= 'Expel_Audit_Bucket'
Allow group 'Default'/'Expel_Machine_Users' to read objects in tenancy where target.bucket.name= 'Expel_Audit_Bucket'
Allow group 'Default'/'Expel_Machine_Users' to read users in tenancy
- Did you use your stream ID in the new policy? Check to be sure before continuing.
- Select Create.
Step 10: Create an Expel Machine User
In this step, you will create a user to add to the new group. If you have already onboarded a device in another region using this guide, you can reuse the existing Expel_Machine_User.
- Navigate to Identity & Security > Identity and select Domains.
- Select your domain (it may be "Default").
- Select Users in the left menu.
- Select Create user.
- On the Create user screen, configure the following settings:
- Last name - enter "Expel_Machine_User".
- Username / Email - we recommend you enter an email you’ll have access to, both so that you can create an API key as the user, and so that OCI can contact you should any problems or maintenance needs arise.
- Select Use the email address as the username.
- Under Groups, select the check box for Expel_Machine_Users.
- Select Create.
- Log out of OCI. In the next step, you will need to log in as the user you just created.
Step 11: Create a User Key
If you have already onboarded a device in another region using this guide, you can reuse the existing API key. If you don't want to do that, you will need to create a new user and add them to the existing group. You can then generate an API key from that user.
- Check for an activation email from Oracle at the address you assigned to the machine user in Step 10. Follow their prompts and log in as the new user.
- Select the profile image in the upper right and select your username.
- Scroll down and select API keys in the left menu.
- In the API keys section, select Add API key.
- On the Add API key screen, select Generate API key pair.
- Select Download private key.
- Select Add.
- Pause at this screen and copy and securely store the following values provided in the configuration file:
- user
- fingerprint
- tenancy
- Rename the .pem file you downloaded to "machineuser.pem" for ease of CLI reference, and base encode it. On UNIX-like systems, you can do this by running
cat machineuser.pem | base64
. - Copy and securely store this output as the base64-encoded user key; you will need to enter it later in Workbench. Be sure to delete the .pem file after you have completed the integration with Workbench.
- After you have recorded all the needed values, select Close.
Step 12: Add Oracle Cloud Infrastructure as a Security Device in Workbench
Now, you can add a Security Device in Workbench to complete the integration.
- Log in to Workbench.
- In the side menu, navigate to Organization Settings > Security Devices.
- Select Add Security Device.
- In the search box, type “Oracle” and then select the Oracle Cloud Infrastructure (OCI) Audit integration.
- A configuration pane displays. Complete the fields as follows:
- Name - in a per-region configuration, we’d recommend <account name>-<Oracle region code>. For example, "Acme-IAD"
- Location - we recommend the OCI region identifier. For example, "us-ashburn-1".
-
Connection Settings - provide the appropriate values you recorded from steps 4 and 11.:
- Stream ID - enter the OCID value.
- Stream endpoint - enter the Messages Endpoint value.
- OCI user - enter the user value.
- OCI key fingerprint - enter the fingerprint value.
- OCI user tenancy - enter the tenancy value.
- OCI region - enter the OCI region identifier for the region you are onboarding. Note that this is NOT the "region" value provided in the configuration file in Step 11.
-
OCI user key, base64 encoded - enter the base64-encoded user key.
Note
If you are onboarding devices for additional regions, you can reuse all of the Connection Settings values except Stream ID, Stream endpoint, and OCI region, which are unique to the region you are onboarding.
- Select Save.
- On the Console access screen, select No thanks, I will not provide console access from the dropdown.
- Select Save.
Your device should be created successfully within a few seconds. It may take a few hours for alerts to appear in the Alerts Analysis dashboard while we tune this device.
Troubleshooting
If you are encountering an error or OCI isn't connecting to Workbench, try checking for some common issues:
- If you are configuring multiple regions, double check how you named your resources, and whether you configured your policy correctly in Step 9.
- Is your device failing to connect in Workbench and showing a 404 error?
- Did you input your stream ID into the log polling policy correctly in Step 9?
- It may be another permissions error. Check your log polling policy in OCI, and confirm your stream ID and bucket name are referenced.
- This may also indicate an issue with your device configuration in Workbench.
- Is your audit bucket receiving logs? Check using these instructions. If not, the issue is likely with the Connector configuration in Step 6. Double check you created a policy allowing the Connector to write to object storage.
- Verify you are seeing messages hit the stream. In OCI, navigate to Streaming > select your stream > Metrics and check the charts. If there is no message activity, check that your Event Rule from Step 5 was configured properly.
Reference
Below is an example of a log polling policy where a device has been configured in two regions. The second statement indicating "WEST" was added to onboard a second region.
Allow group 'Default'/'Expel_Machine_Users' to use stream-pull in tenancy where target.stream.id= '<Your Stream ID-EAST>'
Allow group 'Default'/'Expel_Machine_Users' to use stream-pull in tenancy where target.stream.id= '<Your Stream ID-WEST>'
Allow group 'Default'/'Expel_Machine_Users' to read buckets in tenancy where target.bucket.name= 'Expel_Audit_Bucket'
Allow group 'Default'/'Expel_Machine_Users' to read objects in tenancy where target.bucket.name= 'Expel_Audit_Bucket'
Allow group 'Default'/'Expel_Machine_Users' to read users in tenancy