OCI Monitoring Should Have Authentication Failure Alarm Configured

​

1. Prerequisites

1. Permissions
   • Your user/group must have policies allowing:
     • use metrics in compartment <compartment-name>
     • manage alarms in compartment <compartment-name>
     • use ons-topics in compartment <compartment-name> (for notifications)
2. Create a Notification Topic (if you don’t have one)
   1. In the OCI Console, open the navigation menu.
   2. Go to Developer Services → Notifications.
   3. Make sure you’re in the correct compartment.
   4. Click Create Topic.
   5. Enter a Name (e.g., auth-failure-alerts) and optional Description.
   6. Click Create.
   7. Open the topic you just created → Create Subscription.
   8. Choose Protocol (e.g., Email), enter your Email address, and click Create.
   9. Confirm the subscription from the email you receive.

​

2. Identify / Use the Authentication Failure Metric

• Namespace: something like oci_iam or oci_audit (depends on how your environment is set up)
• Metric name example: AuthenticationFailures, AuthFailureCount, or a custom metric name you defined
• Dimensions: may include tenantId, region, identityDomain, userName, etc.

1. Go to Observability & Management → Monitoring → Metrics Explorer.
2. Select the correct Compartment.
3. In Metric Namespace, browse likely namespaces (e.g., oci_iam, oci_audit, or your custom namespace).
4. Check metrics list for a metric related to authentication failures (names often contain auth, authentication, or login).
5. Once found, note:
   • Namespace
   • Metric name
   • Available dimensions (e.g., userName, requestAction, responseCode)

​

3. Create the Alarm

1. In the OCI Console, open the navigation menu.
2. Go to Observability & Management → Monitoring → Alarms.
3. Select the compartment where you want the alarm defined.
4. Click Create alarm.

​

4. Configure Alarm Details

1. Alarm name:
   e.g., authentication-failures-detected
2. Alarm severity:
   Choose e.g., Critical or Warning, depending on your policy.
3. Alarm body (optional but recommended):
   Provide a concise description, e.g.:
   • Triggers when any authentication failures are detected above threshold.

​

5. Configure the Metric & Trigger

1. Metric namespace:
   Select the namespace you identified, e.g. oci_iam or your custom namespace.
2. Metric name:
   Select the authentication-failure metric, e.g. AuthenticationFailures (or your actual name).
3. Compartment for metric scope:
   Choose the compartment that holds the metric (often root compartment/tenancy).
4. Dimensions / Filters (optional but recommended):
   • You can scope the alarm to a subset, for example:
     • identityDomain = <your-domain>
     • Or exclude service accounts, or focus on certain regions.
   • In the Dimensions section, set filters as needed (e.g., userName != <service-user> if supported).
5. Statistic:
   • Typically Sum over the interval is used for counts.
6. Interval:
   • Set evaluation interval, e.g. 5 minutes or 1 minute depending on your desired sensitivity and cost.
7. Trigger rule:
   • For example:
     • Condition: Sum > 0
     • Over: 1 or 2 consecutive periods.
   • This means: if there is at least 1 authentication failure in the selected period, alarm fires.
   • If you expect occasional benign failures, set a higher threshold, e.g. Sum > 5 in 5 minutes.
8. Query Preview:
   • Most regions now show an MQL-like expression; confirm that it matches your selected metric and dimensions.
   • Use View chart (if available) to verify data is returned and looks correct.

​

6. Configure Notifications & Lifecycle

1. Destination service:
   • Choose Notifications.
2. Topic:
   • Select the Notification topic created earlier (e.g., auth-failure-alerts).
3. Repeat notifications (optional):
   • Configure if you want reminders while the alarm remains in FIRING state (e.g., every 60 minutes).
4. Alarm state:
   • Leave as Enabled so it starts evaluating immediately after creation.
5. Click Create alarm.

​

7. Test the Alarm

1. Generate a test authentication failure, e.g.:
   • Attempt to log in with wrong credentials to OCI Console or an API using bad keys (in a safe/test context).
2. Wait one or two evaluation periods (e.g., 5–10 minutes).
3. Check:
   • Your email (or other endpoint) for a notification.
   • The alarm’s state in Monitoring → Alarms (should move to FIRING when threshold is met and then back to OK when failures stop).

​

8. (Optional) Fine-tune

• If you get too many alerts:
  • Increase threshold (e.g., Sum > 10).
  • Increase evaluation period.
  • Add filters (e.g., focus on specific identity domain or high-risk regions).
• If you miss events:
  • Lower the threshold.
  • Reduce the period (e.g., from 10 min to 5 min).

​

0. Prerequisites

• OCI CLI configured (oci setup config)
• OCID of:
  • Compartment where you want to create the alarm
  • Compartment where the metric is emitted (often the root compartment/tenancy)
  • An OCI Notifications topic (for email/Slack/etc. alerts)

​

1. Identify the Authentication Failure Metric

oci monitoring metric list \
  --compartment-id <TENANCY_OCID> \
  --compartment-id-in-subtree true \
  --namespace oci_iam \
  --all

• Namespace: oci_iam
• Metric name: e.g. AuthenticationFailures, AuthFailures, FailedAuthentication

oci monitoring metric list \
  --compartment-id <TENANCY_OCID> \
  --compartment-id-in-subtree true \
  --namespace oci_identity_domain \
  --all

• namespace (e.g. oci_iam)
• name (e.g. AuthenticationFailures)

​

2. Craft the Alarm Query

AuthenticationFailures[5m].sum() > 0

AuthenticationFailures[5m].sum({region = "us-ashburn-1"}) > 0

​

3. Create the Alarm via OCI CLI

oci monitoring alarm create \
  --compartment-id <ALARM_COMPARTMENT_OCID> \
  --display-name "OCI IAM Authentication Failures" \
  --metric-compartment-id <METRIC_COMPARTMENT_OCID> \
  --namespace "oci_iam" \
  --query-text 'AuthenticationFailures[5m].sum() > 0' \
  --severity "CRITICAL" \
  --destinations '["<NOTIFICATIONS_TOPIC_OCID>"]' \
  --is-enabled true \
  --resolution "1m" \
  --pending-duration "PT1M" \
  --message-format "PRETTY_JSON" \
  --body "Alarm triggers when any IAM authentication failure is detected in the last 5 minutes."

• --compartment-id: where the alarm object lives.
• --metric-compartment-id: where the metric is emitted (often root/tenancy).
• --namespace: the metric namespace (e.g. oci_iam).
• --query-text: the metric expression you built above.
• --destinations: JSON array of Notifications topic OCIDs.

​

4. Verify the Alarm

oci monitoring alarm list \
  --compartment-id <ALARM_COMPARTMENT_OCID> \
  --display-name "OCI IAM Authentication Failures"

oci monitoring alarm-status get \
  --alarm-id <ALARM_OCID>

oci monitoring alarm update \
  --alarm-id <ALARM_OCID> \
  --query-text 'AuthenticationFailures[5m].sum() > 0'

1. Discover the right metric via CLI/Console.
2. Create the alarm via Python using that metric.

​

1. Discover the Authentication Failure Metric

1. Go to OCI Console → Observability & Management → Monitoring → Metrics Explorer.
2. Under:
   • Compartment: choose the tenancy root (or where IAM/Audit is).
   • Service: select your auth-related service (e.g., identity, audit, or a custom namespace if you send auth failures as custom metrics).
3. Search for metrics that represent authentication failures. Common patterns:
   • FailedAuthentication
   • FailedLogin
   • AuthFailure
   • Anything obviously related to login/auth failures.
4. Note:
   • Namespace (e.g., oci_identity, oci_audit, or your custom namespace).
   • Metric name (e.g., FailedAuthenticationCount).
   • Dimensions such as resourceId, region, etc., if present.

metric[1m]{namespace = "oci_identity", name = "FailedAuthenticationCount"}.sum()

metric[1m]{namespace = "oci_identity", name = "FailedAuthenticationCount", resourceId = "ocid1.tenancy.oc1..xxxxx"}.sum()

​

2. Python Setup

pip install oci
oci setup config

​

3. Python Code to Create the Alarm

import oci
from oci.monitoring.models import (
    CreateAlarmDetails,
    AlarmDimensionStates,
    Suppression
)

# 1. Basic config & clients
config = oci.config.from_file("~/.oci/config", "DEFAULT")

monitoring_client = oci.monitoring.MonitoringClient(config)
notifications_client = oci.ons.NotificationDataPlaneClient(config)
identity_client = oci.identity.IdentityClient(config)

# 2. REQUIRED VALUES – UPDATE THESE
compartment_id = "<COMPARTMENT_OCID_FOR_MONITORING_AND_ALARM>"  # Often tenancy root
alarm_display_name = "Authentication Failure Alarm"
alarm_description = "Triggers when authentication failures exceed threshold."

# Metric query expression copied from Metrics Explorer (adjust namespace/name/filter)
# Example ONLY – replace with your actual expression
query_expression = (
    'metric[5m]{namespace = "oci_identity", '
    'name = "FailedAuthenticationCount"}.sum()'
)

# Threshold and severity
threshold = 5  # e.g., more than 5 failed auths in 5 minutes
severity = "CRITICAL"  # or "ERROR", "WARNING", "INFO"

# 3. (Optional) Set up an existing Notifications topic
#    Get or create an ONS topic via Console, then use its OCID here:
notification_topic_id = "<ONS_TOPIC_OCID>"  # e.g. for email/SMS/Slack

# 4. Build alarm details
create_alarm_details = CreateAlarmDetails(
    compartment_id=compartment_id,
    display_name=alarm_display_name,
    # Monitoring query
    query=query_expression,
    # e.g. ">" or ">="
    condition=">" + str(threshold),
    # If TRUE, the alarm is enabled immediately
    is_enabled=True,
    # "PENDING", "FIRING" transitions
    severity=severity,
    # How often to evaluate (ISO8601): "PT1M"=1 min, "PT5M"=5 min
    resolution="PT5M",
    # How long a condition must be met before posting notifications (optional)
    # "PT0M" = immediate
    pending_duration="PT0M",
    # List of Notification Topic OCIDs
    destinations=[notification_topic_id],
    body=(
        "Authentication failure rate exceeded threshold. "
        "Check Audit logs, IAM policies, and possible attacks."
    ),
    description=alarm_description,
    # Whether to treat missing data as zeros or ignore
    # "IGNORE", "EVALUATE_AS_ZERO", "NOT_AVAILABLE"
    is_notifications_per_metric_dimension_enabled=False,
    message_format="ONS_OPTIMIZED"
)

# 5. Create the alarm
response = monitoring_client.create_alarm(create_alarm_details)
alarm = response.data

print("Alarm created:")
print("  OCID:         ", alarm.id)
print("  Display Name: ", alarm.display_name)
print("  Query:        ", alarm.query)
print("  Condition:    ", alarm.condition)

​

4. Verifying

1. In Console, go to Observability & Management → Monitoring → Alarms.
2. Confirm your alarm:
   • is Enabled
   • has the correct query, threshold, and compartment
   • is associated with the correct Notifications topic.
3. Trigger a test authentication failure (e.g., deliberate login failure) and confirm:
   • the metric increases in Metrics Explorer
   • the alarm moves to FIRING and you receive a notification.

​

5. Hardening Notes

• Use a short evaluation window (e.g., metric[1m] or metric[5m]) for near real-time detection.
• Tune thresholds to reduce false positives:
  • E.g., multiple failures within 5 minutes.
• Optionally create separate alarms per:
  • Region
  • Compartment
  • Critical users/groups (using metric dimensions in the query).

resource "oci_monitoring_alarm" "identity_auth_failure_alarm" {
  # Replace with your OCI compartment OCID where the audit/identity metrics reside
  compartment_id = "OCID_OF_TARGET_COMPARTMENT"

  # A human-readable name for the alarm
  display_name = "Identity Authentication Failure Alarm"

  # Optional description
  description = "Triggers when IdentityAuthFailure events exceed threshold, indicating possible brute-force or compromised credentials."

  # The Monitoring namespace and metric depend on how you've exposed auth failures as metrics.
  # Commonly this is from audit logs or identity metrics; set these placeholders accordingly.
  # Example pattern (EDIT THESE VALUES, INCLUDING DIMENSIONS, TO MATCH YOUR METRIC):
  #
  #   <metric_namespace>  = e.g. \"oci_audit\" or \"custom_identity_auth\"
  #   <metric_name>       = e.g. \"IdentityAuthFailureCount\"
  #   <resource_dimension>= e.g. \"resourceId\" or another dimension you filter on
  #
  # The key requirement is that the query selects IdentityAuthFailure events and
  # applies the desired threshold.
  query = <<-EOT
    METRIC(\"METRIC_NAMESPACE\", \"METRIC_NAME\")
      .filter(eventType = \"IdentityAuthFailure\")
      .sum() > THRESHOLD_VALUE
  EOT

  # Replace with a reasonable threshold (e.g., 5 failures in 5 minutes)
  # Example: THRESHOLD_VALUE = 5
  # The value itself is embedded in the query above.

  # Interval at which the alarm evaluates the query
  resolution = "5m"

  # How long the condition must be met before firing
  pending_duration = "5m"

  # Notification topic (replace with your Notifications topic OCID)
  is_notifications_per_metric_dimension_enabled = false
  is_enabled                                   = true
  severity                                     = "CRITICAL"
  message_format                               = "RAW"
  repeat_notification_duration                  = "60m"

  # Where to send notifications (OCI Notifications topic OCID)
  destinations = [
    "OCID_OF_OCI_NOTIFICATIONS_TOPIC"
  ]

  # Optional: suppress alarms during maintenance windows
  # suppression {
  #   time_suppress_from = "2026-08-01T00:00:00Z"
  #   time_suppress_until = "2026-08-01T02:00:00Z"
  #   description = "Planned maintenance window"
  # }
}

• Substitute:
  • OCID_OF_TARGET_COMPARTMENT with the compartment OCID where the metric is emitted.
  • METRIC_NAMESPACE and METRIC_NAME with the actual namespace/metric that tracks IdentityAuthFailure events.
  • THRESHOLD_VALUE inside the query with the numeric threshold your policy requires.
  • OCID_OF_OCI_NOTIFICATIONS_TOPIC with an actual Notifications topic OCID.