DEV Community: Jay F. Grissom

Web Authentication By the Numbers (Part 2)

Jay F. Grissom — Sun, 28 Nov 2021 03:56:06 +0000

Continued

This article is the second in a three part series. See steps 0 through 3 of Web Authentication By the Numbers (Part 1) to get up to speed.

Video

PassportJS Documentation

The documentation for PassportJS delegates a lot to the individual implementing it. There is enough to get a general overview of what needs to be done but it's pretty abstract. It assumes you already understand authentication concepts.

So let's go ahead and build on the authentication concepts we started in Part 1 by implementing this in a new passport local branch.

This looks long but each section is commented to help tie things all together.

Implementing the PassportJS Local Strategy (Step 4)

This is all the code in one place. Below this are specific thoughts on different key sections (what the section does and why it's there).

import express, { Application, NextFunction, Request, Response } from 'express'
import passport from 'passport'
import { Strategy } from 'passport-local'
import session, { SessionOptions } from 'express-session'
import { flash } from 'express-flash-message'

const app: Application = express()
const port = 3000

// The user "database". I kept this as simple as possible to avoid confusion.
const users: Express.User[] = [
  { id: 1, username: 'admin', password: 'supersecret' }
]

// This Express.User is a custom type/interface that is required by PassportJS if
// you're using Typescript. Making this conform to your user model makes sense
// but that isn't strictly required.
declare global {
  namespace Express {
    interface User {
      id: number
      username?: string
      password?: string
    }
  }
}

// Normally the expression-session object doesn't contain a passport property.
// This extends the default session's data model to allow for passport to
// optionally exist. This is only needed if you're using Typescript.
declare module 'express-session' {
  interface SessionData {
    passport?: Object
  }
}

// Enable parsing of data that is posted from the user login form to the login endpoint.
app.use(express.urlencoded())

// Create a session configuration.
const sessionConfig: SessionOptions = {
  secret: 'Not Really A Secret But It Should Be In Production',
  cookie: {
    httpOnly: true, // Only let the browser modify this, not JS.
    secure: process.env.NODE_ENV === 'production' ? true : false, // In production only set cookies if the TLS is enabled on the connection.
    sameSite: 'strict' // Only send a cookie if the domain matches the browser url.
  }
}

// Enable sessions.
app.use(session(sessionConfig))

// Setup the passport strategy with your custom local logic.
// It's worth noting that the passport-local strategy explicitly expects a
// user/password combo used to authenticate the user.
// These inputs (username/password) could be anything though.
// It's also worth noting that this function doesn't get called if your user
// is already authenticated.
passport.use(
  new Strategy({}, (username: string, password: string, done: Function) => {
    // For this example this wouldn't fail but for completeness this check should be done in a real project.
    if (!users) return done(null, false, { message: 'Database Failure.' })

    // Locate the user in your database with the credentials passed to this function.
    const user = users.find((user) => {
      if (user.username === username && user.password === password) {
        return user
      }
    })

    // Fail if the credentials don't exits.
    const failedAuthMessage = "Username and password combo isn't registered."
    if (!user) return done(null, false, { message: failedAuthMessage })

    // Succeed without and error by passing a user without a name or password.
    const sanitizedUser: Express.User = {
      id: user.id
    }
    return done(null, sanitizedUser)
  })
)

// Takes a user that is passed in from the auth strategy
// and serializes the user into the session.
// It's worth noting that this only gets called after the a user has been authenticated.
passport.serializeUser((user, done) => {
  return done(null, user)
})

// Takes the user passed to it from the session and deserializes it so passport can use it.
// It's worth noting this gets called on every subsequent http request.
passport.deserializeUser((user: Express.User, done: Function) => {
  return done(null, user)
})

// Add passport to the existing session handler.
app.use(passport.initialize())
app.use(passport.session())

// Enable flash messages to display auth errors.
app.use(flash())

// Custom Middleware:
// Apply this to any route to secure it.
const authRequired = (req: Request, res: Response, next: NextFunction) => {
  if (!req.isAuthenticated()) return res.redirect('/login')
  next()
}

// Route handlers below here:
app.get('/', (req: Request, res: Response) => {
  return res.send(`
    Home ${
      req.isAuthenticated()
        ? '| <a href="/logout">Logout</a>'
        : '| <a href="/login">Login</a>'
    } | <a href="/members">Members</a>
    <H1>Home</H1>
    <p>This is a public route. No Authentication is needed.</p>
    SessionID: ${req.session.id} <br/>
    Authenticated: ${req.isAuthenticated() ? 'Yes' : 'No'} <br/>
    User: ${JSON.stringify(req.user)}
  `)
})

// Gathers credentials from the user or redirects them if they are already authenticated.
app.get('/login', async (req: Request, res: Response, next: NextFunction) => {
  const errors = await req.consumeFlash('error')
  if (!req.isAuthenticated()) {
    return res.send(`
      <a href="/">Home</a>
      <H1>Login</H1>
      <form action="/auth" method="post">
        <div>
          <label>Username:</label>
          <input type="text" name="username"/>
        </div>
        <div>
          <label>Password:</label>
          <input type="password" name="password"/>
        </div>
        <div>
          <input type="submit" value="Log In"/>
        </div>
      </form>
      Errors: ${errors} <br/>
      SessionID: ${req.session.id}
    `)
  }
  return res.redirect('/members')
})

// Receives posted data that can be used for authenticating a user.
// Inputs are received here from the form located at /login.
app.post(
  '/auth',
  passport.authenticate('local', {
    successRedirect: '/auth/success',
    failureRedirect: '/login',
    failureFlash: true
  })
)

// NIST digital identity guidelines recommend recreating a session for security reasons.
// https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63b.pdf
// To change the session id you'll need to update the cookie on the client side.
// A response with the new session needs to be sent in order to update the client's cookie.
// You'll need a place for them to land once they've been authenticated to change the session id.
// This is also a good place to make updates to the session in the database if you need to.
app.get('/auth/success', (req: Request, res: Response, next: NextFunction) => {
  const previousSessionData = req.session.passport
  const previousUser = req.user
  req.session.regenerate((err) => {
    if (err) return res.status(500)
    req.session.passport = previousSessionData
    req.user = previousUser
    req.session.save((err) => {
      if (err) return res.status(500)
    })
    return res.send(`
      <a href="/">Home</a> ${
        req.isAuthenticated()
          ? '| <a href="/logout">Logout</a>'
          : '| <a href="/login">Login</a>'
      } | <a href="/members">Members</a>
      <h1>Login Success!</h1>
      <p>Would you like to go to the <a href="/members">Members Area</a>?</p>

      <p>
        A client side redirect here could allow this intermediary step to be skipped.
        Note the new session ID!
      </p>
      SessionID: ${req.session.id} <br/>
      Authenticated: ${req.isAuthenticated() ? 'Yes' : 'No'} <br/>
      User: ${JSON.stringify(req.user)}
    `)
  })
})

// Logs a user out by destroying their session and redirecting them.
app.get('/logout', (req: Request, res: Response, next: NextFunction) => {
  req.session.destroy(() => {
    return res.redirect('/logout/success')
  })
})

app.get(
  '/logout/success',
  (req: Request, res: Response, next: NextFunction) => {
    return res.send(`
      <a href="/">Home</a> ${
        req.isAuthenticated()
          ? '| <a href="/logout">Logout</a>'
          : '| <a href="/login">Login</a>'
      } | <a href="/members">Members</a>
      <h1>Logout Success!</h1>

      SessionID: ${req.session.id} <br/>
      Authenticated: ${req.isAuthenticated() ? 'Yes' : 'No'} <br/>
      User: ${JSON.stringify(req.user)}
    `)
  }
)

// For authenticated users only.
app.get(
  '/members',
  authRequired,
  (req: Request, res: Response, next: NextFunction) => {
    return res.send(`
    <a href="/">Home</a> | <a href="/logout">Logout</a>
    <H1>Members Only!</H1>
    <p>You're Authenticated! 😎</p>
    SessionID: ${req.session.id} <br/>
    User: ${JSON.stringify(req.user)}
  `)
  }
)

// Start the service.
app.listen(port)

Complete System

At this point you've got an entire authentication system setup. You could use this for your own projects. The only things you would really need to change are the database and the presentation of each route handler.

Execution Order Counts

There are quite a few things to note about how this is all setup. The order of execution on some of the code here is important.

One example of the execution order is how the express session and passport session modules are used. The express session has to come first and the passport session must come after express session. If not, the application behaves strangely.

Additionally, when you extend Express matters too and support for most of the middleware must be in place before creating any routes.

Database

This could really be any database. But for the purpose of this article I've made it just an array of Users.

Typescript automatically infers the interface for the type is { id: number, username: string, password: string }. This is caused by the global namespace we make changes to when extending Express a little further down in the code.

const users: Express.User[] = [
  { id: 1, username: 'admin', password: 'supersecret' }
]

We get the user at the point of authentication using this inside the local strategy we created.

    const user = users.find((user) => {
      if (user.username === username && user.password === password) {
        return user
      }
    })

Can't Create Users

I intentionally have avoided creating users in the database because we will be using a special approach when it comes to Xumm integration in the next article.

Suffice it to say, all you really need to do is create a new user record in the database to add users. So I've not included that in this discussion because we'll be adding to this in the next article.

Extending Express

There are a few global changes here that are specific to using Typescript with Express. These two items aren't made available in the "@types/express" or "@types/express-session" packages.

Take a look at this addition of a User object to the Express global namespace.

declare global {
  namespace Express {
    interface User {
      id: number
      username?: string
      password?: string
    }
  }
}

This essentially adds a User to Express because it's required by PassportJS to function. If you're using straight Javascript you won't need this.

Take a look at this change the the express session module.

declare module 'express-session' {
  interface SessionData {
    passport?: Object
  }
}

This change allows us to make changes to the req.session.passport object at build time (before it's been added to the session at runtime). We need to do this in order to conform to National Institute of Standards and Technology (NIST) recommendations that ask us to create a new session id when our client is authenticated.

In short these two items allow us to make changes to the session for our own purposes. These changes are changes that are unique to every project so it makes sense that these would not be in these packages.

Handling POST Data

To handle data that is posted to the application we need to be able to parse it. This is how parsing posted data is accomplished.

app.use(express.urlencoded())

Enabling Session Support

These lines configure session support and then adds it to the middleware "sandwich".

const sessionConfig: SessionOptions = {
  secret: 'Not Really A Secret But It Should Be In Production',
  cookie: {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production' ? true : false, 
    sameSite: 'strict' 
  }
}

app.use(session(sessionConfig))

Note the items related to the cookie.

httpOnly tells the browser not to modify the cookie with Javascript.
secure enforces the use of TLS (Transport Layer Security) when in production. If there is no SSL session support just won't happen.
sameSite just ensures that cookies will only be sent to the caller from your domain (it will not be send on cross site requests from other domains).

Local Strategy

This is the bit of code that actually does our authentication work.

passport.use(
  new Strategy({}, (username: string, password: string, done: Function) => {
    if (!users) return done(null, false, { message: 'Database Failure.' })

    const user = users.find((user) => {
      if (user.username === username && user.password === password) {
        return user
      }
    })

    const failedAuthMessage = "Username and password combo isn't registered."
    if (!user) return done(null, false, { message: failedAuthMessage })

    const sanitizedUser: Express.User = {
      id: user.id
    }
    return done(null, sanitizedUser)
  })
)

Serializing User

Once a user is authenticated passport calls the serializeUser function. You'll need to provide this when using the Passport-Local strategy.

Because the cookies are exposed to the client it's worth nothing that it's probably good to only serialize the user's id (or some other identifying information you can use to ).

passport.serializeUser((user, done) => {
  return done(null, user)
})

It's worth noting this only get's called at the point of authentication. It's not called on subsequent requests from the client if the session if valid.

Deserializing User

passport.deserializeUser((user: Express.User, done: Function) => {
  return done(null, user)
})

Initializing Passport

Up to this point passport has been in your code but it would not be able to impact any incoming http request. This initializes passport and adds that initialized instance of PassportJS to your middleware stack.

app.use(passport.initialize())

Binding PassportJS to Express Session

Adding the PassportJS session to the middleware stack (after you've already initialized express-session) binds all your PassportJS sessions to the express-session.

app.use(passport.session())

Showing Ephemeral Messages

Occasionally you want to pass messages to your users which might be helpful (but don't give a bad actor information that will help them to infer things about your website's security).

To do this easily we will add some flash messaging support.

app.use(flash())

Easily Authenticate Any Route

To easily require authentication for any specific route you can just add authRequired to the middleware of any route to secure it.

If the user is not authenticated they will be automatically redirected to login if they attempt to access routes with this middleware attached.

const authRequired = (req: Request, res: Response, next: NextFunction) => {
  if (!req.isAuthenticated()) return res.redirect('/login')
  next()
}

One Special Route

Most of the other routes here are pretty self explanatory.

Home (/) shows the home page.
Login (/login) allows your usr to login.
Members (/members) shows the user a page that requires authentication.
Logout (/logout) - yep, you guessed it - logs the user out by destroying their session.

Of all these those there is one that might seem a little unusual. It's the /login/success route.

This route takes an old session that has been authenticated and assigns a new session id to it.

app.get('/auth/success', (req: Request, res: Response, next: NextFunction) => {
  const previousSessionData = req.session.passport
  const previousUser = req.user
  req.session.regenerate((err) => {
    if (err) return res.status(500)
    req.session.passport = previousSessionData
    req.user = previousUser
    req.session.save((err) => {
      if (err) return res.status(500)
    })
    return res.send(`
      <a href="/">Home</a> ${
        req.isAuthenticated()
          ? '| <a href="/logout">Logout</a>'
          : '| <a href="/login">Login</a>'
      } | <a href="/members">Members</a>
      <h1>Login Success!</h1>
      <p>Would you like to go to the <a href="/members">Members Area</a>?</p>

      <p>
        A client side redirect here could allow this intermediary step to be skipped.
        Note the new session ID!
      </p>
      SessionID: ${req.session.id} <br/>
      Authenticated: ${req.isAuthenticated() ? 'Yes' : 'No'} <br/>
      User: ${JSON.stringify(req.user)}
    `)
  })
})

This is a key activity to secure your site. It's optional but it goes a long way toward preventing man in the middle attacks based on intercepting authenticated session identifiers.

Next Up

I hope this has helped to quickly get a working understanding of PassportJS. The information here is specific to using the Local Strategy but most of the context here applies to any of the strategies.

The next article will build on this with Step 5 (Implementing the PassportJS Xumm Strategy). Also, we'll include the use of a real database abstraction layer (TypeOrm) so you can see how your user models are impacted by sessions and how to store wallet information.

Article Image Credit

Photo by Jon Tyson on Unsplash

Web Authentication By The Numbers (Part 1)

Jay F. Grissom — Wed, 17 Nov 2021 20:30:09 +0000

How authentication layers are built up to create an authentication system for your website.

Audience

This article is intended for intermediate level website developers and software engineers. I've tried to make it approachable for beginners but it's really not for absolute beginners.

Video

Problem

Website authentication can be a very confusing topic. There are a lot of considerations when thinking about an authentication system for your web projects. It's overwhelming because authentication can be extremely simple or it can be a layer cake of individual systems that each build on top of each other.

Approach

In this series we're going to start with no authentication and then you'll add a very basic authentication system. Then you'll progressively add and remove layers on top of it to make it a full blown Authentication System for your website using PassportJS.

Once that is done you'll learn how to go one step further and implement Xumm (a crypto currency wallet) SignIn as a stand-in for a traditional user:password based authentication mechanism. We'll do this using a new PassportJS strategy I've created to authenticate your users with Xumm.

For the grand finale you'll learn how to implement all of this in BlitzJS by executing a single line of code using a BlitzJS recipe.

Assumptions

The examples here use localhost without Transport Layer Security. I'll assume you understand that all this is not secure in a real world production environment without TLS.

For early portions of this series I'll assume

You're familiar with Typescript.
You know how to setup NodeJS and ExpressJS.
You're familiar with the concept of middleware for ExpressJS.
You know how to use Postman to make calls to your application as if you're a client.
You're familiar with PassportJS but may not have implemented it previously.

For late portions of this series I'll assume

You understand that Xumm is a wallet for the XRP Ledger (an open source crypto currency project).
You're familiar with BlitzJS.

GitHub Repo

If you want to follow along with examples there is a branch for each type of authentication system we're building here over on my corresponding Web Authentication By The Numbers Github Repo.

jfgrissom / web-authentication-by-the-numbers

This repository goes with the article by the same name on dev.to.

web-authentication-by-the-numbers

This repository goes with the article by the same name on dev.to.

View on GitHub

Starting With No Authentication (Step 0)

Initially we'll start the application on the master branch where there is no authentication. See the index.ts file on the master branch for this.

import express, { Application, Request, Response } from 'express'

const app: Application = express()
const port = 3000

app.get('/', async (req: Request, res: Response): Promise<Response> => {
  return res.status(200).send({
    message: "Hello World! I'm not authenticated."
  })
})

app.listen(port)

Making a call to this using Postman will return this.

{
    "message": "Hello World! I'm not authenticated."
}

Primitive Authentication System (Step 1)

Probably the most primitive authentication system we can build with express contains a simple set of hard coded credentials. Using this basic auth example we can setup some thing like this.

NOTE: This authentication system is horrible for many reasons. Don't use this in your app (the user and password will be checked into Github). This example is just to help you understand what is going on here.

import express, { Application, Request, Response, NextFunction } from 'express'
import auth from 'basic-auth'

const app: Application = express()
const port = 3000

app.use((req: Request, res: Response, next: NextFunction) => {
  let user = auth(req)

  if (
    user === undefined ||
    user['name'] !== 'admin' ||
    user['pass'] !== 'supersecret'
  ) {
    res.statusCode = 401
    res.setHeader('WWW-Authenticate', 'Basic realm="Node"')
    res.end('Unauthorized')
  } else {
    next()
  }
})

app.get('/', async (req: Request, res: Response): Promise<Response> => {
  return res.status(200).send({
    message: "Hello World! I'm authenticated."
  })
})

app.listen(port)

Once you get basicAuth added to your application you can try to make a call to the service using Postman but you'll just get an empty response with a status code of 401 Unauthorized.

To get an authenticated response you'll need to setup credentials in the "Authorization" tab of your Postman request. The Username is "admin" and the Password is "supersecret".

Make the request again with these credentials and you'll get this for a response.

{
    "message": "Hello World! I'm authenticated."
}

At this point you've got a password database and you can accept "Basic Authentication Headers" from any client.

The user database can be much more complicated than this. It could be in a database or provided by an external authentication provider (like AWS Cognito). For now we'll leave it simple and just keep using basicAuth.

Session Support (Step 2)

So providing credentials every time someone requests something from your site is OK if the client is an API consumer (like another web service). However this isn't typically how you would handle authentication for users who show up to your site using a web browser.

So what resources will you need to create to provide this functionality?

At this point you'll need to provide some webpage features that allow a user to login, use authorized resources, and logout.
You'll also need something that won't require them to login every time they click on something within the page.

Let's begin by adding session support to the project.

To see the code for this take a look at the session support branch of the repo.

NOTE: This branch intentionally doesn't have authentication in it.

import express, { Application, Request, Response } from 'express'
import session from 'express-session'

const app: Application = express()
const port = 3000

const sessionOptions = {
  secret: 'session secret that is not secret'
}

app.use(session(sessionOptions))

app.get('/', async (req: Request, res: Response): Promise<Response> => {
  return res.send(`Session ID: ${req.session.id}`)
})

app.listen(port)

Once you've updated this file connect to your site using a web browser at http://localhost:3000/. When you do this you should see a result similar to this on your web page Session ID: Outbyq2G_EYkL5VQzAdKlZIZPYfaANqB.

NOTE: To keep your browser sessions secure in production you would not share this session ID over an unsecured connection. You would use https (TLS).

So what is this session good for exactly? I'm glad you asked! This session is your server's way of keeping track of browser sessions (note it doesn't take care of user sessions - at least not yet anyway). The session solves the problem of requiring a user to login every time they click on something within the page.

So you've got a session and you've got a user database. How exactly do these things tie together?

The session is tied to a specific client (in this case a browser). The way the server and browser share data related to this session is through a cookie. If you look at the cookies in your browser you'll see that it matches the ID that was presented in your web page.

Session Support with User Support (Step 3)

So how to the session and the user tie together?

In this example we'll reintroduce the Basic Authentication feature by merging in the two previous branches we created (feature/basic-auth and feature/session-support).

You should end up with with this after accounting for previously existing sessions. See the code here.

import express, { Application, Request, Response, NextFunction } from 'express'
import session from 'express-session'
import auth from 'basic-auth'

// Add the session data we need that is specific to our application.
declare module 'express-session' {
  interface SessionData {
    userToken?: string
    tokenExpiration?: number
  }
}

const app: Application = express()
const port = 3000

const sessionOptions = {
  secret: 'session secret that is not secret',
  cookie: {
    httpOnly: true // Only let the browser modify this, not JS.
  }
}

app.use(session(sessionOptions))

app.use((req: Request, res: Response, next: NextFunction) => {
  // If we have a previous session with key session data then we are authenticated.
  const currentTime = Date.now() / 1000
  if (
    req.session.userToken &&
    req.session.tokenExpiration &&
    req.session.tokenExpiration > currentTime
  ) {
    next()
    return
  }

  // If no prior session was established and bad credentials were passed.
  const user = auth(req)
  if (
    user === undefined ||
    user['name'] !== 'admin' ||
    user['pass'] !== 'supersecret'
  ) {
    res.statusCode = 401
    res.setHeader('WWW-Authenticate', 'Basic realm="Node"')
    res.end('Unauthorized')
    return
  }

  // Create a new session for the user who has passed good credentials.
  req.session.userToken = user.name
  req.session.tokenExpiration = currentTime + 15 // 15 second session.
  next()
})

app.get('/', async (req: Request, res: Response): Promise<Response> => {
  const currentTime = Date.now() / 1000
  return res.send(`
  Session ID: ${req.session.id} <br/>
  Authenticated Username: ${auth(req)?.name} <br/>
  User Token: ${req.session.userToken} <br/>
  Current Time: ${currentTime} <br/>
  Session Expiration: ${req.session.tokenExpiration}
  `)
})

app.listen(port)

You have session functionality and you have basic authentication functionality.

You can test how the page behaves without credentials by going to the page in a web browser and clicking cancel when prompted for a username and password. You should see a 401 Error in the console and unauthorized on the web page.

You can test how the page behaves with credentials by prepending the username and password in the url so that it looks like this http://admin:supersecret@localhost:3000/.

Session ID: Wc29HPGVTdnx0VqsDr7uaxWPTV3KoIzO
Authenticated Username: admin
User Token: admin
Current Time: 1637179009.834
Session Expiration: 1637179024.829

You can test out the session persistence by refreshing the page. You'll notice that the User Token remains admin but the Authenticated Username becomes undefined.

To test out the session expiring by passing good credentials like this http://admin:supersecret@localhost:3000/. Then you can pass bad bad credentials to the page like this http://bad:credentials@localhost:3000/. Then refresh the page repeatedly until the session expires after 15 seconds. When the tokenExpires then you'll see a prompt show up for the Username and Password (just click cancel). NOTE: This is most easily done in Chrome because it will not automatically cache (and reuse) good credentials after you've passed bad credentials.

With this latest iteration we've answered a few questions.

How do we access the name of the user? You can see the Authenticated username came in through the authenticated request auth(req) and that if we want to use it again we'll need to access it through the session.
How does our system know if the user previously was authenticated? It knows because a prior session was established.
Why can't a browser just manipulate the cookie and add data we are expecting? We are telling browsers that they can't make changes to the cookie using Javascript with the httpOnly directive {cookie: { httpOnly: true }}. Our server knows the state of the cookie and will reject it if the client changes the cookie.

So what if you don't want to use Basic Auth? This is a very reasonable thing. Basic auth is pretty terrible for a lot of reasons.

I've added more to this in the next section of this series. The section is called Web Authentication By the Numbers (Part 2) and it deals directly with setting up PassportJS using the Local Strategy.

Article Image Credit

Photo by Parsoa Khorsand on Unsplash

Simple CICD with CodeBuild, Github, and S3 for Single Page Applications

Jay F. Grissom — Tue, 29 Jun 2021 18:02:44 +0000

Goal

The goal of this is to create a simple CI/CD system to build and deploy an SPA (Single Page App) to AWS S3.

Requirements

Development branch should deploy to development environment.
A release from the Master branch should deploy to production environment.
Build, test, and deploy in a single place.

Tools

AWS CDK.
TypeScript.

Prerequisites

Familiarity with AWS CDK.
1. Create a typescript project. See this to get started with typescript and the AWS CDK.
2. Be familiar with this to the point where you can update your stack located at lib/your-stack.ts.
Familiarity with Typescript.

CodeBuild vs Local Builds

This is the only thing you'll need to deploy manually. This CodeBuild environment becomes the new build environment for your SPA.

If you've been deploying from your local machine this effectively replaces that environment for one that is always available in AWS.

Code

Using AWS CDK you can create the CodeBuild environment by updating your stack inside the lib directory.

import * as cdk from '@aws-cdk/core'
import * as codebuild from '@aws-cdk/aws-codebuild'
import * as iam from '@aws-cdk/aws-iam'

export class CiCdStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props)

    // Define some basics information.
    const org = 'YourGithubOrgName'
    const repo = `YourRepoName`
    const develop = 'YourDevelopmentBranchName'
    // This is the builds spec that is associated with the project being built. This is where you'll deploy to S3 from.branchOrRef: '*', // * Covers all branches, tags, commit IDs, etc...
    const buildSpec = 'buildspec.yaml'
    const releaseFilter = "^refs\/tags\/v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*).*$"

    // codeBuildIamPrincipal is shared across stacks.
    const codeBuildIamPrincipal = 'site-publisher'

    // Define the source details.
    const gitHubSource = codebuild.Source.gitHub({
      owner: org,
      repo: repo,
      webhook: true,
      // * Covers all branches, tags, commit IDs, etc...
      branchOrRef: '*',
      webhookFilters: [

        // Runs build on release from any target branch (normally master).
codebuild.FilterGroup.inEventOf(codebuild.EventAction.PUSH)
          .andHeadRefIs(`${releaseFilter}`),

        // Runs build on a push to develop branch.
codebuild.FilterGroup.inEventOf(codebuild.EventAction.PUSH)
          .andBranchIs(develop)
      ],
      webhookTriggersBatchBuild: true
    })

    // Create a role for our Codebuild so it can be used by other stacks.branchOrRef: '*', // * Covers all branches, tags, commit IDs, etc...
    const sitePublisherCodeBuild = new iam.Role(this, 'Role', {
      assumedBy: new iam.ServicePrincipal('codebuild.amazonaws.com'),
      roleName: codeBuildIamPrincipal
    })

    // Setup the Codebuild project.
    new codebuild.Project(this, org, {
      source: gitHubSource,
      buildSpec: codebuild.BuildSpec.fromSourceFilename(buildSpec),
      role: sitePublisherCodeBuild
    })
  }branchOrRef: '*', // * Covers all branches, tags, commit IDs, etc...
}

Deploy

Once your code is setup just deploy it to AWS.

npm run build
cdk synth
cdk deploy

When this is completed you'll have a CodeBuild project you should be able to see in the AWS Console.

Webhook

Once this is deployed a webhook between the CodeBuid project and Github should be setup. Take a look at your GitHub repo under settings/hooks and you'll see a new webhook was setup for you.

This is a lot better than it used to be. You used to have to get the URL and Secret from the UI and manually enter it into the GitHub settings.

The buildspec

In your buildspec.yaml add the details you need to perform the build and deployment.

In this case we're building a GatsbyJS project.

version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 14
    commands:
      - npm install -g gatsby-cli
      - npm --version

  pre_build:
    commands:
      - export FRONTEND_ROOT=${CODEBUILD_SRC_DIR}/PathToYourFrontEndRoot
      - cd ${FRONTEND_ROOT}branchOrRef: '*', // * Covers all branches, tags, commit IDs, etc...
      - echo Installing dependencies...
      - npm install
  build:
    commands:
      - npm run build
  post_build:
    commands:
      - echo Build completed deploying to hosting bucket...
      - npm run deploy

batch:
  fast-fail: true
  build-list:
    - identifier: linux_small
      env:
        compute-type: BUILD_GENERAL1_SMALL
      ignore-failure: false

Build and Deploy Scripts

Inside the package.json file of the project being built you'll need to handle these as if you're deploying them from your local environment.


  "scripts": {
    ...,
    "build": "gatsby build",
    "deploy": "aws s3 cp public/ s3://Your-Hosting-Bucket-Name/ --recursive",
    ...
  },

Usage

Now once you cut a release where the tag looks like v0.0.1 in Github and CodeBuild will be triggered.

Pushing or merging to your development branch will trigger CodeBuild too.