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

| 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.

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.. | |

Query to get the access tokens 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 token

Users can call this endpoint to finish the session.

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 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.

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

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