Auth Module

Overview

We are using AWS Cognito to store account credentials and profile information, see

• Cognito for more information

Authentication Flow

Signup as an owner

• This is done by creating a customer using the POST /customers/signup wndpoint
• This can currently only be done by a Hectare admin user
• When a Hectare admin creates a new customer, the endpoint will create
  • An organisation record for the business
  • A User record for the owner
  • A user account for the owner in Cognito used to authenticate
  • Default the owners group to owner
  • Give the owner rwx:* permissions
  • An email will be sent to the user with a temporary password
    • The user must use this temporary password on the POST /customers/login endpoint as the value for password
    • The user can set a new password by adding a property newPassword
    • Finally the username property must have either the email address of the user or be pre-populated with the id query parameter that is contained in the link. The code parameter also contains the temporary password
  • Once all these are sent, the system will
    • Login user with the temporary password
    • Recieve a NEW_PASSWORD_REQUIRED auth challenge
    • Respond to the NEW_PASSWORD_REQUIRED auth challenge using the newPassword value
    • Verify the users email
    • Verify the users phone
    • Return the users JWT tokens and userInfo

Owner create team member

• This is done by creating a user using the POST /customers/organisations/users wndpoint
• Users are created by anyone in the organisation with write user permissions
• Team members are created in the same organisation as the user that is creating them
• When an owner creates a new team member, the endpoint will create
  • A User record for the team member
  • A user account for the team member in Cognito used to authenticate
  • An email will be sent to the user with a confirmation code (usually a six digit number)
    • The user must use this code on the POST /customers/confirm-signup endpoint as the value for confirmationCode
    • Finally the username property must be pre-populated with the id query parameter that is contained in the link.
  • Once all these are sent, the system will
    • Confirm the user account
    • the user can then login with the password that was used on account creation

Authorization

Users are granted a set of roles when their account is created, each roles defines a set of permissions, permissions determine which endpoints the user can access.

We are currently storing authorisation roles on the permissions field of a user and the custom:permissions field in the users Cognito account.

Each permission set on an API endpoint is structured with 3 parts, module:area:permission, for example inv:rec:w grants the user write permission to inventory records in the inventory module. You must specify each component of the permission at the endpoint security level, wildcards are not supported for the endpoint security configuration, for example the following endpoint security configuration indicates the user needs admin access to the org area of the customer service.

security: [
  {
    jwt: ['cus:org:a']
  }
]

There are currently 3 types of permission, but more can be added as needed

1. a admin
2. r read only access
3. w write access

A user's permissions can have wildcards to grant access to groups of endpoints, we support the following wildcard structures...

1. *:*:a admin access to all endpoints
2. inv:*:a admin access to all inventory endpoints
3. cus:*:r read access to all customer endpoints
4. inv:*:w write access to all inventory endpoints

When a user is granted a write access (w) they are automatically granted read access, so there is no need to add both read and write permissions to readonly endpoints, this means most endpoints will by default have just one permission until we need to start supporting more custom roles / permission sets.

Permissions are validated on each request in thecomponents/context/handlers/security.ts handler.

There are 2 special groups of roles which are not available to normal users, Admin and Account Admin. These role groups are used to provide account owner access to services such as logistics & inventory and also admin access to each service. Admin access is only for internal Hectare employees.

When we create a new customer account (inventory for example) the account owner is given the inv-manage role. This role currently has 2 permissions

1. inv:*:w
2. cus:*:w

This therefore gives the account owner write access to all inventory and customer endpoints.

If the same customer is also paying for Logistics we can add the log-manage role to their account which will grant the user two additional permissions (access to all Logistics endpoints and customer endpoints again)

1. log:*:w
2. cus:*:w

Note customer write access is granted regardless of which system is paid for by the customer.

Currently the list of supported role groups is hard coded here (components/context/roles.ts). This is temporary, we will move them to the database and in all likelihood start supporting customer specific roles as the need arises.

We store a list of role id's (see id field on each role in the JSON structure here components/context/roles.ts) against a user, then in the security handler we look up the current set of permissions associated with the roles and use these permissions to authorise requests. We have intentionally separated a user's roles from the permissions so we can add / remove permissions to a role on the fly without needing to modify any user accounts.

Capabilities

• Login
• Logout
• Change Password
• Confirm Signup
• Forgotten Password
• Reset Password
• Admin Set Password
• Admin Confirm Signup

Caveat

• For MVP, the customer self signup is not enabled, and we will only have admin signup of owner users