Authentication Booster Rocket for AWS

This package is a configurable Booster rocket to add an authentication API based on Cognito to your Booster applications.

• Usage
• Configuration Options
• Outputs
• Operations
  • Sign-up
  • Confirm Sign-up
  • Resend Sign-up Confirmation Code
  • Sign-in
  • Request Passwordless Token
  • Revoke Access Token
  • Refresh Access Token
  • Request Password Reset
  • Change Password

Usage

Install this package as a devDependency in your Booster project (It's a devDependency because it's only used during deployment, so we don't want this code to be uploaded to the project lambdas)

npm install --save-dev @boostercloud/rocket-auth-aws-infrastructure

In your Booster config file, pass a RocketDescriptor array to the AWS Provider initializer configuring the aws authentication rocket:

import { Booster } from '@boostercloud/framework-core'
import { BoosterConfig } from '@boostercloud/framework-types'
import * as AWS from '@boostercloud/framework-provider-aws'


Booster.configure('production', (config: BoosterConfig): void => {
  config.appName = 'my-store'
  config.providerPackage = '@boostercloud/framework-provider-aws'
  config.rockets = [
    {
      packageName: '@boostercloud/rocket-auth-aws-infrastructure',
      parameters: {         
        mode: 'UserPassword'                     
      },
    },
  ]
})

Note:

Make sure that you have defined the suitable roles for your application. Please, check the Official Booster Documentation for more information.

Configuration Options

{
  passwordPolicy?: {                         // Optional, all values are set to true by default.
    minLength?: number,                       // Minimum length, which must be at least 6 characters but fewer than 99 character
    requireDigits: boolean,                   // Require numbers
    requireLowercase: boolean,                // Require lowercase letters
    requireSymbols: boolean,                  // Require special characters
    requireUppercase: boolean                // Require uppercase letters
  }
  mode: 'Passwordless' | 'UserPassword'      // If Passwordless, the user must be a phone number. If UserPassword, the user must be a valid email.
}

Outputs

The auth rocket will expose the following base url outputs:

<appName>.AuthApiURL = https://<httpURL>/production/auth
<appName>.AuthApiIssuer = https://cognito-idp.<app-region>.amazonaws.com/{userPoolId}
<appName>.AuthApiJwksUri = https://cognito-idp.<app-region>.amazonaws.com/{userPoolId}/.well-known/jwks.json

Output	Description
AuthApiURL	Base Api Url which will exposed all auth endpoints.
AuthApiIssuer	The issuer who sign the JWT tokens.
AuthApiJwksUri	Uri with all the public keys used to sign the JWT tokens.

The AuthApiIssuer and AuthApiJwksUri must be used in the tokenVerifier Booster config. More information about JWT Configuration here.

Operations

Sign-up

Users can use this endpoint to register in your application and get a role assigned to them.

Endpoint

POST https://<httpURL>/auth/sign-up

Request body

{
  "username": "string",
  "password": "string",
  "userAttributes": {
    "role": "string"
  }
}

Parameter	Description
username	The username of the user you want to register. It must be an email in UserPassword mode or an phone number in Passwordless mode.
password	The password the user will use to later login into your application and get access tokens. Only in UserPassword mode
userAttributes	Here you can specify the attributes of your user. These are: -role: A unique role this user will have. You can only specify here a role where the signUpOptions property is not empty.

Response

{
  "id": "cb61c0a4-8f85-4774-88a9-448ce6321eea",
  "username": "+34999999999",
  "userAttributes": {
    "role": "User"
  }
}

Errors

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error.

Example of an account with the given username which already exists:

{
  "error": {
    "type": "UsernameExistsException",
    "message": "An account with the given phone_number already exists."
  }
}

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error.

Confirm Sign-up

Whenever a User signs up with their phone number in Passwordless mode, an SMS message will be sent with a confirmation code. If you're using a UserPassword mode an email with a confirmation link will be sent. They will need to provide this code to confirm registation by calling thesign-up/confirm endpoint

Endpoint

POST https://<httpURL>/auth/sign-up/confirm

Request body

{
  "confirmationCode": "string",
  "username": "string"
}

Parameter	Description
confirmationCode	The confirmation code received in the SMS message.
username	The username of the user you want to sign in. They must have previously signed up.

Response

{
  "message": "The username: +34999999999 has been confirmed."
}

Errors

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error. Common errors would be like submitting an expired confirmation code or a non valid one.

Example of an invalid verification code:

{
  "error": {
    "type": "CodeMismatchException",
    "message": "Invalid verification code provided, please try again."
  }
}

Resend Sign-up Confirmation Code

If for some reason the confirmation code never reaches your email, or your phone via SMS, you can ask the API to resend a new one.

Endpoint

POST https://<httpURL>/auth/sign-up/resend-code

Request body

{
  "username": "string"
}

Parameter	Description
username	The username of the user you want to sign in. They must have previously signed up.

Response

{
  "message": "The confirmation code to activate your account has been sent to: +34999999999."
}

Errors

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error. Common errors would be like submitting an expired confirmation code or a non valid one.

Sign-in

This endpoint creates a session for an already registered user, returning an access token that can be used to access role-protected resources

Endpoint

POST https://<httpURL>/auth/sign-in

Request body

{
  "username": "string",
  "password": "string"
}

Parameter	Description
username	The username of the user you want to sign in. They must have previously signed up.
password	The password used to sign up the user. Only in UserPassword mode

Response

UserPassword:

{
  "accessToken": "string",
  "expiresIn": "string",
  "refreshToken": "string",
  "tokenType": "string"
}

Parameter	Description
accessToken	The token you can use to finish de session.
tokenId	The token you can use to access restricted resources. It must be sent in the Authorization header (prefixed with the tokenType).
expiresIn	The period of time, in seconds, after which the token will expire.
refreshToken	The token you can use to get a new access token after it has expired.
tokenType	The type of token used. It is always Bearer.

Passwordless:

{
  "session": "string",
  "message": "string"
}

Parameter	Description
session	The type of token used. It is always Bearer.
message	Message with the next steps. It is always: Use the session and the code we have sent you via SMS to get your access tokens via POST /token..

Request Passwordless Token

Call this endpoint to get the access token for Passwordless mode:

Endpoint

POST https://<httpURL>/auth/token

Request body

{
  "username": "string",
  "session": "string",
  "confirmationCode": "string"
}

Parameter	Description
username	The phone number of the user you want to sign in. They must have previously signed up.
session	The session obtained in the sign in response.
confirmationCode	The confirmation code received in the SMS message after sign in.

Response

{
  "accessToken": "string",
  "expiresIn": "string",
  "refreshToken": "string",
  "tokenType": "string"
}

Errors

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error.

Example: Login of a user that has not been confirmed

{
  "error": {
    "type": "UserNotConfirmedException",
    "message": "User is not confirmed.."
  }
}

Revoke Access Token

Users can call this endpoint to finish the session before token expires.

Endpoint

POST https://<httpURL>/auth/token/revoke

Request body

{
  "accessToken": "string"
}

Parameter	Description
accessToken	The access token you get in the sign-in process.

Response

{
  "message": "string"
}

Parameter	Description
message	Message with sign out confirmation. It is always: Signed out

Errors

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error.

Example: Invalid access token specified

{
  "error": {
    "type": "NotAuthorizedException",
    "message": "Invalid Access Token"
  }
}

Refresh Access Token

Users can call this endpoint to refresh the access token.

Endpoint

POST https://<httpURL>/auth/token/refresh

Request body

Refresh-token request body

{
  "refreshToken": "string"
}

Parameter	Description
refreshToken	The token you can use to get a new access token after it has expired.

Response

{
  "accessToken": "string",
  "expiresIn": "string",
  "refreshToken": "string",
  "tokenType": "string"
}

Errors

Refresh token error response body example: Invalid refresh token specified

{
  "error": {
    "type": "NotAuthorizedException",
    "message": "Invalid Refresh Token"
  }
}

You will get a HTTP status code different from 2XX and a body with a message telling you the reason of the error.

Request Password Reset

In case the password is forgotten, users can initiate the password change process through this endpoint.

Endpoint

POST https://<httpURL>/auth/password/forgot

Request body

{
  "username": "string"
}

Parameter	Description
username	The username of the user whose password you want to change. They must have previously signed up.

Response

{
  "message": "string"
}

Parameter	Description
message	Confirmation message. It is always: "The confirmation code to change your password has been sent to: [USER_EMAIL]."

Errors

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error.

Example: User not found.

{
  "error": {
    "type": "UserNotFoundException",
    "message": "Username/client id combination not found."
  }
}

Change Password

Using the code obtained from the email sent by the forgot password endpoint, users can change their password.

Endpoint

POST https://<httpURL>/auth/password/change

Request body

{
  "username": "string",
  "password": "string",
  "confirmationCode": "string"
}

Parameter	Description
username	The username of the user you want to change the password. They must have signed up previously.
password	The new password for sign in.
confirmationCode	The confirmation code received in the user's email.

Response

{
  "message": "string"
}

Parameter	Description
message	Confirmation Message. It is always: "Your password has been successfully changed."

Errors

You will get an HTTP status code different from 2XX and a body with a message telling you the reason of the error.

Example: Confirmation Code is missing.

{
  "error": {
    "type": "MissingRequiredParameter",
    "message": "Missing required key 'ConfirmationCode' in params"
  }
}