Using the ASR API programmatically

If you want to integrate ASR into your own systems for example, a security orchestration platform, a ticketing or ChatOps workflow, or a custom dashboard — and drive remediations from there instead of the Web UI, you can call the Automated Security Response on AWS (ASR) API directly. With the ASR API, you can automate and monitor remediations from tooling you already operate.

To do this, use a machine-to-machine (M2M) client with the OAuth 2.0 client_credentials grant. When the Web UI is enabled, the solution provisions the Amazon Cognito OAuth scope asr-api/full-access. This scope grants the client access to the ASR API. You create the M2M app client yourself after deployment. The solution does not create one, so no machine credential exists until you opt in.

A token with the asr-api/full-access scope has Full Access — the same capability as the solution administrator role, including the ability to manage other users. Treat the credentials with the same care as administrator sign-in credentials.

Prerequisites

Deploy the ASR administrator stack with the Web UI enabled (ShouldDeployWebUI=yes, the default). This creates the Amazon Cognito user pool, the API, and the asr-api/full-access scope. You also need:

• AWS CLI v2 authenticated to the ASR administrator account

• curl and jq for the token and API examples below

Step 1: Create the M2M app client after deployment

Find the user pool id in the administrator stack’s UserPoolId Output, then create a confidential client granted both required OAuth 2.0 scopes — asr-api/api (Amazon API Gateway requires this scope to admit the request to the API) and asr-api/full-access (the backend authorizes Full Access on this scope). A client granted only asr-api/api reaches the API but receives a 403 rejection, because the backend treats it as an unprivileged machine token.

export AWS_REGION="us-east-1"
export STACK_NAME="<ASR-administrator-stack-name>"

export USER_POOL_ID="$(aws cloudformation describe-stacks \
  --stack-name "$STACK_NAME" --region "$AWS_REGION" \
  --query "Stacks[0].Outputs[?OutputKey=='UserPoolId'].OutputValue" --output text)"

CREATE_OUT="$(aws cognito-idp create-user-pool-client \
  --user-pool-id "$USER_POOL_ID" --region "$AWS_REGION" \
  --client-name "ASR-M2M-FullAccess" \
  --generate-secret \
  --allowed-o-auth-flows client_credentials \
  --allowed-o-auth-flows-user-pool-client \
  --allowed-o-auth-scopes "asr-api/api" "asr-api/full-access" \
  --output json)"

export M2M_CLIENT_ID="$(echo "$CREATE_OUT" | jq -r '.UserPoolClient.ClientId')"
export CLIENT_SECRET="$(echo "$CREATE_OUT" | jq -r '.UserPoolClient.ClientSecret')"

The response contains UserPoolClient.ClientId and UserPoolClient.ClientSecret. Cognito shows you the secret value only once. Cognito requires the secret to be generated when the client is created (--generate-secret); there is no command to add a secret to an existing client later.

Step 2: Store the secret in your own secret store

The solution never stores this secret. It is intentionally kept out of AWS CloudFormation outputs and template state. You are responsible for capturing the returned client secret and storing it securely in your own secret store — for example AWS Secrets Manager, AWS Systems Manager Parameter Store (Secure String), or your organization’s vault.

• Store the secret immediately; you cannot retrieve it again later.

• Restrict read access to the integration that needs it.

• Anyone who holds this secret can obtain Full Access tokens for ASR, so guard it accordingly.

Step 3: Retrieve an access token (client_credentials flow)

The token endpoint is derived from the user pool’s hosted domain. Request a token using HTTP Basic auth (client_id:client_secret), the client_credentials grant, and both scopes:

export DOMAIN_PREFIX="$(aws cognito-idp describe-user-pool \
  --user-pool-id "$USER_POOL_ID" --region "$AWS_REGION" \
  --query "UserPool.Domain" --output text)"
export TOKEN_URL="https://${DOMAIN_PREFIX}.auth.${AWS_REGION}.amazoncognito.com/oauth2/token"

export ACCESS_TOKEN="$(curl -s -X POST "$TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "${M2M_CLIENT_ID}:${CLIENT_SECRET}" \
  -d "grant_type=client_credentials&scope=asr-api/api asr-api/full-access" \
  | jq -r '.access_token')"

Access tokens are valid for 1 hour, and the client_credentials grant does not issue a refresh token. Cache and reuse a token for the duration of its validity rather than requesting a new one for every API call. Request a new token shortly before the current one expires — for example, one to two minutes before the 1-hour mark — using the credentials you already hold.

Caching the token keeps your integration within the Cognito token endpoint rate limits and reduces cost. A correctly caching integration needs only about one token request per hour. Requesting a new token for every API call is slower and unnecessarily costly.

Step 4: Call the ASR API

Send the access token as a Authorization: Bearer <access_token> header on any ASR API path. API Gateway validates the token and the asr-api/api scope before the request reaches the backend, and the backend grants Full Access on the asr-api/full-access scope:

# Find the API base URL in the administrator stack's APIEndpoint Output, then
# call an endpoint your integration uses.
curl -s -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  "https://<api-id>.execute-api.${AWS_REGION}.amazonaws.com/prod/<endpoint>"

You do not need additional network or firewall configuration for programmatic callers. The API’s AWS WAF protections already admit authenticated machine clients (non-browser user agents from cloud IP ranges) while blocking abusive traffic. Machine activity is attributed to the client ID in the ASR API logs, and AWS CloudTrail records every token issuance.

Step 5: Rotate or disable the client

Because a secret cannot be added, replaced, or removed on an existing Cognito app client, rotation and disablement operate on the client itself:

• Rotate: create a second M2M client (repeat Step 1 with a different --client-name), migrate your integration to its credentials, confirm it can obtain tokens, then delete the old client.

• Disable: delete the client to immediately revoke machine access.

aws cognito-idp delete-user-pool-client \
  --user-pool-id "$USER_POOL_ID" \
  --client-id "$M2M_CLIENT_ID" \
  --region "$AWS_REGION"

Detect denied machine tokens (optional)

When Amazon CloudWatch alarms are enabled, ASR ships an opt-in alarm (ASR-Cognito-M2MForbidden) on the ASR/M2MForbiddenAuthorization metric. The API AWS Lambda function emits this metric whenever a machine token is denied for lacking the asr-api/full-access scope — a non-zero count signals a misconfigured client or probing. The alarm uses ASR’s shared SNS alarm topic, which has no subscriber by default; subscribe a channel to be notified.

Enable Amazon Cognito logging and threat protection

We recommend that you enable native log delivery and Advanced Security on the ASR user pool for visibility into authentication activity.

Amazon Cognito native log delivery

With this option, you can deliver sign-in and token events to Amazon CloudWatch Logs. In the Amazon Cognito console, open your user pool and choose Logging. Enable log delivery to a CloudWatch Logs log group. Set the log level to ERROR or INFO depending on how much detail you need.

Amazon Cognito records token issuance in AWS CloudTrail. To retain and query these audit records in Amazon CloudWatch Logs, configure a management-event CloudTrail trail in the account that owns the user pool. Configure the trail to deliver logs to a CloudWatch Logs log group. For more information, see Monitoring CloudTrail Log Files with Amazon CloudWatch Logs.

Amazon Cognito Advanced Security and threat protection

With this option, you get compromised-credential detection and risk-based adaptive authentication. In the Amazon Cognito console, open your user pool, choose Advanced Security, and set the mode to Enforced.

Additional cost

If you enable Advanced Security, you incur additional per-authentication charges. For more information about Amazon Cognito pricing, see Amazon Cognito pricing.