Directory Service SNS Notifications

Overview

This check verifies that AWS Directory Service directories are configured to send status change notifications through Amazon SNS. When enabled, the directory publishes messages whenever its status changes (for example, from "Active" to "Impaired" or back to "Active").

Risk

Without directory notifications enabled, you may not know when your directory encounters problems:

• Delayed incident response: Your team won't be alerted when the directory becomes impaired, leading to longer outages
• Authentication failures: Directory issues can break Kerberos/LDAP lookups and domain joins, affecting user access
• Increased recovery time: Without timely alerts, problems go unnoticed until users report them
• Undetected failures: Replication or trust relationship failures may silently impact dependent workloads

Remediation Steps

Prerequisites

You need:

• AWS Console access with permissions to modify Directory Service settings
• An existing AWS Managed Microsoft AD or AD Connector directory
• Permission to create or use an SNS topic in the same region as your directory

IAM permissions and topic naming requirements

Your IAM user or role needs these permissions:

• ds:RegisterEventTopic
• ds:DescribeEventTopics
• sns:CreateTopic (if creating a new topic)
• sns:Subscribe (to add notification recipients)

Important: If your IAM user only has the DirectoryServiceFullAccess managed policy (without additional SNS permissions), you must name the SNS topic starting with DirectoryMonitoring (for example, DirectoryMonitoring-MyDirectory).

AWS Console Method

1. Open Directory Service in the AWS Console

   • Go to Directory Service Console in us-east-1

2. Select your directory

   • On the Directories page, click the directory ID you want to configure

3. Go to the Maintenance tab

   • On the directory details page, click the Maintenance tab

4. Create a notification

   • In the Directory monitoring section, click Actions
   • Select Create notification

5. Configure the notification

   • Under Choose a notification type, select:
     • Create a new notification to create a new SNS topic, or
     • Associate existing SNS topic to use an existing topic
   • Choose a Recipient type (Email or SMS)
   • Enter the recipient's email address or phone number
   • For SMS: Enter digits only (no dashes or spaces); you must also provide a display name (max 10 characters)

6. Save the notification

   • Click Create

To add more recipients (such as multiple emails, SQS queues, or Lambda functions), use the Amazon SNS Console to subscribe additional endpoints to the topic.

AWS CLI (optional)

Step 1: Create an SNS topic (if needed)

If you don't already have an SNS topic, create one:

aws sns create-topic \
    --name DirectoryMonitoring-MyDirectory \
    --region us-east-1

Note the TopicArn from the output.

Step 2: Subscribe to the topic

Add an email subscriber to receive notifications:

aws sns subscribe \
    --topic-arn arn:aws:sns:us-east-1:123456789012:DirectoryMonitoring-MyDirectory \
    --protocol email \
    --notification-endpoint your-email@example.com \
    --region us-east-1

Check your email and confirm the subscription.

Step 3: Register the topic with your directory

aws ds register-event-topic \
    --directory-id d-1234567890 \
    --topic-name DirectoryMonitoring-MyDirectory \
    --region us-east-1

Replace:

• d-1234567890 with your actual directory ID (format: d- followed by 10 hexadecimal characters)
• DirectoryMonitoring-MyDirectory with your SNS topic name

List your directories

To find your directory ID:

aws ds describe-directories --region us-east-1

CloudFormation (optional)

This CloudFormation template creates an SNS topic with an email subscription and registers it with a Directory Service directory.

AWSTemplateFormatVersion: '2010-09-09'
Description: Enable Directory Service SNS notifications

Parameters:
  DirectoryId:
    Type: String
    Description: The Directory Service directory ID (e.g., d-1234567890)
    AllowedPattern: ^d-[0-9a-f]{10}$
  NotificationEmail:
    Type: String
    Description: Email address to receive directory status notifications

Resources:
  DirectoryNotificationTopic:
    Type: AWS::SNS::Topic
    Properties:
      TopicName: !Sub 'DirectoryMonitoring-${DirectoryId}'
      DisplayName: DirMon

  EmailSubscription:
    Type: AWS::SNS::Subscription
    Properties:
      Protocol: email
      Endpoint: !Ref NotificationEmail
      TopicArn: !Ref DirectoryNotificationTopic

Outputs:
  TopicArn:
    Description: SNS Topic ARN for directory notifications
    Value: !Ref DirectoryNotificationTopic
  TopicName:
    Description: SNS Topic name to register with Directory Service
    Value: !GetAtt DirectoryNotificationTopic.TopicName

Important: CloudFormation does not natively support AWS::DirectoryService::EventTopicRegistration. After deploying this stack, you must manually register the topic using the AWS CLI:

aws ds register-event-topic \
    --directory-id <your-directory-id> \
    --topic-name DirectoryMonitoring-<your-directory-id> \
    --region us-east-1

Terraform (optional)

This Terraform configuration creates an SNS topic and registers it with a Directory Service directory.

variable "directory_id" {
  description = "The Directory Service directory ID (e.g., d-1234567890)"
  type        = string

  validation {
    condition     = can(regex("^d-[0-9a-f]{10}$", var.directory_id))
    error_message = "Directory ID must match pattern d-XXXXXXXXXX."
  }
}

variable "notification_email" {
  description = "Email address to receive directory status notifications"
  type        = string
}

resource "aws_sns_topic" "directory_notifications" {
  name         = "DirectoryMonitoring-${var.directory_id}"
  display_name = "DirMon"
}

resource "aws_sns_topic_subscription" "email" {
  topic_arn = aws_sns_topic.directory_notifications.arn
  protocol  = "email"
  endpoint  = var.notification_email
}

resource "aws_directory_service_log_subscription" "example" {
  # Note: Terraform uses aws_directory_service_log_subscription for CloudWatch logs,
  # but SNS event topic registration requires the AWS CLI or API.
  # Use a null_resource with local-exec as a workaround.
}

# Register the SNS topic with Directory Service
resource "null_resource" "register_event_topic" {
  provisioner "local-exec" {
    command = <<-EOT
      aws ds register-event-topic \
        --directory-id ${var.directory_id} \
        --topic-name ${aws_sns_topic.directory_notifications.name} \
        --region us-east-1
    EOT
  }

  depends_on = [aws_sns_topic.directory_notifications]

  triggers = {
    directory_id = var.directory_id
    topic_name   = aws_sns_topic.directory_notifications.name
  }
}

output "sns_topic_arn" {
  description = "ARN of the SNS topic for directory notifications"
  value       = aws_sns_topic.directory_notifications.arn
}

Note: The AWS Terraform provider does not have a native resource for Directory Service event topic registration. This example uses a null_resource with local-exec as a workaround. Ensure the AWS CLI is available in your Terraform execution environment.

Verification

After configuring notifications, verify they are working:

1. In the AWS Console:

   • Go to Directory Service > Directories
   • Click your directory ID
   • Select the Maintenance tab
   • Under Directory monitoring, confirm your SNS topic is listed with status Registered

2. Check your email:

   • If you added an email subscription, confirm you received and accepted the SNS subscription confirmation

CLI verification commands

Check if SNS notifications are registered for your directory:

aws ds describe-event-topics \
    --directory-id d-1234567890 \
    --region us-east-1

Expected output when properly configured:

{
    "EventTopics": [
        {
            "DirectoryId": "d-1234567890",
            "TopicName": "DirectoryMonitoring-MyDirectory",
            "TopicArn": "arn:aws:sns:us-east-1:123456789012:DirectoryMonitoring-MyDirectory",
            "CreatedDateTime": "2024-01-15T10:30:00.000Z",
            "Status": "Registered"
        }
    ]
}

The Status should be Registered. If it shows Topic not found or Failed, verify the SNS topic exists and is in the same region as the directory.

To list all directories and their notification status:

aws ds describe-event-topics --region us-east-1

Additional Resources

• AWS Documentation: Enable Directory Status Notifications
• AWS Documentation: Directory Service Troubleshooting
• AWS Documentation: Amazon SNS Getting Started

Notes

• Regional configuration: If you use multi-region replication for your directory, you must configure notifications separately in each region.
• Topic naming convention: If your IAM user only has the DirectoryServiceFullAccess policy, the SNS topic name must start with DirectoryMonitoring.
• Multiple recipients: You can add multiple subscribers to the same SNS topic through the SNS console, including email addresses, SMS numbers, SQS queues, Lambda functions, and HTTP endpoints.
• No email confirmation = no notifications: Email subscribers must confirm their subscription before they receive notifications. Check spam folders if the confirmation email doesn't arrive.
• Status changes only: Notifications are sent when the directory status changes (Active to Impaired, or Impaired to Active). They do not provide continuous health metrics; use CloudWatch for detailed monitoring.