Crate aws_cognito_srp

Expand description

§AWS Cognito SRP

A Rust implementation of the Secure Remote Password (SRP) protocol for AWS Cognito.

This includes helpers for User (USER_SRP_AUTH / PASSWORD_VERIFIER) and Device (DEVICE_SRP_AUTH / DEVICE_PASSWORD_VERIFIER) authentication flows, as well as the ConfirmDevice flow.

§Usage

[dependencies]
aws-cognito-srp = "0.2.3"

§User authentication

The authentication flow is described in detail the AWS Cognito documentation.

When performing the SRP authentication flow, the correct parameters can be generated for the InitiateAuth request, when using the USER_SRP_AUTH flow type, and the subsequent RespondToAuthChallenge request when the PASSWORD_VERIFIER challenge is issued.

use aws_cognito_srp::{UserAuthenticationParameters, SrpClient, SrpError, User, VerificationParameters};

let client_id = "";

// Optional: If your App client is configured with a client secret, AWS Cognito will require that
// a secret is provided during the authentication flow (which requires the client secret).
//
// If your App client does not have a client secret, you can omit this parameter.
//
// https://docs.aws.amazon.com/cognito/latest/developerguide/signing-up-users-in-your-app.html#cognito-user-pools-computing-secret-hash
let client_secret = Some("");

let user = User::new(
     // The ID of the AWS Cognito User Pool the user is registered with.
     "<pool id>",

     // The credentials of the user.
     "<username>",
     "<password>"
);

let client = SrpClient::new(user, client_id, client_secret);

// Part 1: Generate the auth parameters for the initial `InitiateAuth` request
let UserAuthenticationParameters {
    a, // SRP_A
    username, // USERNAME
} = client.get_auth_parameters();

let secret_hash = client.get_secret_hash(); // SECRET_HASH (if required)

// Part 2: Generate the challenge response parameters for the `PASSWORD_VERIFIER` challenge issued
// by Cognito in response to the `InitiateAuth` request.
let VerificationParameters {
    password_claim_secret_block, // PASSWORD_CLAIM_SECRET_BLOCK
    password_claim_signature, // PASSWORD_CLAIM_SIGNATURE
    timestamp // TIMESTAMP
} = client.verify(
    "SECRET_BLOCK_FROM_INITIATE_AUTH_RESPONSE",
    "USER_ID_FOR_SRP_FROM_INITIATE_AUTH_RESPONSE",
    "SALT_FROM_INITIATE_AUTH_RESPONSE",
    "SRP_B_FROM_INITIATE_AUTH_RESPONSE"
)?;

§Device authentication

The authentication flow is described in detail the AWS Cognito documentation.

When performing the SRP authentication flow, if a DEVICE_KEY is provided, AWS Cognito will prompt for device authentication.

The correct SRP parameters can be generated for the two RespondToAuthChallenge requests needed when the DEVICE_SRP_AUTH and DEVICE_PASSWORD_VERIFIER challenges are issued.

use aws_cognito_srp::{DeviceAuthenticationParameters, TrackedDevice, SrpClient, SrpError, User, VerificationParameters};

let client_id = "";

// Optional: If your App client is configured with a client secret, AWS Cognito will require that
// a secret is provided during the authentication flow (which requires the client secret).
//
// If your App client does not have a client secret, you can omit this parameter.
//
// https://docs.aws.amazon.com/cognito/latest/developerguide/signing-up-users-in-your-app.html#cognito-user-pools-computing-secret-hash
let client_secret = Some("");

let tracked_device = TrackedDevice::new(
     // The ID of the AWS Cognito User Pool the user is registered with.
     "<pool id>",

     // The tracked device.
     "<device group key>",
     "<device key>",
     "<device password>"
);

let client = SrpClient::new(tracked_device, client_id, client_secret);

// Part 1: Generate the challenge response parameters for the `RespondToAuthChallenge` request
// when responding to the `DeviceSrpAuth` challenge issued by AWS Cognito.
let DeviceAuthenticationParameters {
    a, // SRP_A
    device_key // DEVICE_KEY
} = client.get_auth_parameters();

let secret_hash = client.get_secret_hash("<username of the owner of the tracked device>"); // SECRET_HASH (if required)

// Part 2: Generate the challenge response parameters for the `DEVICE_PASSWORD_VERIFIER` challenge
// issued by AWS Cognito in response to the `RespondToAuthChallenge` request.
let VerificationParameters {
    password_claim_secret_block, // PASSWORD_CLAIM_SECRET_BLOCK
    password_claim_signature, // PASSWORD_CLAIM_SIGNATURE
    timestamp // TIMESTAMP
} = client.verify(
    "SECRET_BLOCK_FROM_INITIATE_AUTH_RESPONSE",
    "SALT_FROM_INITIATE_AUTH_RESPONSE",
    "SRP_B_FROM_INITIATE_AUTH_RESPONSE"
)?;

§Confirm device

Once a user has been authenticated, if the User Pool is configured to allow device tracking, a ConfirmDevice request can be made.

This request passes in a verifier and salt for a random password generated for the untracked device. And, once confirmed, subsequent logins can use device authentication flow, citing the device key, along with the random password generated here.

use aws_cognito_srp::{TrackedDevice, PasswordVerifierParameters, SrpClient, SrpError, User, UntrackedDevice};

let client_id = "";

// Optional: If your App client is configured with a client secret, AWS Cognito will require that
// a secret is provided during the authentication flow (which requires the client secret).
//
// If your App client does not have a client secret, you can omit this parameter.
//
// https://docs.aws.amazon.com/cognito/latest/developerguide/signing-up-users-in-your-app.html#cognito-user-pools-computing-secret-hash
let client_secret = Some("");

let untracked_device = UntrackedDevice::new(
     // The ID of the AWS Cognito User Pool the user is registered with.
     "<pool id>",

     // The device to be tracked.
     "<device group key>",
     "<device key>"
);

let client = SrpClient::new(untracked_device, client_id, client_secret);

// Part 1: Generate a password, and the verifier parameters (verifier and salt) for the `ConfirmDevice`
// request.
let PasswordVerifierParameters {
    verifier, // PasswordVerifier
    salt, // Salt
    password // The devices password (should be stored to use with device authentication later)
} = client.get_password_verifier();

// Part 2: Once the `ConfirmDevice` request has succeeded, the untracked device can then be converted
// into a tracked device, which can be used for Device authentication later.
let tracked_device = client.take_credentials()
    .into_tracked(&password);

§Contributing

Many of the tests require that an AWS Cognito User Pool, configured with SRP authentication and device tracking, be available to act as a mock server.

The setup of a suitable User Pool is fully automated with Terraform (see the infrastructure folder).

§Set up

In order to setup the test environment, Terraform needs to be installed and AWS credentials need to be configured locally.

Once this is done, running apply should setup the Terraform backend, and the user pool and app client in the correct state:

# Setup state backend
cd infrastructure/state && terraform init && terraform apply

# Setup user pool
cd infrastructure/tests && terraform init --backend-config="./local.config" && terraform apply

After the user pool is set up, multiple environment variables need to be set in a .env file.

The .env file can be created by using .env.example as a template:

cp .env.example .env

§Running tests

The tests can be run with:

cargo test

§Tear down

The test environment can be torn down at any point with:

cd infrastructure/tests && terraform destroy

Structs§

DeviceAuthenticationParameters: The parameters required to respond to the DEVICE_SRP_AUTH challenge for AWS Cognito, when using the USER_SRP_AUTH flow type.
PasswordVerifierParameters: The parameters required to generate a password verifier when confirming a new device in AWS Cognito.
SrpClient: The client for interacting with parameters required for the Secure Remote Password (SRP) protocol.
TrackedDevice: A device which is tracked against a user in the AWS Cognito user pool.
UntrackedDevice: A device which is not yet tracked against a user in the AWS Cognito user pool.
User: A user stored in the AWS Cognito user pool.
UserAuthenticationParameters: The parameters required to initiate an authentication flow with AWS Cognito, when using the USER_SRP_AUTH flow type.
VerificationParameters: The parameters required to respond to the PASSWORD_VERIFIER (if authenticating as a User) and DEVICE_PASSWORD_VERIFIER (if authenticating using a Device) challenges.

Enums§

SrpError: An error occurred while generating parameters for the Secure Remote Password (SRP) protocol.

Traits§

Credentials: The credentials required to authenticate with AWS Cognito using the Secure Remote Password (SRP).