@boostercloud/rocket-auth-aws-infrastructure v1.0.7

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

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.provider = Provider([
    {
      packageName: '@boostercloud/rocket-auth-aws-infrastructure',
      parameters: {         
        mode: 'Passwordless'                     
      },
    },
  ])
})

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

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

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"
  }
}

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"
}

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"
}

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"
}

Response

UserPassword:

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

Passwordless:

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

Query to get the access tokens for Passwordless mode:

Endpoint

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

Request body

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

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 token

Users can call this endpoint to finish the session.

Endpoint

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

Request body

{
  "accessToken": "string"
}

Response

{
  "message": "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: Invalid access token specified

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

Refresh 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"
}

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.

Forgot password

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"
}

Response

{
  "message": "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: 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"
}

Response

{
  "message": "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: Confirmation Code is missing.

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