Triggering Webhooks for AWS Console Login Events

If you want to secure your AWS Console more than usual, you can make use of CloudTrail, EventBridge and a Lambda Function to trigger webhooks to your server whenever a successful login occurs.

...

Below, we'll walk you through how to set up your AWS account so that ConsoleLogin events trigger a webhook to your desired endpoint. This can be especially useful for more advanced teams that want to trigger certain logic when specific users log into your AWS console (e.g. sending SMS or email notifications to IT or Security departments).

Setting up your resources

CloudTrail

CloudTrail is a service from AWS that helps you audit and track events that go on within your account (and it's associated resources). At it's simplest, it writes log files for events.

The first thing we want to do is setup a "Trail" within CloudTrail. It's important to note that this is not region or zone specific, so don't worry about that here.

  1. Head over to CloudTrail
  2. Create a trail
  3. Give it a name. For the purposes of this tutorial, we're going to use:
    00-management-events
  4. This will create an S3 bucket (the name is generated by AWS) with CloudTrail log files.

Great! You're now done with CloudTrail!

Lambda Function

We now want to create a Lambda Function. This function will be used to receive events (from EventBridge), and when it matches our preferred event name (ConsoleLogin), we're then going to "rebound" that event over to our preferred URL endpoint (this is the webhook part).

  1. Visit the Lambda Functions page
  2. Create a Lambda Function (in the us-east-1 region / zone)
  3. Give it a name. For this tutorial, we'll use:
    00-aws-console-login-event-rebounding-function
  4. Choose the runtime: Node.js 20.x
  5. Choose the architecture: x86_64
  6. Press the Create function button
  7. For the Lambda Function code, use the following: https://github.com/zenlogin/aws-lambda-nodejs-rebounding-function/blob/main/index.mjs
  8. After you've pasted that code in, press the Deploy button

Okay! You now have an AWS Lambda Function. When it's triggered (by EventBridge, which we'll get to next), it will check the event name. If it matches what we're looking to capture (namely, AWS console login events), it'll trigger your preferred endpoint URL to be requested (with a POST payload).

One final thing to do here:

  1. In the code you pasted in, you'll want to change line 58 so that it points to your own endpoint (instead of the default one).

EventBridge

This is the last step. It's a bit longer, but relatively straightforward once you grasp it. We're going to create a "rule" within AWS EventBridge This rule will basically say "when a user logs into AWS console, trigger a specific Lambda Function" (the one we just created).

Here we go:

  1. Visit the EventBridge page
  2. Create a rule (in the us-east-1 region / zone)
  3. Give it a "Name". For this tutorial, we'll use:
    00-aws-console-login-events
  4. If you want, give it a "Description" (this is optional)
  5. Choose the "Event bus": default
  6. Choose the "Rule type": Rule with an event pattern
  7. Click the "Next" button
  8. Choose the "Event source": AWS events or EventBridge partner events
  9. Skip over the "Sample event" section
  10. For the "Creation method" choose: Use pattern form
  11. Head down to the "Event pattern" section
  12. Choose the "Event source": AWS services
  13. Choose the "AWS service": AWS Console Sign-in
  14. Choose the "Event type": Sign-in Events
  15. Choose the "Event Type Specification 1": leave as Any user
  16. The "Event pattern" should look as follows: https://416.io/ss/f/d867m8
  17. Click the "Next" button
  18. For the "Target types" choose: AWS service
  19. For the "Select a target" option, choose: Lambda function
  20. Now we want to choose the Lambda Function that we created above: 00-aws-console-login-event-rebounding-function
  21. Click the "Next" button
  22. Click Next (skipping over the Tags area)
  23. Click "Create rule"

Now what?

That's it! Just log into AWS like normal.

Everything should be running smoothly. When a login happens in the AWS console, these three resources should work together to send a POST payload over to your defined endpoint URL.

If you'd like to see a sample of the POST payload that will be "rebounded" (also known as the webhook payload), see the Sample Webhook Payload section below.

If you're having trouble, take a look at the Troubleshooting / Debugging area below, or else, reach out to support@zenlogin.co and we'll do our best to help you out.

Troubleshooting / Debugging

If you're having trouble, the first thing to do is head over to your Lambda Function's CloudWatch / Log Group. In this area, you can see log files generated when your Lambda Function is executed. This can point out any runtime errors.

Another considertion is that when you create a Lambda Function, an associated IAM Role is also created. You can see those details here: https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/roles (you should notice a new IAM Role that references the recently created 00-aws-console-login-event-rebounding-function Lambda Function).

And one gotcha: for this to work, it assumes login events are only happening in the us-east-1 region / zone. There are instances when this doesn't happen, in which case you'll (unfortunately) need to go through this process again for each of your zones. For more information, head over here: https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-aws-console-sign-in-events.html

Sample Webhook Payload 

{
    "event": {
        "version": "0",
        "id": "2da6a4bc-hax7-es2s-57zz-d470a443677d",
        "detail-type": "AWS Console Sign In via CloudTrail",
        "source": "aws.signin",
        "account": "012345678901",
        "time": "2024-05-14T23:56:59Z",
        "region": "us-east-1",
        "resources": [],
        "detail": {
            "eventVersion": "1.08",
            "userIdentity": {
                "type": "Root",
                "principalId": "012345678901",
                "arn": "arn:aws:iam::012345678901:root",
                "accountId": "012345678901",
                "accessKeyId": ""
            },
            "eventTime": "2024-05-14T23:56:59Z",
            "eventSource": "signin.amazonaws.com",
            "eventName": "ConsoleLogin",
            "awsRegion": "global",
            "sourceIPAddress": "224.23.213.30",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
            "requestParameters": null,
            "responseElements": {
                "ConsoleLogin": "Success"
            },
            "additionalEventData": {
                "LoginTo": "https://us-west-2.console.aws.amazon.com/ec2/v2/home?hashArgs=%23Instances%3A&isauthcode=true®ion=us-west-2&state=hashArgsFromTB_us-west-2_b143de86f65714a7",
                "MobileVersion": "No",
                "MFAUsed": "No"
            },
            "eventID": "59ba21zd-0z2z-4d49-a1f2-6e296b9e935e",
            "readOnly": false,
            "eventType": "AwsConsoleSignIn",
            "managementEvent": true,
            "recipientAccountId": "012345678901",
            "eventCategory": "Management",
            "tlsDetails": {
                "tlsVersion": "TLSv1.3",
                "cipherSuite": "TLS_AES_128_GCM_SHA256",
                "clientProvidedHostHeader": "signin.aws.amazon.com"
            }
        }
    }
}



Let your users know you care.

Secure your users accounts with a few lines of code.

Get started for free