# Provide authentication credentials for penetration testing
<a name="provide-testing-credentials"></a>

Provide credentials to enable AWS Security Agent to test authenticated areas of your web applications. Without credentials, the agent can only test publicly accessible pages and APIs.

## Configure authentication credentials
<a name="_configure_authentication_credentials"></a>

1. In the penetration test creation workflow, locate the **Authentication credentials - Optional** section.

1. In the **Credential \$11** section, choose your credential input method:
   +  **Input credentials** - Enter credentials directly. Best for development and testing environments.
   +  **Advanced setting** - Use AWS-native credential management. Recommended for production environments and sensitive credentials.

### Advanced options
<a name="_advanced_options"></a>

If you select **Advanced setting**, you can choose from three credential strategies:
+  **IAM role assumption** - For applications using AWS Cognito or IAM authentication
+  **AWS Secrets Manager** - For secure credential storage with encryption and rotation
+  **Lambda function** - For dynamic credential generation or complex authentication flows

## Input credentials directly
<a name="_input_credentials_directly"></a>

1. Select **Input credentials**.

1. Enter the **User name** and **Password**.

1. In the **Access URL** dropdown, select the URL where these credentials will be used. This must be selected from the list of target endpoints.

1. (Optional) In the **2FA - optional** field, provide a TOTP secret for applications that require two-factor authentication. You can either:
   + Enter the TOTP secret directly (for example, `JBSWY3DPEHPK3PXP`), or enter the full `otpauth://totp/` URI (for example, `otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example`).
   + Click the upload icon to upload a QR code image from your authenticator app setup page. The QR code is scanned locally and the TOTP URI is extracted automatically.

     When a TOTP secret is provided, the agent automatically generates fresh one-time codes and enters them when a 2FA prompt is detected during login.

1. (Optional) Expand **Agent Space login prompt** to provide specific login instructions if your application has a complex authentication flow.

**Important**  
Use test accounts with representative access rather than personal or administrative accounts.

## Use advanced setting
<a name="_use_advanced_setting"></a>

1. Select **Advanced setting**.

1. In the **User access strategy** dropdown, choose one of the following:

### Select available IAM role for agent to assume
<a name="_select_available_iam_role_for_agent_to_assume"></a>

Use this option for applications using AWS Cognito, API Gateway with IAM authentication, or other AWS-native authentication systems. The IAM role must have a trust relationship allowing AWS Security Agent to assume it and permissions to access your application’s authentication system.

### Select static credential from connected AWS Secrets Manager
<a name="provide-testing-credentials-secrets-manager"></a>

Use this option to retrieve credentials securely from AWS Secrets Manager with encryption, rotation, and access auditing.

The IAM role must have `secretsmanager:GetSecretValue` and `secretsmanager:DescribeSecret` permissions.

Use the **Agent Space login prompt** to provide detailed instructions on how to interpret and use the credentials stored in the secret. You may use any format to store your secret, as the agent will dynamically interpret the format using these instructions.

For example, if the agent is to submit a username/password login form at https://example.com/login, you may format your secret as JSON with `username` and `password` fields. If the application requires TOTP-based 2FA, include a `totpSecret` field with either the TOTP secret directly or a full `otpauth://totp/` URI:

```
{
  "username": "test-user",
  "password": "secure-password-here",
  "totpSecret": "JBSWY3DPEHPK3PXP"
}
```

Then, configure the authentication instructions: . Set **Access URL** to `https://example.com` (or any other URL selected from the list of target endpoints). . Enter the following into **Agent Space login prompt**: "Navigate to https://example.com/login and enter the provided username and password into the form."

As another example, if you instead have an API key to be provided in an HTTP header, you may store it as plaintext:

```
"api-key-here"
```

Then, configure the authentication instructions: . Enter the following into **Agent Space login prompt**: "Set the X-API-Key header to the provided API key for all requests."

**Important**  
Only TOTP-based 2FA is supported. SMS, email, push notifications, hardware keys, and OAuth authentication are not supported.

### Select available Lambda function to retrieve credentials dynamically
<a name="_select_available_lambda_function_to_retrieve_credentials_dynamically"></a>

Use this option for complex authentication systems, dynamic credential generation, or integration with external identity providers.

The IAM role must have `lambda:InvokeFunction` permissions and the function must complete within 30 seconds.

Like with Secrets Manager, the agent will dynamically interpret your Lambda function’s output using any login instructions provided in the **Agent Space login prompt**. Refer to [Select static credential from connected AWS Secrets Manager](#provide-testing-credentials-secrets-manager) for examples of how to format the output of your Lambda function and supported authentication types.

## Configure multiple credentials
<a name="_configure_multiple_credentials"></a>

To test different user roles or authentication systems:

1. Click **Add another credential**.

1. Configure the additional credential using either input method.

1. To remove a credential, click **Remove** in the credential section.