Skip to content

Architecture

Jump to bottom
Danny Jung edited this page May 12, 2024 · 2 revisions
    1. Application Architecture
    2. User Flow
    3. Design Patterns

Intro

This section will be split into two parts.

Section 1: For the developer who wants to use Authorization and authentication

Section 2: For the developer who wants to know how Authorization and authentication is implemented

Prerequisites:

The following assumptions are made, otherwise this documentation will be huge.

To understand section 1:

  • Understand JWT tokens and how they're used
  • Understanding of the parts of a HTTP request, specifically what headers are and how authentication works in Http Requests as bearer tokens.
  • Understand difference between Authorization / Authentication
  • Understanding of FSAE's user models. Specfically roles and the activate flag

To understand section 2:

  • Understanding of dependency injection
  • Understanding differences between services, repositories, models, datasources
  • Understanding of backend systems and how authorization and authentication works at a high level. EG Auth Strategies
  • Understanding of the Loopback4 architecture, inbuilt Authentication library, inbuilt Authorization library
  • Understanding of how JWT tokens work and store user data

Section 1 - For the developer who wants to use Authorization and authentication:

1.1 Authentication :

Do you want endpoint require a user to be logged in first? This section is for you.

Do you want an endpoint to only be accessible to a certain role? Read this section, then refer to sect 1.2 authorization.

1.1.1 Getting JWT access tokens:

To get an access token, use one of login endpoints in login.controller.ts. If the correct credentials are sent via HTTP POST a response similar is given

{
  "userId": "1",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEiLCJyb2xlIjoiYWRtaW4iLCJhY3RpdmF0ZWQiOmZhbHNlLCJpYXQiOjE3MjAyNDA5NjMsImV4cCI6MTcyMDMyNzM2M30.t6bdkZesragtj6N7N83SaN6W3YDlQdMphh5qdhiTHrk"
}

This JWT token can be decoded with websites such at these link. For every endpoint that requires authentication, this JWT token must be passed part of the 'Authentication header' as a bearer token'. What this means.

The HTTP request, headers are a key, value pair. To use authentication

Key/Name of header is `authentication`
The value of the header is `Bearer <tokenHere>`

This is a standard, widely used across the web, so it will be similar to many other web apps out there.

1.1.2 Protecting your endpoint:

Add @authenticate('fsae-jwt') decorator. This endpoint now requires a JWT bearer token as part of the Authorization header to be accessed.

It is important to note, this endpoint still allows user accounts that have the 'activate' flag set or unset. The sole purpose of authentication is identifying who you are, not what permissions you have.

1.2 Authorization

Authorization requires authentication. Once authentication determines who you are, authorization determines what you can access. Currently authorization is Claim based role authentication using JWT Tokens

The role is stored within the JWT claim, alongside whether your user account is activated or not. (You can see this by decoding a JWT token)

To add authorization to your endpoint add the following decorator. You can modify the allowRoles as you wish.

  @authorize({
    allowedRoles: [FsaeRole.ADMIN, FsaeRole.SPONSOR, FsaeRole.ALUMNI, FsaeRole.ALUMNI],
  })

By default this decorator, will reject users whose activate flag is set to false. This can be bypassed by adding the following scope

  @authorize({
    allowedRoles: [FsaeRole.ADMIN, FsaeRole.SPONSOR, FsaeRole.ALUMNI, FsaeRole.ALUMNI],
    scopes: ['allow-non-activated'],
  })

1.3 Example endpoint calls

A series of example endpoints are defined in ping.controller with different permissions.

// Unprotected endpoint. Anyone can access it
  @get('/ping')
  @response(200, PING_RESPONSE)
  ping(): object {...}
// Protected endpoint. Anyone logged in can access it. Including deactivated users
  @get('/protected-ping')
  @authenticate('fsae-jwt')
// Protected endpoint, that only admins can access, and whose admin account is activated
  @get('/protected-ping/admin-only')
  @authenticate('fsae-jwt')
  @authorize({
    allowedRoles: [FsaeRole.ADMIN],
  })
// Protected endpoint that all users can access, alongside non-activated accounts. 
  @authorize({
    allowedRoles: [FsaeRole.ADMIN, FsaeRole.SPONSOR, FsaeRole.ALUMNI, FsaeRole.ALUMNI],
    scopes: ['allow-non-activated'],
  })

Section 2 - For the developer who wants to know how Authorization and authentication are implemented:

Authorization Technical Log.docx

Clone this wiki locally