[New Feature] I Tried Specifying Password Hashes in an Amazon Cognito CSV Import
This page has been translated by machine translation. View original
Introduction
The Amazon Cognito user import feature has been updated, and you can now include password hashes in the CSV file when importing. With the conventional CSV import, the user status after import became RESET_REQUIRED, and a password reset was mandatory on first sign-in. When you import with password hashes included in the CSV, the user status becomes CONFIRMED, and users can sign in immediately with their existing passwords.
In this article, I covered two of the four supported algorithms, bcrypt and PBKDF2_SHA256, set password hashes in a CSV, imported them, and confirmed that authentication works with the existing passwords.
Verification Details
Verification Environment
| Item | Value |
|---|---|
| Region | ap-northeast-1 |
| User pool | username-attributes: email, email verification enabled |
| App client | No secret, ALLOW_USER_PASSWORD_AUTH / ALLOW_ADMIN_USER_PASSWORD_AUTH enabled |
| AWS CLI | v2.35.24 |
| boto3 / botocore | 1.43.49 |
| Algorithms verified | BCRYPT, PBKDF2_SHA256 |
Preparation
I created a user pool that uses email addresses as the sign-in attribute and has email verification enabled.
aws cognito-idp create-user-pool \
--pool-name password-hash-import-test \
--username-attributes email \
--auto-verified-attributes email \
--policies '{"PasswordPolicy":{"MinimumLength":8,"RequireUppercase":true,"RequireLowercase":true,"RequireNumbers":true,"RequireSymbols":true}}' \
--region ap-northeast-1
{
"UserPool": {
"Id": "ap-northeast-1_XXXXXXXXX",
"Name": "password-hash-import-test",
"UsernameAttributes": ["email"],
"AutoVerifiedAttributes": ["email"]
}
}
Because SRP authentication cannot be used for users right after import, you need to enable an authentication flow that sends the password directly. I created an app client with ALLOW_USER_PASSWORD_AUTH and ALLOW_ADMIN_USER_PASSWORD_AUTH enabled. No secret is issued.
aws cognito-idp create-user-pool-client \
--user-pool-id ap-northeast-1_XXXXXXXXX \
--client-name password-hash-import-client \
--no-generate-secret \
--explicit-auth-flows ALLOW_USER_PASSWORD_AUTH ALLOW_ADMIN_USER_PASSWORD_AUTH ALLOW_REFRESH_TOKEN_AUTH \
--region ap-northeast-1
{
"UserPoolClient": {
"UserPoolId": "ap-northeast-1_XXXXXXXXX",
"ClientId": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
"ClientName": "password-hash-import-client",
"ExplicitAuthFlows": [
"ALLOW_USER_PASSWORD_AUTH",
"ALLOW_ADMIN_USER_PASSWORD_AUTH",
"ALLOW_REFRESH_TOKEN_AUTH"
]
}
}
I created an IAM role that the import job uses to write to CloudWatch Logs. The trust policy allows assumption by cognito-idp.amazonaws.com, and the role is granted permission to write to CloudWatch Logs.
cat > trust-policy.json <<'EOF'
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "cognito-idp.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}
EOF
aws iam create-role \
--role-name cognito-import-cloudwatch-role \
--assume-role-policy-document file://trust-policy.json
aws iam put-role-policy \
--role-name cognito-import-cloudwatch-role \
--policy-name cognito-import-logs \
--policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":["logs:CreateLogGroup","logs:CreateLogStream","logs:DescribeLogStreams","logs:PutLogEvents"],"Resource":"arn:aws:logs:*:*:*"}]}'
{
"Role": {
"RoleName": "cognito-import-cloudwatch-role",
"Arn": "arn:aws:iam::123456789012:role/cognito-import-cloudwatch-role"
}
}
bcrypt Hash Import
First, I generated a hash of the test password TestPassword123! with a bcrypt cost of 10. The maximum cost that Cognito accepts is 10.
import bcrypt
password = b'TestPassword123!'
salt = bcrypt.gensalt(rounds=10)
hashed = bcrypt.hashpw(password, salt)
print(hashed.decode())
# Example output: $2b$10$6utAl7aqnqX9VP4tyUsY2Ol9eciwln7Wx71GFPBy1I1P8xpKgfUu6
The CSV header must be exactly what is obtained from get-csv-header for the target user pool.
Result of running get-csv-header
aws cognito-idp get-csv-header \
--user-pool-id ap-northeast-1_XXXXXXXXX \
--region ap-northeast-1
{
"UserPoolId": "ap-northeast-1_XXXXXXXXX",
"CSVHeader": [
"profile", "address", "birthdate", "gender", "preferred_username",
"updated_at", "website", "picture", "phone_number", "phone_number_verified",
"zoneinfo", "locale", "email", "email_verified", "given_name", "family_name",
"middle_name", "name", "nickname", "cognito:mfa_enabled", "cognito:username",
"password_hash"
]
}
The password_hash column is included at the end. I included all the retrieved columns in the header and set the generated hash in password_hash. For a pool with username-attributes: email, set the email address in cognito:username as well. For details on the CSV format, see the official documentation.
profile,address,birthdate,gender,preferred_username,updated_at,website,picture,phone_number,phone_number_verified,zoneinfo,locale,email,email_verified,given_name,family_name,middle_name,name,nickname,cognito:mfa_enabled,cognito:username,password_hash
,,,,,,,,,,,,bcrypt-user-01@example.com,TRUE,,,,,,,bcrypt-user-01@example.com,$2b$10$6utAl7aqnqX9VP4tyUsY2Ol9eciwln7Wx71GFPBy1I1P8xpKgfUu6
,,,,,,,,,,,,bcrypt-user-02@example.com,TRUE,,,,,,,bcrypt-user-02@example.com,$2b$10$6utAl7aqnqX9VP4tyUsY2Ol9eciwln7Wx71GFPBy1I1P8xpKgfUu6
In CreateUserImportJob, specify BCRYPT in the new PasswordHashingAlgorithm parameter. The AWS CLI v2.35.24 and boto3 / botocore 1.43.49 at the time of verification did not support this parameter, so I called the HTTP API directly using botocore's SigV4 signing. The following is the full code I ran.
import json
import urllib.request
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
from botocore.session import Session
region = 'ap-northeast-1'
service = 'cognito-idp'
endpoint = f'https://cognito-idp.{region}.amazonaws.com/'
session = Session()
credentials = session.get_credentials().get_frozen_credentials()
payload = json.dumps({
'JobName': 'bcrypt-import-test-3',
'UserPoolId': 'ap-northeast-1_XXXXXXXXX',
'CloudWatchLogsRoleArn': 'arn:aws:iam::123456789012:role/cognito-import-cloudwatch-role',
'PasswordHashingAlgorithm': 'BCRYPT',
})
headers = {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'AWSCognitoIdentityProviderService.CreateUserImportJob',
}
request = AWSRequest(method='POST', url=endpoint, data=payload, headers=headers)
SigV4Auth(credentials, service, region).add_auth(request)
req = urllib.request.Request(
endpoint,
data=payload.encode('utf-8'),
headers=dict(request.headers),
method='POST',
)
with urllib.request.urlopen(req) as response:
print(response.read().decode())
The response contained the pre-signed URL to which the CSV is uploaded and PasswordHashingAlgorithm. I confirmed that the specified BCRYPT was returned.
CreateUserImportJob response
{
"UserImportJob": {
"JobName": "bcrypt-import-test-3",
"JobId": "import-XXXXXXXXXX",
"UserPoolId": "ap-northeast-1_XXXXXXXXX",
"PreSignedUrl": "https://cognito-idp-user-import-pdx.s3.us-west-2.amazonaws.com/<masked>",
"Status": "Created",
"CloudWatchLogsRoleArn": "arn:aws:iam::123456789012:role/cognito-import-cloudwatch-role",
"ImportedUsers": 0,
"SkippedUsers": 0,
"FailedUsers": 0,
"PasswordHashingAlgorithm": "BCRYPT"
}
}
I uploaded the CSV to the returned pre-signed URL.
curl -sS -o /dev/null -w '%{http_code}\n' \
--request PUT \
--upload-file bcrypt-users.csv \
'https://cognito-idp-user-import-pdx.s3.us-west-2.amazonaws.com/<masked>'
200
After the upload, I started the job with the AWS CLI.
aws cognito-idp start-user-import-job \
--user-pool-id ap-northeast-1_XXXXXXXXX \
--job-id import-XXXXXXXXXX \
--region ap-northeast-1
{
"UserImportJob": {
"JobId": "import-XXXXXXXXXX",
"Status": "Pending",
"PasswordHashingAlgorithm": "BCRYPT"
}
}
Checking the job after completion, 2 users had been imported successfully.
aws cognito-idp describe-user-import-job \
--user-pool-id ap-northeast-1_XXXXXXXXX \
--job-id import-XXXXXXXXXX \
--region ap-northeast-1
{
"UserImportJob": {
"JobName": "bcrypt-import-test-3",
"JobId": "import-XXXXXXXXXX",
"Status": "Succeeded",
"ImportedUsers": 2,
"SkippedUsers": 0,
"FailedUsers": 0,
"PasswordHashingAlgorithm": "BCRYPT",
"CompletionMessage": "Import Job Completed Successfully."
}
}
The UserStatus of the imported users was CONFIRMED.
aws cognito-idp admin-get-user \
--user-pool-id ap-northeast-1_XXXXXXXXX \
--username bcrypt-user-01@example.com \
--region ap-northeast-1
{
"Username": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"UserStatus": "CONFIRMED",
"Enabled": true,
"UserAttributes": [
{"Name": "email", "Value": "bcrypt-user-01@example.com"},
{"Name": "email_verified", "Value": "true"}
]
}
Running ADMIN_USER_PASSWORD_AUTH with the password used before the import returned tokens.
aws cognito-idp admin-initiate-auth \
--user-pool-id ap-northeast-1_XXXXXXXXX \
--client-id xxxxxxxxxxxxxxxxxxxxxxxxxx \
--auth-flow ADMIN_USER_PASSWORD_AUTH \
--auth-parameters USERNAME=bcrypt-user-01@example.com,PASSWORD=TestPassword123! \
--region ap-northeast-1
{
"AuthenticationResult": {
"AccessToken": "<masked>",
"ExpiresIn": 3600,
"TokenType": "Bearer",
"RefreshToken": "<masked>",
"IdToken": "<masked>"
},
"ChallengeParameters": {}
}
With an incorrect password, NotAuthorizedException was returned.
aws cognito-idp admin-initiate-auth \
--user-pool-id ap-northeast-1_XXXXXXXXX \
--client-id xxxxxxxxxxxxxxxxxxxxxxxxxx \
--auth-flow ADMIN_USER_PASSWORD_AUTH \
--auth-parameters USERNAME=bcrypt-user-01@example.com,PASSWORD=WrongPassword456! \
--region ap-northeast-1
An error occurred (NotAuthorizedException) when calling the AdminInitiateAuth operation: Incorrect username or password.
PBKDF2_SHA256 Hash Import
I verified the same flow with PBKDF2_SHA256. I set the iteration count to the upper limit of 600000 and generated the hash in the following format. The format Cognito accepts is $pbkdf2-sha256$iterations$base64salt$base64hash. In this verification, the import succeeded with the base64 padding (=) removed.
import hashlib, base64, os
password = b'TestPassword123!'
salt = os.urandom(16)
iterations = 600000
dk = hashlib.pbkdf2_hmac('sha256', password, salt, iterations)
salt_b64 = base64.b64encode(salt).rstrip(b'=').decode()
hash_b64 = base64.b64encode(dk).rstrip(b'=').decode()
hash_str = f"$pbkdf2-sha256${iterations}${salt_b64}${hash_b64}"
print(hash_str)
# Example output: $pbkdf2-sha256$600000$dFmpDGYWnTMuSn2wC3qo7Q$+1ITLXTq5iiV2SbQQ6loZ0DHz21ZktaFJMNemioCfcE
When creating the import job, specify PBKDF2_SHA256 in PasswordHashingAlgorithm.
payload = json.dumps({
'JobName': 'pbkdf2-import-test',
'UserPoolId': 'ap-northeast-1_XXXXXXXXX',
'CloudWatchLogsRoleArn': 'arn:aws:iam::123456789012:role/cognito-import-cloudwatch-role',
'PasswordHashingAlgorithm': 'PBKDF2_SHA256',
})
From the CSV upload to the authentication test, I followed the same steps as for bcrypt.
| Verification item | bcrypt | PBKDF2_SHA256 |
|---|---|---|
| Import job Status | Succeeded | Succeeded |
| ImportedUsers | 2 | 2 |
| FailedUsers | 0 | 0 |
| User UserStatus | CONFIRMED | CONFIRMED |
| Authentication with correct password | SUCCESS (tokens obtained) | SUCCESS (tokens obtained) |
| Authentication with incorrect password | NotAuthorizedException | NotAuthorizedException |
| PasswordHashingAlgorithm in response | BCRYPT | PBKDF2_SHA256 |
Notes and Tips
-
The AWS CLI / boto3 at the time of verification do not support
PasswordHashingAlgorithm
The AWS CLI v2.35.24 and boto3 / botocore 1.43.49 that I used at the time of verification (2026-07-16) did not include the input model forPasswordHashingAlgorithm. Specifying it results in the following error.ParamValidationError: Parameter validation failed: Unknown parameter in input: "PasswordHashingAlgorithm", must be one of: JobName, UserPoolId, CloudWatchLogsRoleArnIn this verification, I called the HTTP API directly using botocore's
SigV4Auth. Depending on the CLI / SDK version you use, it may be possible to specify it as an official parameter. -
The CSV header needs all the columns obtained from
get-csv-header
If you use a CSV narrowed down to only the necessary attributes, the import fails due to a header mismatch.The header in the CSV file does not match the expected headers.Include all the columns returned by
get-csv-headerin the header, and leave unnecessary values blank. -
For pools with
username-attributes: email, specify the email address incognito:username
If you set something other than an email address incognito:usernamewith this pool configuration, the import fails.Username should be an email.Set an email address that is consistent with the user pool's sign-in attribute in
cognito:username. -
SRP authentication cannot be used right after import
If you useUSER_SRP_AUTHbefore the first sign-in, authentication fails.An error occurred (NotAuthorizedException) when calling the InitiateAuth operation: Incorrect username or password.Use
USER_PASSWORD_AUTHorADMIN_USER_PASSWORD_AUTHfor the first sign-in. After the first sign-in, SRP authentication also becomes available.
Supported Algorithms and Parameter Limits
In addition to BCRYPT and PBKDF2_SHA256, which I verified on actual hardware, SCRYPT and ARGON2ID are also supported. The formats and parameter limits are described in the official documentation.
| Algorithm | Format | Parameter limits |
|---|---|---|
| BCRYPT | $2<a/b/x/y>$[cost]$[22-char salt][31-char hash] |
cost ≤ 10 |
| SCRYPT | N$r$p$hexSalt$hexHash |
N ≤ 65536, r ≤ 8, p ≤ 1 |
| ARGON2ID | $argon2id$v=N$m=M,t=T,p=P$salt$hash |
m ≤ 19456, t ≤ 2, p ≤ 1 |
| PBKDF2_SHA256 | $pbkdf2-sha256$iterations$salt$hash |
iterations ≤ 600000 |
If the hashes in the source system do not match a supported algorithm or format, or were generated with parameters exceeding these limits, they cannot be imported, so you need to check in advance.
Summary
With Amazon Cognito's CSV import, you can now specify password hashes. When I verified with two algorithms, bcrypt and PBKDF2_SHA256, both allowed users to be imported as CONFIRMED, and authentication with the pre-import passwords succeeded.
As long as the hashes satisfy the supported algorithms, formats, and parameter limits, you can migrate from an existing system to Cognito without requiring all users to reset their passwords at once.
However, the scope of this feature is "improving migration from other systems to Cognito." There is still no means of exporting password hashes from Cognito. Therefore, portability, such as migrating again to another service after migration or performing backup/restore that includes password hashes, is not guaranteed.
When adopting Cognito as a user authentication platform, I recommend evaluating not only the import feature but also non-functional requirements such as API execution rate limits.
