DEV Community: Randall Degges

Build and Understand a Simple Node.js Website with User Authentication

Randall Degges — Fri, 17 Aug 2018 05:00:00 +0000

Building websites with user authentication and management (login, registration, password reset, etc.), can be a huge pain. As a developer there are a million little things you need to worry about:

Storing the users in your database
Making sure you have the right user attributes defined
Forcing users to be logged in to view a page
Building registration and login forms
Creating password reset workflows that email users a link
Verifying new users when they sign up via email
Etc…

The list goes on and on.

Today I’m not only going to show you how to quickly build a Node.js website that supports all those things above, I’m going to teach you exactly what’s going on behind the scenes so you fully understand how web authentication works.

If you’ve ever been curious about how web authentication and user security works, you will enjoy this. =)

What We’re Building

As I mentioned above, today we’ll be building a simple Node.js site that supports a few key user flows:

User registration
User login
Password reset
Email verification

The end product of this article looks like this:

If you want to see a preview of this project live, you can do so here: https://okta-express-login-portal.herokuapp.com/.

The site will be built using a few different tools (you don’t need to know them already):

Express.js, the most popular web framework in the Node.js ecosystem.
express-session, a popular session management library. This is what will allow us to create and store cookies that remember who a user is.
Pug, a popular templating language that makes writing HTML a bit simpler.
oidc-middleware, a popular developer library that makes handling authentication using the OpenID Connect protocol simple

Install the Tools

The first thing you need to do is install all the open source tools we’ll be using to build this Node.js site.

PS : If you don’t already have Node.js setup and working on your computer, you can go checkout this link which shows you the best way to get it working regardless of what operating system you’re using.

Next, install the express-generator tool, which is the officially supported bootstrapping tool for quickly getting started with Express.js.

npm install express-generator@4.16.0

Once that’s done, you’ll want to scaffold your new Express.js site using express-generator.

express --view pug login-portal
cd login-portal
npm install

You now have a simple Express.js website that you can run and test out. Start up your new web server by running npm start then go visit http://localhost:3000 in your browser to make sure everything is working OK. If all is well, you should see a page like the one below.

Next, install some additional packages. We’ll use these packages through the rest of the tutorial. Getting them installed and out of the way upfront will make it simpler later on.

To install all the extra dependencies, run the following commands in your terminal.

npm install express-session@1.15.6
npm install @okta/oidc-middleware@0.1.3
npm install @okta/okta-sdk-nodejs@1.1.0

Now, on with the show!

Setup Your Authorization Server

Historically, implementing web authentication has been a bit of a mess. Everyone used to implement authentication patterns in different, arbitrary ways. Over the last few years, however, the game has changed quite a bit with the introduction and growing popularity of the OpenID Connect protocol. If you want to read up on OpenID Connect, I recommend this series.

One of the core tenants of OpenID Connect is the authorization server. An authorization server is a one-stop shop that handles all of the user login flows for your applications. The idea is that your application redirects to the authorization server to process user logins and the authorization server then redirects the user back to your website once the user has been authenticated.

Authorization servers make handling user management a significantly simpler, less risky task — so that’s what we’ll be doing today: using an authorization server provider (Okta) to make the process simple and secure.

Okta is free to use and allows you to create and manage users, authorization servers, and lots of other tasks that make handling web authentication simple.

To get started with the authorization server setup, you first need to go create a free Okta developer account: https://developer.okta.com/signup/. Once you’ve created your account and logged in, follow the steps below configure Okta and then you’ll be ready to write some code!

Step 1: Store Your Org URL

The first thing you need to do is copy down the Org URL from the top-right portion of your Okta dashboard page. This URL will be used to route to your authorization server, communicate with it, and much more. You’ll need this value later, so don’t forget it.

Step 2: Create an OpenID Connect Application

Okta allows you to store and manage users for multiple applications you might be creating. This means that before we can go any further, you need to create a new OpenID Connect application for this project.

Applications in OpenID Connect have a username and password (referred to as a client ID and client secret) that allow your authorization server to recognize which application is talking to it at any given time.

To create a new application browse to the Applications tab and click Add Application.

Next, click the Web platform option (since this project is a web app).

On the settings page, enter the following values:

Name : login-portal
Base URIs : http://localhost:3000
Login redirect URIs : http://localhost:3000/users/callback

You can leave all the other values unchanged.

Now that your application has been created, copy down the Client ID and Client secret values on the following page, you’ll need them later when we start writing code.

Step 3: Create an Authentication Token

In order to access the Okta APIs and be able to manage your user accounts with a great deal of granularity, you’ll also need to create an Okta authentication token. This is an API key that will be used later on communicate with the Okta APIs and allows you to do things like:

Create, update, and delete users
Create, update, and delete groups
Manage application settings
Etc.

To create an authentication token click the API tab at the top of the page followed by the Create Token button. Give your token a name, preferably the same name as your application, then click Create Token. Once your token has been created, copy down the token value as you will need it later.

Step 4: Enable User Registration

The last piece of setup you need to complete is to enable user registration functionality for the authorization server. Normally, authorization servers only support login, logout, and stuff like that. But Okta’s authorization server also supports self-service registration, so that users can create accounts, log into them, reset passwords, and basically do everything without you writing any code for it.

In your Okta dashboard, you’ll notice a small button labeled < > Developer Console at the top-left of your page. Hover over that button and select the Classic UI menu option that appears.

Next, hover over the Directory tab at the top of the page then select the Self-Service Registration menu item. On this page click the Enable Registration button.

On the configuration page, leave all the settings as their default values, except for the Default redirect option. For this option, click the Custom URL radiobox and enter http://localhost:3000/dashboard as the value.

This setting essentially tells the authorization server where to redirect users after they’ve successfully created a new account on your site.

Once you’ve clicked Save , the last thing you need to is switch back to the developer console.

Hover over the Classic UI button at the top right of the page and select the < > Developer Console menu item from the dropdown.

Configure Session Management

Now that all the setup work is done, let’s write some code!

The first thing we’ll add to this basic Express.js site is support for sessions using the express-session library.

Session management is the core of any authentication system. It’s what allows a user to stay logged into your site and not have to re-enter their credentials before viewing each page. The most secure way to handle user sessions is via server-side cookies, which is why we’ll be using the express-session library: it allows us to create and manage server-side cookies.

To start, open up the ./app.js file in your favorite editor (I prefer neovim), and import the session library at the top of the file alongside the other import statements. The app.js file is the heart of your Express.js site. It initializes the Express.js web server, contains the site settings, etc.

var createError = require('http-errors');
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan');
var session = require("express-session");

Next, you need to remove the cookie-parser library that express-generator included by default, since we won’t be using it. In the ./app.js file delete the following two lines of code.

var cookieParser = require('cookie-parser');

// and...

app.use(cookieParser());

Now all you need to do is plug the express-session library into the ./app.js file along with the other middlewares.

app.use(logger('dev'));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public')));
app.use(session({
  secret: 'LONG_RANDOM_STRING_HERE',
  resave: true,
  saveUninitialized: false
}));

Make sure to replace LONG_RANDOM_STRING_HERE with an actual random string you type. This string is what will keep your user’s cookies safe from compromise. I personally like to bash my hands around on the keyboard for a second to generate something random.

This session library handles a lot of work behind the scenes:

It creates secure, cryptographically signed cookies so you can store data in a user’s browser. Cryptographic signing is a technique that allows your server to tell whether or not a user has tried to “modify” their cookies to make it look as if they’re someone they’re not.
It gives you a simple API for creating and removing cookies
It allows you to tweak and configure cookie settings based on what you need to do

As you’ll see in a moment, this library is used by the oidc-middleware library behind the scenes to make user authentication magical.

Create Express.js Views

The next thing we’re going to do is create our Express.js views. Views in Express.js are nothing more than HTML templates (web pages) that we want to display to a user. But unlike normal HTML, we’ll be using the Pug templating language to create our views.

Pug is one of the most popular templating languages in the Node.js ecosystem because it allows you more concisely write HTML, use variables, and things like that.

Create the Layout View

The first (and most important!) view we’re going to create is the ./views/layout.pug view. This is the “base” view that all our other views will extend.

In this view we’ll define the basic layout of all the pages, the navbar, and stuff like that. Open up the ./views/layout.pug and replace whatever is in the file with the following.

block variables

doctype html
html(lang="en")
  head
    meta(charset="utf-8")
    meta(name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no")
    link(rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous")
    link(rel="stylesheet", href="/stylesheets/style.css")
    title okta-express-login-portal: #{title}
  body
    div.top-bar.d-flex.flex-column.flex-md-row.align-items-center.p-3.px-md-4.mb-3.bg-white.border-bottom.box-shadow
      h5.my-0.mr-md-auto.font-weight-normal
        a(href="/", title="Expresso") okta-express-login-portal
      nav.my-2.my-md-0.mr-md-3
        a.p-2.text-dark(href="/", title="Home") Home

        if user == undefined
          a.p-2.text-dark(href="/users/login") Log In / Register
        else
          a.p-2.text-dark(href="/dashboard") Dashboard
          a.p-2.text-dark(href="/users/logout") Logout
    .container
      block content

    footer.
      Built with #[a(href="https://expressjs.com/") Express.js], login powered by #[a(href="https://developer.okta.com/") Okta].

As you can probably figure out if you’re at all familiar with HTML, pug is very similar to HTML but uses whitespace instead of closing tags (like the Python programming language).

This layout view doesn’t do anything except render a simple page with a navbar at the top, a footer at the bottom, and two special constructs, block variables and block content.

The block variables line at the top of the file means that any of the templates that inherit from this one will be able to inject some variables into the page. You might have noticed that the title tag contains a variable: #{title} — this is one of the variables that a child template can overwrite later on.

Did you notice the block content line right above the footer? This block allows a child template to inject HTML into our layout template at just the right spot — this way our child templates don’t need to re-define a navbar, page header, etc.

By using these two blocks: variables and content, our child templates can build full web pages with nothing more than a title and some body content. Pretty nifty.

Create the Homepage View

The next view we’ll create is the ./views/index.pug view. Open that file and insert the following code.

extends layout

block variables
  - var title = "Home"

block content
  h2.text-center Express App

  .row
    .offset-sm-2.col-sm-8
      .jumbotron.text-center.
        Welcome to your new Express app! Please visit the
        #[a(href="https://github.com/rdegges/okta-express-login-portal", title="okkta-express-login-portal on GitHub") GitHub page] to learn more.

Notice the extends layout line at the top. This is what tells pug that this template is a child of the layout template we created earlier.

In the block variables section we then define our title variable which will be used in the layout template to output the page title, and in the block content section we insert the HTML for the rest of the page.

As you can hopefully see by now, template inheritance in Pug is pretty straightforward.

Create the Dashboard View

The next view to create is the dashboard view. This is the page users will see once they’ve logged into the site. Open up the ./views/dashboard.pug file and insert the following code.

extends layout

block variables
  - var title = "Dashboard"

block content
  h2.text-center Dashboard

  .row
    .offset-sm-2.col-sm-8
      .jumbotron.text-center.
        Welcome to your dashboard page, #{user.profile.firstName}.

You’ll notice that in this template there’s a new variable being used: #{user}. This will eventually refer to the currently logged in user as you’ll see later on.

Create the Error Views

The last two views you need to create are for handling errors.

Open up the ./views/error.pug view and insert the following code.

extends layout

block content
  h1= message
  h2= error.status
  pre #{error.stack}

This view will be rendered when the user hits a URL that doesn’t exist (404), or when the web server has a problem (5XX).

You’ll also need to create a file named ./views/unauthenticated.pug and insert the following code. This view will be displayed to a user if they visit a page that requires them to be logged in.

extends layout

block variables
  - var title = "Unauthenticated"

block content
  h2.text-center You Must Log In to View This Page
  p.text-center.
    You must be signed in to view this page. Please #[a(href="/users/login", title="Login") login or register] to view this page.

Create Public Routes

Routes in Express.js are the place where you define application logic. They dictate what code runs when a particular URL is hit by a user, and what response is sent back.

To get started, let’s remove the default routes that express-generator created for you. Run the following command to remove them.

rm routes/*

Next, create a file named ./routes/public.js and insert the following code.

const express = require("express");

const router = express.Router();

// Home page
router.get("/", (req, res) => {
  res.render("index");
});

module.exports = router;

In this module we’re creating a new Express.js Router and telling it that if a user makes a GET request to the / URL, then we’re going to run a function that renders the index.pug view file we created earlier and returns it to the user.

Now this won’t take effect just yet (for reasons you’ll learn about later on), but once this router is “enabled”, every time a user makes a request for the homepage of the site, eg: http://localhost:3000, this code will run and the index.pug view will be shown.

Pretty neat, right?

Next, create a file named ./routes/dashboard.js and insert the following code.

const express = require("express");

const router = express.Router();

// Display the dashboard page
router.get("/", (req, res) => {
  res.render("dashboard");
});

module.exports = router;

This router acts similarly to the homepage router above, except it is rendering our dashboard page. While it doesn’t make sense just yet, if a user eventually visits the /dashboard URL, this function will run which will render the dashboard.pug defined earlier.

If you were to go into this file and define another route, for example:

router.get("/test", (req, res) => {
  res.render("test");
});

… You would find that a user would need to visit /dashboard/test to trigger the function to run. Again: don’t worry about this not adding up just yet, we’ll get to that down below.

Enable the Routes

Now that you’ve created some routes for public pages, let’s enable them with Express.js so we can actually see them in action!

To do this, open up the ./app.js file and delete the following two lines.

var indexRouter = require('./routes/index');
var usersRouter = require('./routes/users');

Replace those two lines with the two lines of code below.

const dashboardRouter = require("./routes/dashboard");        
const publicRouter = require("./routes/public");

Now we’re importing the correct route files we just defined above.

Next, scroll down until you see the following two lines of code and delete them.

app.use('/', indexRouter);
app.use('/users', usersRouter);

Those lines of code were loading up the old routes we just deleted. Now you need to change those lines of code to look like this.

app.use('/', publicRouter);
app.use('/dashboard', dashboardRouter);

Is it starting to make sense now? These app.use lines of code tell Express.js that if a user visits the / URL, it should look into the ./routes/public.js file and start matching URLs there to run against. So if a user visits the homepage, eg: /, Express.js will look in the ./routes/public.js file, find the route that serves the / URL, then run the associated function.

The same thing happens with the dashboardRouter below. If a user visits /dashboard, then Express.js will look in the ./routes/dashboard.js file for a function that runs when the / URL is called, because /dashboard + / is the path the user is visiting!

Routes in Express.js make it easy to compose complex sites with lots of nested URLs without a lot of work.

Now that you’ve enabled your routes, go test them out. Start your web server by running the command below.

npm start

Then visit http://localhost:3000 in your browser. You should see the following page rendered.

NOTE : This page doesn’t look just right yet because we haven’t created any CSS yet. We’ll do that last.

If you now go visit the dashboard page you created, http://localhost:3000/dashboard, you’ll notice you get an error. That is because that Pug view refers to the #{user} variable we haven’t yet defined. We’ll get to that soon.

Configure User Authentication

Now that our Express.js site is starting to become functional, let’s dive deeper into user authentication.

The first thing you need to do is open up ./app.js and import the following two libraries at the top of the file.

var createError = require('http-errors');
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan');
var session = require('express-session');
var okta = require("@okta/okta-sdk-nodejs");
var ExpressOIDC = require("@okta/oidc-middleware").ExpressOIDC;

The two libraries we just added are at the bottom of the list: @okta/okta-sdk-nodejs and @okta/oidc-middleware. These two libraries handle all of the OpenID Connect communication and routing.

The next thing we need to do is create an oktaClient object as well as an ExpressOIDC object. These will be used in a moment once we’ve configured them and given them the right credentials.

To do this, open up your ./app.js file again, find the line that reads var app = express();, and insert the following code immediately beneath it.

var oktaClient = new okta.Client({
  orgUrl: 'https://{yourOktaDomain}',
  token: '{yourOktaToken}'
});

const oidc = new ExpressOIDC({
  issuer: "https://{yourOktaDomain}/oauth2/default",
  client_id: {yourClientId},
  client_secret: {yourClientSecret},
  redirect_uri: 'http://localhost:3000/users/callback',
  scope: "openid profile",
  routes: {
    login: {
      path: "/users/login"
    },
    callback: {
      path: "/users/callback",
      defaultRedirect: "/dashboard"
    }
  }
});

Now, remember those values I told you to write down way back at the beginning of this post? Now you need them! Make sure you substitute out the following variables above for the proper values: {yourOktaDomain}, {yourOktaToken}, {yourClientId}, and {yourClientSecret}.

The oidc object created handles 100% of the OpenID Connect protocol support. It handles router the users to the authorization server to handle user registration, login, password reset, etc. It handles logging the users into your application using secure cookies (powered by express-session), and it also handles everything else.

The oktaClient object is merely used to retrieve user data from the Okta API service.

Now that our OpenID Connect support is ready to be used, let’s enable it. To do this, open up the ./app.js and find the session middleware from earlier, then add the following line beneath it.

app.use(session({
  secret: 'asdf;lkjh3lkjh235l23h5l235kjh',
  resave: true,
  saveUninitialized: false
}));
app.use(oidc.router);

The app.use(oidc.router); call is all that’s needed to tell Express.js to enable the routes that ship with the oidc-middleware library to handle all of the OpenID Connect support. You might have noticed above that when we created the oidc object we specified some routes in the configuration. These settings dictate what URLs we want to use to handle user login, and what URLs we want to redirect users to after they’ve been logged in.

One benefit of this router being enabled is that from this point forward, in any of our route code, we’ll have access to a special variable, req.userinfo, which contains some of the currently logged in user’s basic profile information (pulled from Okta).

And while req.userinfo is nice, it’d be a lot nicer if we could get any data about the currently logged in user that we want.

So let’s go ahead and define another middleware to help us with that. Immediately below the app.use(oidc.router); code, insert the following:

app.use((req, res, next) => {
  if (!req.userinfo) {
    return next();
  }

  oktaClient.getUser(req.userinfo.sub)
    .then(user => {
      req.user = user;
      res.locals.user = user;
      next();
    }).catch(err => {
      next(err);
    });
});

This middleware will run on every user request, and does the following:

It checks to see if there is a currently logged in user or not by looking at the req.userinfo object. If there is no user logged in, it will do nothing (return next();).
If there IS a user logged in, this middleware will then use the Okta Node SDK library to retrieve the user object from the Okta API.
Finally, it will create two new values: req.user and res.locals.user which point to the user object directly.

This means that in any route we define later on, we could access the req.user object directly to view the user’s information, edit it, or even delete it.

For example, you could create the following route below to display the user’s profile information each time a user visits the /test URL:

app.get('/test', (req, res) => {
  res.json({ profile: req.user ? req.user.profile : null });
});

Let’s also go ahead and create one additional middleware, loginRequired, that will only allow a user to visit a route if they’ve been logged in already. This will come in handy if you want to build pages that only logged in users can access (a dashboard, etc.).

Below the code above, go ahead and define the function below.

function loginRequired(req, res, next) {
  if (!req.user) {
    return res.status(401).render("unauthenticated");
  }

  next();
}

Since we want to ensure only logged in users can view our dashboard page, let’s also go back and modify our route code for the dashboard.

Find the line of code that enabled the dashboard route in your ./app.js.

app.use('/dashboard', dashboardRouter);

Now modify it to look like this.

app.use('/dashboard', loginRequired, dashboardRouter);

By injecting the loginRequired function immediately after the URL pattern, Express.js will first run our loginRequired middleware BEFORE the dashboardRouter is processed. This way, if a user visits any page that starts with the URL /dashboard they’ll be required to log in before they can access it!

The final thing we need to do to finish up our authentication component is define a logout route. The oidc-middleware library provides logout functionality, but doesn’t automatically generate a route for it.

To do this, create a new file named ./routes/users.js and put the following code inside of it.

const express = require("express");

const router = express.Router();

// Log a user out
router.get("/logout", (req, res) => {
  req.logout();
  res.redirect("/");
});

module.exports = router;

As you can probably tell, this route will log a user out of their account if they send a POST request to the /users/logout URL. The only thing we need to do now is enable this route in our ./app.js.

Open up ./app.js, and import this new route file alongside the others at the top of the file.

const dashboardRouter = require("./routes/dashboard");
const publicRouter = require("./routes/public");
const usersRouter = require("./routes/users");

Next, scroll down until you see your other routers being enabled, and enable this router as well.

app.use('/', publicRouter);
app.use('/dashboard', loginRequired, dashboardRouter);
app.use('/users', usersRouter);

Congratulations, you’ve now got user management and authentication fully configured for your website! And you didn’t even have to write any code, manage any passwords, store anything in a database, etc!

How Authentication Works

Now that you’ve seen how to successfully setup authentication for your Node.js websites, let’s talk a bit more about how it works and explore the full authentication flow.

In order to explain each component, let’s assume that you’re visiting this website and are not currently logged into your account.

When you first click the Log In / Register button at the top of the page, the oidc-middleware library is going to redirect you to an Okta hosted domain (the authorization server). Here’s the sort of URL you’ll be redirected to:

https://dev-842917.oktapreview.com/login/login.htm?fromURI=/oauth2/v1/authorize/redirect?okta_key=qBpZVCpQIJlxUALtybnI9oajmFSOmWJNKL9pDpGtZRU

NOTE : You can fully customize this domain name, look, and feel using Okta.

Once you’ve landed on the authorization server page, you can either enter your account credentials and login immediately or create a new account. This functionality is handled by the authorization server completely.

If you enter your credentials and click the Sign In button on the authorization server, what happens behind the scenes is:

Your password is hashed and your credentials are checked against the Okta user database to determine whether or not they are correct
If your credentials are correct, a new session cookie is created for you on the Okta hosted domain (eg: dev-842917.oktapreview.com, in this case), and you are redirected to the redirect_uri setting you provided earlier when defining the ExpressOIDC object. In this case, you’d be redirected to http://localhost:3000/users/callback. When you’re redirected to this URL, the authorization server will also pass along a special code token. This is part of the OpenID Connect Authorization Code flow.
Your Express.js app will receive the request to /users/callback and service the request automatically using the oidc-middleware library’s built-in routes. The route servicing this URL will intercept the request and exchange the code token for an access and id token. This process of exchanging the code token is part of the OpenID Connect authorization code flow and is detailed more here: /authentication-guide/implementing-authentication/auth-code#3-exchanging-the-code-for-tokens.
Once these tokens have been retrieved, the oidc-middleware library takes the user’s basic information embedded in the id token and stores it in a session cookie.
Then, the oidc-middleware library redirects you to the dashboard page as a fully logged-in user.
From this point on, each time your browser makes a request to the Express.js website, the cookie containing your profile information will be sent back to Express.js, so that the oidc-middleware library can recognize who you are and populate a req.userinfo object with your account data.

Once your session cookies have expired (or have been wiped via a logout procedure), the process starts all over again.

Create Styles

I’m not a professional designer, but even I can make this website look a little better.

Create a file named ./public/stylesheets/style.css and put the following CSS into it.

.top-bar a {
 text-decoration: none;
  color: inherit;
}

footer {
  border-top: 1px solid rgba(0,0,0,.1);
  margin-top: 4em !important;
  padding-top: 1em;
  text-align: center;
  margin-top: 1em;
}

h2 {
  margin-bottom: 2em;
}

.container {
  padding-top: 2em;
}

This will make the page styles look a little nicer.

Test Out Your New Login Portal

Now that your Express.js website is built, why not take it for a test drive? Start up your web server by running the npm start command, visit http://localhost:3000, and test things out!

You’ll notice a few things:

If you click the Log In / Register button at the top of the page, you can either create a new user account OR log into an existing one. This functionality is all provided by Okta’s authorization server automatically.
Once you’re logged in, you’ll be redirected to the /dashboard page, which will greet you by your first name. Remember that #{user.profile.firstName} variable in the ./views/dashboard.pug file earlier? That variable is now you actual user account since you’ve now plugged in all the appropriate middleware.
If you log out, then immediately click the Log In / Register button again, you’ll be instantly logged in without needing to re-enter your username and password. This is a feature of OpenID Connect — the authorization server remembers who you are for a set amount of time. This is the same way that Google Login and Facebook Login work!

If you’re already logged into your Okta account and instantly get logged into the dashboard, don’t worry. Just open a new incognito window in your browser and go through the flow there.

Learn More About Node.js and Authentication

I hope you enjoyed seeing how authentication works with OpenID Connect and Node.js. Building websites with user management can be a pain, but new protocols like OpenID Connect alongside providers like Okta make the process much simpler.

If you’d like to learn more about building web apps in Node, you might want to check out these other great posts:

Finally, please follow us on Twitter to find more great resources like this, request other topics for us to write about, and follow along with our new open source libraries and projects!

PS : If you liked this project and want to see the source code in one place, please go checkout and star the GitHub repository.

And… If you have any questions, please leave a comment below!

Build a Simple CRUD App with Flask and Python

Randall Degges — Mon, 23 Jul 2018 05:00:00 +0000

Today I’m going to walk you through building a simple Flask web app (a blog) complete with user management (login, registration, etc.), database models, and everything else that goes along with it.

In this post I’ll walk you through the code piece-by-piece, explaining everything you need to know along the way. By the end of this tutorial, you’ll know how to build simple Flask web apps and have a good understanding of how to create database models, add user registration and login to your sites, etc.

Through this post you’ll learn about and use the following tools:

Flask — my favorite Python web framework. It’s small, minimal, and simple.
Flask-SQLAlchemy — an extremely popular ORM for Flask. It allows you to interact with relational database servers like Postgres, MySQL, SQLite, etc. In this tutorial, we’ll be using SQLite as our database, but any of the others would work equally well with no code changes.
Flask-OIDC — an OpenID Connect library for Flask. OpenID Connect is an open protocol that handles user authentication and authorization. It’s the “modern” way to handle authentication on the web.
Okta — a free-to-use API service that acts as an OpenID Connect authorization server. Okta will store user accounts for your app and make it possible to handle user registration, login, etc. in a simple way.
python-slugify — a simple Python library that generates web-friendly URLs. We’ll use this to convert blog post titles into URLs that look nice.

If you’d like to skip the tutorial and check out the fully built project, you can go view it on GitHub.

Initialize Authentication for Your Flask + Python App with Okta

Okta is a free-to-use API service that stores user accounts and makes handling user authentication, authorization, social login, password reset, etc. — simple. Okta utilizes open standards like OpenID Connect to make integration seamless.

In this tutorial, you’ll use Okta to store the user accounts for your web app, and you’ll use OpenID Connect to talk to Okta to handle the logistics around authentication and authorization.

To get started, you first need to create a free Okta developer account: https://developer.okta.com/signup/. Once you’ve created your account and logged in, follow the steps below configure Okta, and then you’ll be ready to write some code!

Step 1: Store Your Org URL

Step 2: Create an OpenID Connect Application

To create a new application browse to the Applications tab and click Add Application.

Next, click the Web platform option (since this project is a web app).

On the settings page, enter the following values:

Name : Simple Flask App
Base URIs : http://localhost:5000
Login redirect URIs : http://localhost:5000/oidc/callback

You can leave all the other values unchanged.

Now that your application has been created, copy down the Client ID and Client secret values on the following page, you’ll need them later when we start writing code.

Step 3: Create an Authentication Token

To access the Okta APIs and be able to manage your user accounts with a great deal of granularity, you’ll also need to create an Okta authentication token. This is an API key that will be used later on communicate with the Okta APIs and allows you to do things like:

Create, update, and delete users
Create, update, and delete groups
Manage application settings
Etc.

Step 4: Enable User Registration

The last piece of setup you need to complete is to enable user registration functionality for the authorization server. Typically, authorization servers only support login, logout, and stuff like that. But Okta’s authorization server also supports self-service registration, so that users can create accounts, log into them, reset passwords, and basically do everything without you writing any code for it.

In your Okta dashboard, you’ll notice a small button labeled < > Developer Console at the top-left of your page. Hover over that button and select the Classic UI menu option that appears.

Next, hover over the Directory tab at the top of the page then select the Self-Service Registration menu item. On this page click the Enable Registration button.

On the configuration page, leave all the settings as their default values, except for two:

Disable the User must verify email address to be activated. checkbox. This setting removes the requirement for new users to verify their email address before being allowed to access your web app.
Set the Default redirect option by clicking the Custom URL radio box and entering http://localhost:5000/dashboard as the value. This setting tells the authorization server where to redirect users after they’ve successfully created a new account on your site.

Once you’ve clicked Save , the last thing you need to is switch back to the developer console.

Hover over the Classic UI button at the top right of the page and select the < > Developer Console menu item from the drop-down.

Install Python and Flask Dependencies

The first thing you need to do to initialize your Flask app is install all of the required dependencies. If you don’t have Python installed on your computer already, please go install it now. Be sure to use the latest Python 3+ release.

NOTE : I also strongly recommend you get familiar with pipenv when you get some time. It’s a great tool that makes managing Python dependencies very simple.

Now install the dependencies required for this application.

pip install Flask==1.0.2
pip install Flask-SQLAlchemy==2.3.2
pip install flask-oidc==1.4.0
pip install python-slugify==1.2.5
pip install okta==0.0.4

Initialize Your Flask App

Now that the dependencies are installed, let’s start by creating a simple Flask app. We’ll build on this simple “hello, world!” app until we’ve got all our functionality included.

First, create a new directory for your project.

mkdir simple-flask-app
cd simple-flask-app

Next, create a directory inside your project to hold your Flask application code. This folder will hold all the project source code.

mkdir blog

Create a blog/ __init__.py file and enter the following code. This file will hold your Flask app’s initialization code.

from flask import Flask

app = Flask( __name__ )

@app.route("/")
def index():
    return "hello, world!"

Open the terminal and run the following code to start up your new Flask app.

FLASK_APP=blog flask run

Once your Flask app is running, visit http://localhost:5000 in the browser to see the hello world message!

As you can see from the small file above, building a minimalist app with Flask can be really simple. All you need to do is:

Import the Flask library
Create a Flask app object
Define a function (called a view) that runs when a particular URL is requested by a user (in this case, the / URL)

Not bad, right?

Create the Flask Templates

I’m primarily a back-end developer. I do some basic front-end work, but it isn’t my strong suit. Because of this, I like to get the tough stuff out of the way first, and in my case, that tough stuff is templating.

When building a website with Flask, you’ll usually use the built-in Jinja2 templating language.

You can think of Jinja2 as HTML with a little bit of extra stuff: variables, filters, and some other tools that make building large websites simpler. I find Jinja2 simple to work with, and once you get the hang of it, I’m sure you’ll like it too.

To get started creating the templates, let’s create the necessary template files which we’ll fill in.

mkdir -p blog/static
touch simple-flask-app/blog/static/style.css
mkdir -p blog/templates/blog
touch blog/templates/{403.html,404.html,layout.html}
touch blog/templates/blog/{dashboard.html,edit.html,index.html,post.html}

You should now have the following directory structure.

simple-flask-app
└── blog
    ├── __init__.py
    ├── static
    │ └── style.css
    └── templates
        ├── 403.html
        ├── 404.html
        ├── blog
        │ ├── dashboard.html
        │ ├── edit.html
        │ ├── index.html
        │ └── post.html
        └── layout.html

The templates folder holds all of the project’s templates. Within that folder there are some “top-level” templates:

layout.html — this template is the base for all other templates. It contains all the boilerplate HTML code, etc. that all the other pages will share in common with each other.
403.html — this template will be shown to the user if they get a 403 error
404.html — this template will be shown to the user if they get a 404 error
static/ — this folder holds all the static files for the site (images, CSS, etc.)
static/style.css — this file holds all the website styles
blog/ — this folder holds all the blog-related templates
blog/index.html — the blog homepage
blog/dashboard.html — the user dashboard
blog/edit.html — the post edit page
blog/post.html — the page that shows a single post

Next, copy the following CSS into the blog/static/style.css file.

footer {
  text-align: center;
  font-style: italic;
  margin-top: 1em;
}

.nav {
  float: right;
}

h2 {
  margin-bottom: 2em;
}

.posts ul {
  list-style-type: none;
}

.posts a {
  font-size: 1.3em;
  text-decoration: underline;
  color: #212529;
}

.posts span {
  font-size: 1.1em;
  float: right;
}

.empty {
  font-size: 2em;
  margin-bottom: 5em;
}

.container {
  padding-top: 2em;
}

.unauthenticated p {
  font-size: 1.3em;
  text-align: center;
}

hr.bottom {
  margin-top: 4em;
}

.submit-btn {
  float: right;
}

.alert p {
  font-size: 1.1em;
}

.author {
  font-size: 1.2em;
  margin-top: 2em;
}

.body {
  margin-top: 2em;
  font-size: 1.2em;
}

.edit {
  padding-left: 0;
}

.edit a {
  text-decoration: underline;
  color: #212529;
  font-size: 1.5em;
}

.edit li {
  list-style-type: none;
  line-height: 2.5em;
}

.edit button {
  float: right;
}

.delete {
  margin-left: 1em;
}

.your-posts {
  margin-top: 2em;
}

.hidden {
  display: inline;
}

I won’t explain this as I assume you’re familiar with CSS. I’ve basically just defined some simple styles that will come into play later.

Next, let’s create the blog/templates/layout.html template. This template contains reusable HTML that all the other pages of the site will share.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css" integrity="sha384-9gVQ4dYFwwWSjIDZnLEWnxCjeSWFphJiwGPXr1jddIhOegiu1FwO5qRGvFXOdJZ4" crossorigin="anonymous">
    <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
    <title>Blog | {% block title %}{% endblock %}</title>
  </head>
  <body>
    <div class="d-flex flex-column flex-md-row align-items-center p-3 px-md-4 mb-3 bg-white border-bottom box-shadow">
      <h5 class="my-0 mr-md-auto font-weight-normal">Blog</h5>
      <nav class="my-2 my-md-0 mr-md-3">
        <a class="p-2 text-dark" href="/" title="Home">Home</a>
        {% if not g.user %}
          <a class="p-2 text-dark" href="/login">Log In / Register</a>
        {% else %}
          <a class="p-2 text-dark" href="/dashboard">Dashboard</a>
          <a class="p-2 text-dark" href="/logout">Logout</a>
        {% endif %}
      </nav>
    </div>
    <div class="container">
      {% block body %}{% endblock %}
    </div>
    <footer class="text-center">Created by <a href="https://twitter.com/rdegges">@rdegges</a>, built using <a href="https://twitter.com/okta">@okta</a>.
  </body>
</html>

Most of this page is just standard HTML. You can see with a quick glance that there’s a head tag that includes the Bootstrap UI library (to make things look decent), a navbar that will show on all the pages of the site, and a footer. Other than that, there are a couple of key elements that make this template special. Let’s analyze them.

<link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">

The link tag in the head section above uses a special function, url_for, to properly link to the style.css file you created above. This is a built-in Flask function that figures out what URL the static files will be served at based on your Flask configuration. This is a lot nicer than if you would have hardcoded something like /static/style.css, since at any point in the future you can change a Flask setting and move all your static files to a new URL.

You may have also noticed the special blog tags:

<title>Blog | {% block title %}{% endblock %}</title>

<!-- ... -->

{% block body %}{% endblock %}

These special block tags act as a placeholder for future values. Since this template will be reused across every page of our site, it would be silly if each page of the site had to have the exact same title or same body content. To work around this, you can use the block tag shown above. Child templates will be able to insert their own titles and body content into this template to generate a full page without duplicating code!

Lastly, take a look at the navbar code and the if/else statement it contains.

{% if not g.user %}
  <a class="p-2 text-dark" href="/login">Log In / Register</a>
{% else %}
  <a class="p-2 text-dark" href="/dashboard">Dashboard</a>
  <a class="p-2 text-dark" href="/logout">Logout</a>
{% endif %}

This is a Jinja2 conditional block, which works intuitively. If the variable g.user does not exist, then the user will be shown a button in the navbar that prompts them to login or register. Otherwise, the user will be shown a Dashboard and Logout button instead.

In the future, the g.user variable will contain a logged-in user account (if one exists), which is what this conditional will be checking against. But more on that later!

Next, go ahead and copy the following code into the blog/templates/403.html file.

{% extends "layout.html" %}

{% block title %}Insufficient Permissions{% endblock %}

{% block body %}
  <h1 class="text-center">Insufficient Permissions</h1>
  <p class="text-center">Mind your own business &gt;:S</p>
{% endblock %}

This is what a child template looks like. It uses the special extends tag to literally “extend” the layout.html template you just created.

In this template, the content between the block tags is inserted into the parent template (layout.html) as specified. This template, when rendered, will now display a full page without needing to duplicate any code. Pretty neat!

Next, copy the following code into the blog/templates/404.html file. This page will be shown to a user when they visit a page that isn’t found.

{% extends "layout.html" %}

{% block title %}Page Not Found{% endblock %}

{% block body %}
  <h1 class="text-center">Page Not Found</h1>
  <p class="text-center">Whatever you did, it's not working :(</p>
{% endblock %}

Now copy the following code into the blog/templates/blog/index.html file. This template will be the homepage for the blog app we’re creating. It will list the blog posts so readers can view them.

{% extends "layout.html" %}

{% block title %}Home{% endblock %}

{% block body %}
  <h2 class="text-center">Recent Posts</h2>
  {% if posts %}
    <div class="posts">
      <ul>
        {% for post in posts %}
          <div class="row">
            <div class="offset-sm-2 col-sm-8">
              <li>
                <a href="/{{ post.slug }}" title="{{ post.title }}">{{ post.title }} <span>  by {{ post.author_name }}</span></a>
              </li>
            </div>
          </div>
        {% endfor %}
      </ul>
    </div>
  {% else %}
    <p class="empty text-center">Uh-oh. There are no posts to view.</p>
  {% endif %}
{% endblock %}

Note that this template uses the for tag to loop through an array of post objects, and then generates links to each of the blog posts by using the post object properties, e.g. post.author_name, post.title, etc. Using the {{ ... }} syntax allows you to output a variable’s value into the HTML of the page.

Now copy the following code into the blog/templates/blog/dashboard.html file. This will be the dashboard that authors can use to manage their articles. It will allow them to create articles, edit articles, and delete articles.

{% extends "layout.html" %}

{% block title %}Dashboard{% endblock %}

{% block body %}
  <div class="row">
    <div class="offset-sm-2 col-sm-8">
      <h2>Create a Post</h2>
    </div>
  </div>

  {% if post %}
    <div class="row">
     <div class="offset-sm-2 col-sm-8">
       <div class="alert alert-successful text-center" role="alert">
         <p>Your new post was created successfully! <a href="/{{ post.slug }}">View it?</a>
        </div>
      </div>
    </div>
  {% endif %}

   <div class="row">
    <div class="offset-sm-2 col-sm-8">
      <form method="post">
        <div class="form-group">
          <label for="title">Post Title</label>
          <input class="form-control" id="title" type="text" name="title" placeholder="Title" required>
        </div>
        <div class="form-group">
          <label for="title">Post Body</label>
          <textarea class="form-control" id="post" name="body" rows="6" required></textarea>
        </div>
        <button class="btn btn-primary submit-btn" type="submit">Update</button>
      </form>
    </div>
  </div>

  <div class="row">
    <div class="offset-sm-2 col-sm-8">
      <h2 class="your-posts">Your Posts</h2>
      <ul class="edit">
        {% for post in posts %}
          <li>
            <a href="/{{ post.slug }}" title="{{ post.title }}">{{ post.title }}</a>
            <form class="hidden" method="post" action="/{{ post.slug }}/delete">
              <button class="btn btn-outline-danger delete">Delete</button>
            </form>
            <a href="/{{ post.slug }}/edit" title="{{ post.title }}">
              <button class="btn btn-outline-secondary">Edit</button>
            </a>
          </li>
        {% endfor %}
      </ul>
    </div>
  </div>
{% endblock %}

Let’s continue by copy the following code into the blog/templates/blog/edit.html file. This template will be displayed to the user when they want to edit one of their articles.

{% extends "layout.html" %}

{% block title %}{{ post.title }}{% endblock %}

{% block body %}
  <h2 class="text-center">Edit Post</h2>
  <div class="row">
    <div class="offset-sm-2 col-sm-8">
      <form method="post">
        <div class="form-group">
          <label for="title">Post Title</label>
          <input class="form-control" id="title" type="text" name="title" value="{{ post.title }}" required>
        </div>
        <div class="form-group">
          <label for="title">Post Body</label>
          <textarea class="form-control" id="post" name="body" rows="6" required>{{ post.body }}</textarea>
        </div>
        <button class="btn btn-primary submit-btn" type="submit">Update</button>
      </form>
    </div>
  </div>
{% endblock %}

And finally, copy the code below into the blog/templates/blog/post.html file. This template will be shown to the user when they attempt to view a blog post.

{% extends "layout.html" %}

{% block title %}{{ post.title }}{% endblock %}

{% block body %}
  <h2 class="text-center">{{ post.title }}</h2>
  <div class="row">
    <div class="offset-sm-2 col-sm-8">
      <div class="body">{{ post.body|safe }}</div>
      <p class="author">Written by {{ post.author_name }}</p>
    </div>
  </div>
{% endblock %}

And with that, we’re now done creating the templates! Yey!

Now you can’t test this out just yet (we haven’t written any code to make this stuff work), but don’t worry, we’ll get there soon.

Create the Database Models for Your Flask + Python App

The next thing we’ll do is create the necessary database models for the application.

Once the front-end templates have been built, the next complex part of an application is the data model. What data will your app be storing and referencing? I like to define these models early, so I know how to plug things together later on as the application evolves.

For this app, we’ll be building a simple blog. This means we’ll primarily be storing two pieces of data: user account data and blog post data. Because we’ll be using OpenID Connect and Okta to store our user account data, that leaves just the blog post data for us to store and manage.

A blog post in our application will require several critical pieces of data:

An id field, so we can assign each blog post a unique identifier in the database
An author_id field, so we can see what author created a blog post
A created field, so we can see at what date and time a blog post was created
A title field, so we can see what the title of each blog post is
A body field, so we can see what the content of each blog post is (this will be HTML)
A slug field, so we can determine what URL to display each blog post as (for example, a blog post titled “My Favorite Post” might be available at the URL https://ourblog.com/my-favorite-post, so “my-favorite-post” would be the slug)

Now that we know what pieces of data are critical to store, let’s set up Flask-SQLAlchemy (the ORM library we’ll use to manage the database) as well as our database model.

Initialize Flask-SQLAlchemy

To get our database hooked up, the first step is getting Flask-SQLAlchemy working.

Create a new file, blog/db.py and copy in the following code. This file will hold all of our database related code.

from datetime import datetime

from click import command, echo
from flask_sqlalchemy import SQLAlchemy
from flask.cli import with_appcontext

# Initialize SQLAlchemy with no settings
db = SQLAlchemy()

@command("init-db")
@with_appcontext
def init_db_command():
    """Initialize the database."""
    db.create_all()
    echo("Initialized the database.")

def init_app(app):
    """Initialize the Flask app for database usage."""
    db.init_app(app)
    app.cli.add_command(init_db_command)

Let’s take a look at what’s happening here.

First, we’re creating a db global object. This is what will be used to create our database models later and manage our relationship with the database. When we initialize the db object, we’re initializing the Flask-SQLAlchemy extension without actually giving it any settings or configuration. We’ll get to that soon.

Next, the init_db_command function. This is a special command that you will be able to run on the command line when you type the following.

FLASK_APP=blog flask init-db

This command runs a special method SQLAlchemy provides called create_all, which will initialize any database tables and configuration specified. Right now this won’t do anything, but once we define database models in a moment, this will become useful.

The init_db_command function is built using the click library which ships with Flask. click is a very popular library for building command line applications, like this one.

Next, the init_app function. This is meant to run from the main application initialization code, and it will properly configure the Flask-SQLAlchemy extension as well as hook up the init_db_command function to the app in the correct way.

Now that our database code has been written, copy the following code into the blog/ __init__.py file, overwriting what was there before.

from os.path import dirname, join

from flask import Flask

from . import db

app = Flask( __name__ )
app.config.from_mapping(
    SQLALCHEMY_DATABASE_URI="sqlite:///" + join(dirname(dirname( __file__ )), "database.sqlite"),
)

db.init_app(app)

What we’re doing here, in the “main” part of our application, is importing the newly created database model we built a moment ago (blog/db.py), specifying some application configuration data (to tell Flask-SQLAlchemy what sort of database we’re using), and finally, calling the special db.init_app() function we defined in the blog/db.py file, which initializes Flask-SQLAlchemy properly.

For almost all Flask apps, you’ll at some point need to specify some configuration information that gets used by extensions or helper libraries. The way you do this is via the app.config.from_mapping call above. This method allows you to define configuration data and settings that can be shared across your Flask app.

In this case, we’re specifying a setting that Flask-SQLAlchemy requires, SQLALCHEMY_DATABASE_URI, which basically tells it what type of database we’re using and how to access it. In this case, we’re going to be storing the SQLite database in a file called database.sqlite in the root of our project folder.

For this blog app, we’ll be using the SQLite database. SQLite is an incredibly popular database that stores all of its data in a single file on the disk. This makes it ideal for building portable applications. If you are building something that requires high levels of throughput and data processing, SQLite may not be the best fit… But for just about everything else, it’s not only simple — it’s very convenient, as you don’t even need a database server!

Now, if you go back and re-run your Flask application, you’ll notice that it should run fine. The only problem is that we still haven’t accomplished anything yet other than initializing the database.

Create the SQLAlchemy Database Models

Now that our database is initialized, let’s create the actual data model we need. This model will allow us to store blog post data as previously described into the SQLite database.

Open up blog/db.py and insert the following code, overwriting what was there before.

from datetime import datetime

from click import command, echo
from flask_sqlalchemy import SQLAlchemy
from flask.cli import with_appcontext

# Initialize SQLAlchemy with no settings
db = SQLAlchemy()

class Post(db.Model):
    """A blog post."""
    id = db.Column(db.Integer, primary_key=True)
    author_id = db.Column(db.Text, nullable=False)
    created = db.Column(db.DateTime, default=datetime.utcnow)
    title = db.Column(db.Text, nullable=False)
    body = db.Column(db.Text, nullable=False)
    slug = db.Column(db.Text, nullable=False, unique=True)

@command("init-db")
@with_appcontext
def init_db_command():
    """Initialize the database."""
    db.create_all()
    echo("Initialized the database.")

def init_app(app):
    """Initialize the Flask app for database usage."""
    db.init_app(app)
    app.cli.add_command(init_db_command)

What we’ve added here is the new Post class. This is a database model that tells SQLAlchemy what sort of data we’re storing (a blog post), and what fields it contains. To do this, we’re using typical relational database column types (Integer, Text, DateTime, etc.). If you aren’t familiar with SQL, you might want to check out this fantastic Khan Academy course on the subject.

Now that the database model has been defined, all we need to do is initialize the database so we can start writing and reading data from it. To do this, let’s use the new init-db command we created earlier.

FLASK_APP=blog flask init-db

If you look in the root of your project folder, you’ll now see a file called database.sqlite. This is where all of your application data will now be stored!

Set Up User Registration, User Login, etc. in Flask

Your database is now ready for action, but you still have a problem: how do you allow users to log into your website, create accounts, etc.? The answer is simple: OpenID Connect and Okta!

Step 1: Create an OpenID Connect Config File

Create a new file named client_secrets.json in the root of your project folder and insert the following code.

{
  "web": {
    "client_id": "{{ OKTA_CLIENT_ID }}",
    "client_secret": "{{ OKTA_CLIENT_SECRET }}",
    "auth_uri": "{{ OKTA_ORG_URL }}/oauth2/default/v1/authorize",
    "token_uri": "{{ OKTA_ORG_URL }}/oauth2/default/v1/token",
    "issuer": "{{ OKTA_ORG_URL }}/oauth2/default",
    "userinfo_uri": "{{ OKTA_ORG_URL }}/oauth2/default/userinfo",
    "redirect_uris": [
      "http://localhost:5000/oidc/callback"
    ]
  }
}

Be sure to replace the placeholder variables with your actual Okta information.

Replace {{ OKTA_ORG_URL }} with the Org URL on your dashboard pageReplace {{ OKTA_CLIENT_ID }} with the Client ID on your application pageReplace {{ OKTA_CLIENT_SECRET }} with the Client secret on your application page

This file will be used by the Flask-OIDC library which we’ll be configuring in a moment. These settings essentially tell the OpenID Connect library what OpenID Connect application you’re using to authenticate against, and what your authorization server API endpoints are.

The URIs above point to your newly created Okta resources so that the Flask library will be able to talk to it properly.

Step 2: Configure Flask-OIDC

Open up blog/ __init__.py and paste in the following code.

from os.path import dirname, join

from flask import Flask, g

from . import auth, db

app = Flask( __name__ )
app.config.from_mapping(
    SECRET_KEY={{ LONG_RANDOM_STRING }},
    OIDC_CLIENT_SECRETS=join(dirname(dirname( __file__ )), "client_secrets.json"),
    OIDC_COOKIE_SECURE=False,
    OIDC_CALLBACK_ROUTE="/oidc/callback",
    OIDC_SCOPES=["openid", "email", "profile"],
    OIDC_ID_TOKEN_COOKIE_NAME="oidc_token",
    SQLALCHEMY_DATABASE_URI="sqlite:///" + join(dirname(dirname( __file__ )), "database.sqlite"),
)

auth.oidc.init_app(app)
db.init_app(app)

app.register_blueprint(auth.bp)

@app.before_request
def before_request():
    """
    Load a user object into `g.user` before each request.
    """
    if auth.oidc.user_loggedin:
        g.user = auth.okta_client.get_user(auth.oidc.user_getfield("sub"))
    else:
        g.user = None

What we’re doing here is specifying settings for the Flask-OIDC library:

The OIDC_CLIENT_SECRETS setting tells Flask-OIDC where your OpenID Connect configuration file is located (the one you created in the previous section).
The OIDC_COOKIE_SECURE setting allows you to test out user login and registration in development without using SSL. If you were going to run your site publicly, you would remove this option and use SSL on your site.
The OIDC_CALLBACK_ROUTE setting tells Flask-OIDC what URL on your site will handle user login. This is a standard part of the OpenID Connect flows. This is out of scope for this article, but if you want to learn more, read our OpenID Connect primer.
The OIDC_SCOPES setting tells Flask-OIDC what data to request about the user when they log in. In this case, we’re requesting basic user information (email, name, etc.).
The SECRET_KEY setting should be set to a long, random string. This is used to secure your Flask sessions (cookies) so that nobody can tamper with them. Make sure this variable stays private. It should never be publicly exposed.

Once that configuration data has been created, we also use a (currently) undefined auth module (which we’ll get to in a moment) to initialize the Flask-OIDC library.

We then register a Blueprint (which will be discussed in the next section).

Finally, we define a special function called before_request. This function will run automatically before each user request (hence the @app.before_request decorator), and load up a user object is it is available.

Here’s how this works.

Once a user has logged in using OpenID Connect, they’ll have a session created and stored in a server-side cookie
The if auth.oidc.user_loggedin code will check to see whether or not this cookie exists and is valid. If it is, then we’ll use the okta Python library to retrieve the user’s account as a User object that we can easily work with, and assign it to the special variable g.user.
If no user is logged in, then g.user will be set to None.

The special g.user value is something that we can use to store important data our application needs, like the current user, for example. This variable is available to us to use in templates, server-side code, etc. which makes it very handy.

Step 3: Create User Login and Logout Views in Flask

Create a new file, blog/auth.py and paste in the following code. This file will hold all of our authentication related code.

from os import environ

from flask import Blueprint, redirect, url_for
from flask_oidc import OpenIDConnect
from okta import UsersClient

bp = Blueprint("auth", __name__ , url_prefix="/")
oidc = OpenIDConnect()
okta_client = UsersClient("{{ OKTA_ORG_URL }}", "{{ OKTA_AUTH_TOKEN }}")

@bp.route("/login")
@oidc.require_login
def login():
    """
    Force the user to login, then redirect them to the dashboard.
    """
    return redirect(url_for("blog.dashboard"))

@bp.route("/logout")
def logout():
    """
    Log the user out of their account.
    """
    oidc.logout()
    return redirect(url_for("blog.index"))

Be sure to substitute OKTA_ORG_URL and OKTA_AUTH_TOKEN with the appropriate Okta values.

What this file does is:

Define a special auth Blueprint. Blueprints in Flask are ways to modularize code to make it reusable in large systems. Each Blueprint has a name, a URL prefix (in this case that isn’t relevant, however), and it’s own mini application object.
Define an okta_client object. This allows us to talk to the Okta API to retrieve user data. While this isn’t strictly necessary, it allows us to more easily work with our users.
Define a login view to handle user login functionality. What these view functions do is this: when a user visits /login, if the user is already logged in (via the @oidc.require_login decorator), they’ll then be redirected to the dashboard page via the redirect(...) function call. If the user isn’t logged in, the @oidc.require_login decorator will redirect the user to the Okta authorization server and prompt them to either create a new account (user registration), or log into an existing account.
Define a logout view to handle logout functionality. If a user visits the /logout URL, their session cookie will be deleted (via the oidc.logout() call), and they’ll then be redirected to the homepage of the site.

Congratulations, you’ve now fully integrated user registration, login, and user management into your application! Not bad, right?

Define the Blog Views in Flask

So far, we’ve built the front-end templates, created the database models, and wired up user authentication. The one thing we haven’t done, however, is define the core behavior for our application: the views!

In Flask, views are functions that run when a user visits a particular URL. If a user visits /dashboard, for example, Flask needs to know what function to run and what to do to display the dashboard page to the user.

Now that we’ve figured everything else out, let’s get the views built!

First off, however, we need to update our app initialization code so our soon-to-be created blog views will work! Open blog/ __init__.py and copy in the following code.

from os.path import dirname, join

from flask import Flask, g

from . import auth, blog, db

app = Flask( __name__ )
app.config.from_mapping(
    SECRET_KEY='LONG_RANDOM_STRING',
    OIDC_CLIENT_SECRETS=join(dirname(dirname( __file__ )), "client_secrets.json"),
    OIDC_COOKIE_SECURE=False,
    OIDC_CALLBACK_ROUTE="/oidc/callback",
    OIDC_SCOPES=["openid", "email", "profile"],
    OIDC_ID_TOKEN_COOKIE_NAME="oidc_token",
    SQLALCHEMY_DATABASE_URI="sqlite:///" + join(dirname(dirname( __file__ )), "database.sqlite"),
)

auth.oidc.init_app(app)
db.init_app(app)

app.register_blueprint(auth.bp)
app.register_blueprint(blog.bp)

@app.before_request
def before_request():
    """
    Load a user object into `g.user` before each request.
    """
    if auth.oidc.user_loggedin:
        g.user = auth.okta_client.get_user(auth.oidc.user_getfield("sub"))
    else:
        g.user = None

@app.errorhandler(404)
def page_not_found(e):
    """Render a 404 page."""
    return render_template("404.html"), 404

@app.errorhandler(403)
def insufficient_permissions(e):
    """Render a 403 page."""
    return render_template("403.html"), 403

We haven’t changed much here, except to import a blog module and register it as a Blueprint. We’ve also defined two additional functions: one that will be run if a user visits a non-existent page (a 404), or if a user visits a page they don’t have permission to access (a 403).

Next, create the file blog/blog.py and paste in the following code.

from flask import Blueprint, abort, g, render_template, redirect, request, url_for
from slugify import slugify

from .auth import oidc, okta_client
from .db import Post, db

bp = Blueprint("blog", __name__ , url_prefix="/")

def get_posts(author_id):
    """
    Return all of the posts a given user created, ordered by date.
    """
    return Post.query.filter_by(author_id=author_id).order_by(Post.created.desc())

@bp.route("/")
def index():
    """
    Render the homepage.
    """
    posts = Post.query.order_by(Post.created.desc())
    posts_final = []

    for post in posts:
        u = okta_client.get_user(post.author_id)
        post.author_name = u.profile.firstName + " " + u.profile.lastName
        posts_final.append(post)

    return render_template("blog/index.html", posts=posts_final)

@bp.route("/dashboard", methods=["GET", "POST"])
@oidc.require_login
def dashboard():
    """
    Render the dashboard page.
    """
    if request.method == "GET":
        return render_template("blog/dashboard.html", posts=get_posts(g.user.id))

    post = Post(
        title=request.form.get("title"),
        body=request.form.get("body"),
        author_id = g.user.id,
        slug = slugify(request.form.get("title"))
    )

    db.session.add(post)
    db.session.commit()

    return render_template("blog/dashboard.html", posts=get_posts(g.user.id))

@bp.route("/<slug>")
def view_post(slug):
    """View a post."""
    post = Post.query.filter_by(slug=slug).first()
    if not post:
        abort(404)

    u = okta_client.get_user(post.author_id)
    post.author_name = u.profile.firstName + " " + u.profile.lastName

    return render_template("blog/post.html", post=post)

@bp.route("/<slug>/edit", methods=["GET", "POST"])
def edit_post(slug):
    """Edit a post."""
    post = Post.query.filter_by(slug=slug).first()

    if not post:
        abort(404)

    if post.author_id != g.user.id:
        abort(403)

    post.author_name = g.user.profile.firstName + " " + g.user.profile.lastName
    if request.method == "GET":
        return render_template("blog/edit.html", post=post)

    post.title = request.form.get("title")
    post.body = request.form.get("body")
    post.slug = slugify(request.form.get("title"))

    db.session.commit()
    return redirect(url_for(".view_post", slug=post.slug))

@bp.route("/<slug>/delete", methods=["POST"])
def delete_post(slug):
    """Delete a post."""
    post = Post.query.filter_by(slug=slug).first()

    if not post:
        abort(404)

    if post.author_id != g.user.id:
        abort(403)

    db.session.delete(post)
    db.session.commit()

    return redirect(url_for(".dashboard"))

I realize that’s a lot to take in, so let’s go through it one function at a time.

The get_posts Helper Function

def get_posts(author_id):
    """
    Return all of the posts a given user created, ordered by date.
    """
    return Post.query.filter_by(author_id=author_id).order_by(Post.created.desc())

This function is designed as a helper. What it does is query the database, looking for any posts written by a specific author, and returns them in descending order by date.

This will be useful later when displaying the user dashboard page, as we’ll only want to show users blog posts they’ve created on their dashboard page. This function allows us to easily get a list of those posts without duplicating code.

The index View

@bp.route("/")
def index():
    """
    Render the homepage.
    """
    posts = Post.query.order_by(Post.created.desc())
    posts_final = []

    for post in posts:
        u = okta_client.get_user(post.author_id)
        post.author_name = u.profile.firstName + " " + u.profile.lastName
        posts_final.append(post)

    return render_template("blog/index.html", posts=posts_final)

This view function is the homepage of the site. This function will run each time a user visits the / URL. What it does is:

Get a list of all blog posts on the site, ordered by date descending
Loops through each post and extracts the author’s ID
Uses the Okta Python library to retrieve the corresponding user’s first name and last name (this will allow us to display the author’s information to blog readers)
Renders the blog/index.html template we created much earlier, which displays a list of all blog posts, and who wrote them

The dashboard View

@bp.route("/dashboard", methods=["GET", "POST"])
@oidc.require_login
def dashboard():
    """
    Render the dashboard page.
    """
    if request.method == "GET":
        return render_template("blog/dashboard.html", posts=get_posts(g.user.id))

    post = Post(
        title=request.form.get("title"),
        body=request.form.get("body"),
        author_id = g.user.id,
        slug = slugify(request.form.get("title"))
    )

    db.session.add(post)
    db.session.commit()

    return render_template("blog/dashboard.html", posts=get_posts(g.user.id))

This view function is the user dashboard page. This function will run each time a user visits the /dashboard URL. What it does is:

If the user is viewing the dashboard, it just renders the blog/dashboard.html template we defined earlier. This template shows the user a list of their previously created blog posts, and also allows the user to create new blog posts if they want by filling out a form.
If the user is submitting a form (trying to create a new post), this view will create a new Post object and save it to the database. Along the way, it will use the python-slugify library mentioned earlier to convert the title of the post into a URL-friendly format.

The view_post View

@bp.route("/<slug>")
def view_post(slug):
    """View a post."""
    post = Post.query.filter_by(slug=slug).first()
    if not post:
        abort(404)

    u = okta_client.get_user(post.author_id)
    post.author_name = u.profile.firstName + " " + u.profile.lastName

    return render_template("blog/post.html", post=post)

This view function renders the post page. This function will run each time a user visits the /<some-blog-slug-here> URL. What it does is:

Look in the database for a blog post with the slug specified in the URL. If one can be found, it’ll render that page and show the blog to the user.
If no matching blog post can be found, the user will see a 404 page and nothing more

The edit_post View

@bp.route("/<slug>/edit", methods=["GET", "POST"])
def edit_post(slug):
    """Edit a post."""
    post = Post.query.filter_by(slug=slug).first()

    if not post:
        abort(404)

    if post.author_id != g.user.id:
        abort(403)

    post.author_name = g.user.profile.firstName + " " + g.user.profile.lastName
    if request.method == "GET":
        return render_template("blog/edit.html", post=post)

    post.title = request.form.get("title")
    post.body = request.form.get("body")
    post.slug = slugify(request.form.get("title"))

    db.session.commit()
    return redirect(url_for(".view_post", slug=post.slug))

This view function allows users to edit a post. This function will run each time a user visits the /<some-blog-slug-here>/edit URL. What it does is:

Look in the database for a blog post with the slug specified in the URL. If one can be found, it’ll update the post accordingly (assuming the user has the correct permissions). If the user doesn’t have the correct permissions, they’ll be shown a 403 page.
If no matching blog post can be found, the user will see a 404 page and nothing more

The delete_post View

@bp.route("/<slug>/delete", methods=["POST"])
def delete_post(slug):
    """Delete a post."""
    post = Post.query.filter_by(slug=slug).first()

    if not post:
        abort(404)

    if post.author_id != g.user.id:
        abort(403)

    db.session.delete(post)
    db.session.commit()

    return redirect(url_for(".dashboard"))

This view function allows users to delete a post. This function will run each time a user visits the /<some-blog-slug-here>/delete URL. What it does is:

Look in the database for a blog post with the slug specified in the URL. If one can be found, it’ll delete the post from the database (assuming the user has the correct permissions). If the user doesn’t have the correct permissions, they’ll be shown a 403 page.
If no matching blog post can be found, the user will see a 404 page and nothing more

And… That’s it!

Test Your New Flask + Python App

Now that your app is fully built, go test it out! Open up http://localhost:5000, create an account, log in, etc.

As you can see, building a Flask app with user registration, login, databases, templates, etc. doesn’t have to be hard!

If you’re interested in learning more about web authentication and security, you may also want to check out some of our other articles, or follow us on Twitter — we write a lot about interesting web development topics.

Here are three of my favorites:

Flask Tutorial: Simple User Registration and Login

Randall Degges — Thu, 12 Jul 2018 05:00:00 +0000

Flask is my favorite Python web framework. It’s minimal, it’s fast, and most of all: it’s fun. I love almost everything about Flask development, with one exception: user management.

User management in Flask, just like in many other web frameworks, is difficult. I can’t tell you how many times I’ve created user databases, set up groups and roles, integrated social login providers, handled password reset workflows, configured multi-factor authentication workflows, etc. Even awesome libraries like Flask-Login and Flask-Security can be difficult to setup and maintain over long periods of time as your requirements change.

In this short tutorial, I’ll show you what I think is one of the best and simplest ways to manage users for your Flask web applications: OpenID Connect. If you haven’t heard of it, OpenID Connect is an open protocol that makes managing user authentication and authorization simple.

Follow along below and you’ll learn how to:

Create a simple Flask website
Use OpenID Connect for user authentication and authorization
Use Okta as your authorization server to store and manage your user accounts in a simple, straightforward way

If you’d like to skip the tutorial and just check out the fully built project, you can go view it on GitHub.

Initialize Authentication for Your Flask App with Okta

Okta is a free-to-use API service that stores user accounts, and makes handling user authentication, authorization, social login, password reset, etc. — simple. Okta utilizes open standards like OpenID Connect to make integration seamless.

In this tutorial, you’ll use Okta to store the user accounts for your web app, and you’ll use OpenID Connect to talk to Okta to handle the logistics around authentication and authorization.

To get started, you first need to go create a free Okta developer account: https://developer.okta.com/signup/. Once you’ve created your account and logged in, follow the steps below configure Okta and then you’ll be ready to write some code!

Step 1: Store Your Org URL

Step 2: Create an OpenID Connect Application

To create a new application browse to the Applications tab and click Add Application.

Next, click the Web platform option (since this project is a web app).

On the settings page, enter the following values:

Name : Simple Flask App
Base URIs : http://localhost:5000
Login redirect URIs : http://localhost:5000/oidc/callback

You can leave all the other values unchanged.

Now that your application has been created, copy down the Client ID and Client secret values on the following page, you’ll need them later when we start writing code.

Step 3: Create an Authentication Token

Create, update, and delete users
Create, update, and delete groups
Manage application settings
Etc.

Step 4: Enable User Registration

In your Okta dashboard, you’ll notice a small button labeled < > Developer Console at the top-left of your page. Hover over that button and select the Classic UI menu option that appears.

Next, hover over the Directory tab at the top of the page then select the Self-Service Registration menu item. On this page click the Enable Registration button.

On the configuration page, leave all the settings as their default values, except for two:

Disable the User must verify email address to be activated. checkbox. This setting removes the requirement for new users to verify their email address before being allowed to access your web app.
Set the Default redirect option by clicking the Custom URL radio box and entering http://localhost:5000/dashboard as the value. This setting tells the authorization server where to redirect users after they’ve successfully created a new account on your site.

Once you’ve clicked Save , the last thing you need to is switch back to the developer console.

Hover over the Classic UI button at the top right of the page and select the < > Developer Console menu item from the drop-down.

Install Python and Flask Dependencies

The first thing you need to do in order to initialize your Flask app is install all of the required dependencies. If you don’t have Python installed on your computer already, please go install it now.

NOTE : I also strongly recommend you get familiar with pipenv when you get some time. It’s a great tool that makes managing Python dependencies very simple.

Now install the dependencies required for this application.

pip install Flask>=1.0.0
pip install flask-oidc>=1.4.0
pip install okta==0.0.4

Initialize Your Flask App

Now that the dependencies are installed, let’s start by creating a simple Flask app. We’ll build on this simple “hello, world!” app until we’ve got all our functionality included.

Create an app.py file and enter the following code:

from flask import Flask

app = Flask( __name__ )

@app.route('/')
def index():
    return 'hello, world!'

Open the terminal and run the following code to start up your new Flask app.

FLASK_APP=app.py flask run

Once your Flask app is running, go visit http://localhost:5000 in the browser to see the hello world message!

As you can see from the small file above, building a minimalist app with Flask can be really simple. All you need to do is:

Import the Flask library
Create a Flask app object
Define a function (called a view) that runs when a particular URL is requested by a user (in this case, the / URL)

Not bad, right?

Create an Index and Dashboard View in Flask

The next step to building a simple Flask app is creating a homepage and dashboard page. The homepage is what will be shown to the user when they visit the / URL, and the dashboard page (/dashboard) will be shown to the user once they’ve logged into their account.

When I’m building web apps, I like to define my templates and views first so I can get the hard part out of the way (design isn’t my strong suit).

To get started, open up you app.py file from before and modify it to look like the following:

from flask import Flask, render_template

app = Flask( __name__ )

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/dashboard")
def dashboard():
    return render_template("dashboard.html")

You’ll notice that you now have two view functions defined: index (which renders the homepage) and dashboard (which renders the dashboard page). Both of the view functions are calling the render_template Flask function, which is responsible for displaying an HTML page to the user.

Now, you obviously haven’t created those HTML templates yet, so let’s do that next!

Templates in Flask are built using the Jinja2 templating language. If you’re familiar with HTML, it should look natural.

Let’s start by creating the template files we’ll need.

mkdir templates
touch templates/{layout.html,index.html,dashboard.html}

All templates in Flask should live inside the templates folder.

Next, open up the templates/layout.html file and enter the following code.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css" integrity="sha384-9gVQ4dYFwwWSjIDZnLEWnxCjeSWFphJiwGPXr1jddIhOegiu1FwO5qRGvFXOdJZ4" crossorigin="anonymous">
    <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
    <title>Simple Flask App | {% block title %}{% endblock %}</title>
  </head>
  <body>
    <div class="d-flex flex-column flex-md-row align-items-center p-3 px-md-4 mb-3 bg-white border-bottom box-shadow">
      <h5 class="my-0 mr-md-auto font-weight-normal">Simple Flask App</h5>
      <nav class="my-2 my-md-0 mr-md-3">
        <a class="p-2 text-dark" href="/" title="Home">Home</a>
        {% if not g.user %}
          <a class="p-2 text-dark" href="/login">Log In / Register</a>
        {% else %}
          <a class="p-2 text-dark" href="/dashboard">Dashboard</a>
          <a class="p-2 text-dark" href="/logout">Logout</a>
        {% endif %}
      </nav>
    </div>
    <div class="container">
      {% block body %}{% endblock %}
    </div>
    <footer class="text-center">Created by <a href="https://twitter.com/rdegges">@rdegges</a>, built using <a href="https://twitter.com/okta">@okta</a>.
  </body>
</html>

This layout.html file is our base template. It’s basically a building block that all the other templates will inherit from. By defining our common, shared HTML in this file, we can avoid writing redundant HTML everywhere else. Yey!

Now, this file contains all the basic stuff you might expect:

A simple, Bootstrap-based layout
A nav bar (that contains some special Jinja2 logic)
A special Jinja2 body
A footer

Let’s take a look at one interesting part of the template.

{% if not g.user %}
  <a class="p-2 text-dark" href="/login">Log In / Register</a>
{% else %}
  <a class="p-2 text-dark" href="/dashboard">Dashboard</a>
  <a class="p-2 text-dark" href="/logout">Logout</a>
{% endif %}

Anything in a Jinja2 tag (the {% … %} stuff) will be compiled by Flask before being shown to the user. In the example above, we’re basically telling Flask that if the object g.user exists, we should render a dashboard and logout link in the navbar, but if no g.user object exists, we should show a login button instead.

We’re doing this because eventually we’re going to have the user’s account accessible via the g.user object and we want the navbar to be smart in regards to what the user sees.

The next interesting part of the template is the body tag:

<div class="container">
  {% block body %}{% endblock %}
</div>

The block Jinja2 tag allows us to inject content from a child template into this parent template. This is what lets us build complex HTML pages without writing redundant code.

Now that the layout is defined, let’s create the homepage. Open the templates/index.html file and insert the following code.

{% extends "layout.html" %}

{% block title %}Home{% endblock %}

{% block body %}
  <h1 class="text-center">Simple Flask App</h1>
  <div class="row">
    <div class="col-sm-6 offset-sm-3">
      <div class="jumbotron">
        Welcome to this simple Flask example app. It shows you how to easily
        enable users to register, login, and logout of a Flask web app using <a
           href="https://developer.okta.com">Okta</a>.
      </div>
    </div>
  </div>
{% endblock %}

The {% extends "layout.html" %} tag is what tells the template engine that this template depends on the layout.html template to work.

Everything inside the block tags is then injected back into the parent template from before. By combining these two things together, you’re now able to have a fully rendered homepage!

Next, go ahead and place the following code into the templates/dashboard.html file.

{% extends "layout.html" %}

{% block title %}Dashboard{% endblock %}

{% block body %}
  <h1 class="text-center">Dashboard</h1>
  <div class="row">
    <div class="col-sm-8 offset-sm-2">
      <p>Welcome to the dashboard, {{ g.user.profile.firstName }}!</p>
      <p>Your user information has been pulled from the <code>g.user</code>
      object, which makes accessing your user information simple. Your first
      name, for example, is available via the <code>g.user.profile.firstName</code>
      property. Your user id (<code>{{ g.user.id }}</code>), is pulled from the <code>g.user.id</code> property!</p>
    </div>
  </div>
{% endblock %}

This template works in the same way, except it also outputs some variables. For instance, the {{ g.user.id }} value will output that ID value into the HTML template directly. These variables will eventually be available once we hook up the OpenID Connect library.

The last thing you need to do before testing things is add a bit of CSS to make things look nicer.

mkdir static
touch static/style.css

Open static/style.css and copy in the following CSS.

h1 {
  margin: 1em 0;
}

footer {
  padding-top: 2em;
}

Finally, now that your templates have been created, go test them out!

Visit http://localhost:5000 and you should see your beautiful new website.

Add User Registration and Login to Your Flask App

Now that the UI for the app is finished, let’s get the interesting stuff working: user registration and login.

Step 1: Create an OpenID Connect Config File

Create a new file named client_secrets.json in the root of your project folder and insert the following code.

{
  "web": {
    "client_id": "{{ OKTA_CLIENT_ID }}",
    "client_secret": "{{ OKTA_CLIENT_SECRET }}",
    "auth_uri": "{{ OKTA_ORG_URL }}/oauth2/default/v1/authorize",
    "token_uri": "{{ OKTA_ORG_URL }}/oauth2/default/v1/token",
    "issuer": "{{ OKTA_ORG_URL }}/oauth2/default",
    "userinfo_uri": "{{ OKTA_ORG_URL }}/oauth2/default/userinfo",
    "redirect_uris": [
      "http://localhost:5000/oidc/callback"
    ]
  }
}

Be sure to replace the placeholder variables with your actual Okta information.

Replace {{ OKTA_ORG_URL }} with the Org URL on your dashboard page
Replace {{ OKTA_CLIENT_ID }}} with the Client ID on your application page
Replace {{ OKTA_CLIENT_SECRET }} with the Client secret on your application page

The URIs above simply point to your newly created Okta resources so that the Flask library will be able to talk to it properly.

Step 2: Configure Flask-OIDC

Open up app.py and paste in the following code.

from flask import Flask, render_template
from flask_oidc import OpenIDConnect

app = Flask( __name__ )
app.config["OIDC_CLIENT_SECRETS"] = "client_secrets.json"
app.config["OIDC_COOKIE_SECURE"] = False
app.config["OIDC_CALLBACK_ROUTE"] = "/oidc/callback"
app.config["OIDC_SCOPES"] = ["openid", "email", "profile"]
app.config["SECRET_KEY"] = "{{ LONG_RANDOM_STRING }}"
oidc = OpenIDConnect(app)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/dashboard")
def dashboard():
    return render_template("dashboard.html")

What we’re doing here is configuring the Flask-OIDC library.

The OIDC_CLIENT_SECRETS setting tells Flask-OIDC where your OpenID Connect configuration file is located (the one you created in the previous section).
The OIDC_COOKIE_SECURE setting allows you to test out user login and registration in development without using SSL. If you were going to run your site publicly, you would remove this option and use SSL on your site.
The OIDC_CALLBACK_ROUTE setting tells Flask-OIDC what URL on your site will handle user login. This is a standard part of the OpenID Connect flows. This is out of scope for this article, but if you want to learn more, go read our OpenID Connect primer.
The OIDC_SCOPES setting tells Flask-OIDC what data to request about the user when they log in. In this case, we’re requesting basic user information (email, name, etc.).
The SECRET_KEY setting should be set to a long, random string. This is used to secure your Flask sessions (cookies) so that nobody can tamper with them. Make sure this variable stays private. It should never be publicly exposed.

Finally, after all the configuration is finished, we initialize the Flask-OIDC extension by creating the oidc object.

Step 3: Inject the User Into Each Request

Open up app.py and paste in the following code.

from flask import Flask, render_template, g
from flask_oidc import OpenIDConnect
from okta import UsersClient

app = Flask( __name__ )
app.config["OIDC_CLIENT_SECRETS"] = "client_secrets.json"
app.config["OIDC_COOKIE_SECURE"] = False
app.config["OIDC_CALLBACK_ROUTE"] = "/oidc/callback"
app.config["OIDC_SCOPES"] = ["openid", "email", "profile"]
app.config["SECRET_KEY"] = "{{ LONG_RANDOM_STRING }}"
app.config["OIDC_ID_TOKEN_COOKIE_NAME"] = "oidc_token"
oidc = OpenIDConnect(app)
okta_client = UsersClient("{{ OKTA_ORG_URL }}", "{{ OKTA_AUTH_TOKEN }}")

@app.before_request
def before_request():
    if oidc.user_loggedin:
        g.user = okta_client.get_user(oidc.user_getfield("sub"))
    else:
        g.user = None

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/dashboard")
def dashboard():
    return render_template("dashboard.html")

What we’re doing here is importing the okta Python library, and using it to define the okta_client object. This client object will be used to retrieve a robust User object that you can use to:

Identify the currently logged in user
Make changes to the user’s account
Store and retrieve user information

Make sure you replace {{ OKTA_ORG_URL }} and {{ OKTA_AUTH_TOKEN }} with the values you wrote down in the first section of this tutorial. These two variables are mandatory so the okta library can communicate with the Okta API service.

@app.before_request
def before_request():
    if oidc.user_loggedin:
        g.user = okta_client.get_user(oidc.user_getfield("sub"))
    else:
        g.user = None

The code above is where the magic happens. This function will be executed each time a user makes a request to view a page on the site before the normal view code runs. What this function does is:

Check to see whether or not a user is logged in via OpenID Connect or not (the oidc.user_loggedin value is provided by the Flask-OIDC library)
If a user is logged in, it will grab the user’s unique user ID from the user’s session, then use that ID to fetch the user object from the Okta API

In all cases, there will be a newly created value: g.user. In Flask, you can store request data on the g object, which can be accessed from anywhere: view code, templates, etc. This makes it a convenient place to store something like a user object so it can easily be used later on.

Step 4: Enable User Registration, Login, and Logout

Open up app.py and insert the following code.

from flask import Flask, render_template, g, redirect, url_for
from flask_oidc import OpenIDConnect
from okta import UsersClient

app = Flask( __name__ )
app.config["OIDC_CLIENT_SECRETS"] = "client_secrets.json"
app.config["OIDC_COOKIE_SECURE"] = False
app.config["OIDC_CALLBACK_ROUTE"] = "/oidc/callback"
app.config["OIDC_SCOPES"] = ["openid", "email", "profile"]
app.config["SECRET_KEY"] = "{{ LONG_RANDOM_STRING }}"
app.config["OIDC_ID_TOKEN_COOKIE_NAME"] = "oidc_token"
oidc = OpenIDConnect(app)
okta_client = UsersClient("{{ OKTA_ORG_URL }}", "{{ OKTA_AUTH_TOKEN }}")

@app.before_request
def before_request():
    if oidc.user_loggedin:
        g.user = okta_client.get_user(oidc.user_getfield("sub"))
    else:
        g.user = None

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/dashboard")
@oidc.require_login
def dashboard():
    return render_template("dashboard.html")

@app.route("/login")
@oidc.require_login
def login():
    return redirect(url_for(".dashboard"))

@app.route("/logout")
def logout():
    oidc.logout()
    return redirect(url_for(".index"))

There are only a few things different here:

You now have a login view. The view will redirect the user to Okta (the OpenID Connect provider) to register or login. This is powered by the @oidc.require_login decorator which is provided by the Flask-OIDC library. Once the user has been logged in, they’ll be redirected to the dashboard page.
The logout view is also present. This simply logs the user out using the oidc.logout() method and then redirects the user to the homepage.

And with that, your application is now fully functional!

Test Your New Flask App

Now that your app is fully built, go test it out! Open up http://localhost:5000, create an account, log in, etc.

As you can see, building a Flask app with user registration, login, etc. doesn’t have to be hard!

Here are two of my favorites:

Tutorial: Build a Basic CRUD App with Node.js

Randall Degges — Thu, 28 Jun 2018 05:00:00 +0000

Node.js is eating the world. Many of the largest companies are building more and more of their websites and API services with Node.js, and there’s no sign of a slowdown. I’ve been working with Node.js since 2012 and have been excited to see the community and tooling grow and evolve — there’s no better time to get started with Node.js development than right now.

This tutorial will take you step-by-step through building a fully functional Node.js website. Along the way you’ll learn about Express.js, the most popular web framework, user authentication with OpenID Connect, locking down routes to enforce login restrictions, and performing CRUD operations with a database (creating, reading, updating, and deleting data). This tutorial uses the following technologies but doesn’t require any prior experience:

Node.js
Express.js and Pug
Okta’s OIDC-middleware and Node SDK
Sequelize.js, a popular ORM for working with databases in Node.js

If you’d like to skip the tutorial and just check out the fully built project, you can go view it on GitHub.

About Express.js

Express.js is the most popular web framework in the Node.js ecosystem. It’s incredibly simple and minimalistic. Furthermore, there are thousands of developer libraries that work with Express, making developing with it fun and flexible.

Regardless of whether you’re trying to build a website or an API, Express.js provides tons of features and a nice developer experience.

Through this tutorial, you’ll be building a simple blog. The blog you build will have a homepage that lists the most recent posts, a login page where users can authenticate, a dashboard page where users can create and edit posts, and logout functionality.

The blog will be built using Express.js, the user interface will be built using Pug, the authentication component will be handled by Okta, and the blog post storage and database management will be handled by Sequelize.js.

Create Your Express.js App

Before we begin, make sure you have a recent version of Node.js installed. If you don’t already have Node.js installed, please visit this page and install it for your operating system before continuing.

To get your project started quickly you can leverage express-generator. This is an officially maintained program that allows you to easily scaffold an Express.js website with minimal effort.

To install express-generator run:

npm install -g express-generator

Next, you need to initialize your project. To do this, use the newly installed express-generator program to bootstrap your application:

express --view pug blog
cd blog
npm install
npm start

The above command will initialize a new project called blog , move you into the new project folder, install all project dependencies, and start up a web server.

Once you’ve finished running the commands above, point your favorite browser to http://localhost:3000 and you should see your application running:

Initialize Authentication

Dealing with user authentication in web apps is a huge pain for every developer. This is where Okta shines: it helps you secure your web applications with minimal effort. To get started, you’ll need to create an OpenID Connect application in Okta. Sign up for a forever-free developer account (or log in if you already have one).

Once you’ve logged in and land on the dashboard page, copy down the Org URL pictured below. You will need this later.

Then create a new application by browsing to the Applications tab and clicking Add Application.

Next, click the Web platform option (since our blog project is a web app).

On the settings page, enter the following values:

Name : Blog
Base URIs : http://localhost:3000
Login redirect URIs : http://localhost:3000/users/callback

You can leave all the other values unchanged.

Now that your application has been created, copy down the Client ID and Client secret values on the following page, you’ll need them soon.

Finally, create a new authentication token. This will allow your app to talk to Okta to retrieve user information, among other things. To do this, click the API tab at the top of the page followed by the Create Token button. Give your token a name, preferably the same name as your application, then click Create Token. Copy down this token value as you will need it soon.

Install Dependencies

The first thing you need to do in order to initialize your Express.js app is install all of the required dependencies.

npm install express@4.16.3
npm install @okta/oidc-middleware@0.1.2
npm install @okta/okta-sdk-nodejs@1.1.0
npm install sqlite3@4.0.1
npm install sequelize@4.38.0
npm install async@2.6.1
npm install slugify@1.3.0
npm install express-session@1.15.6

Define Database Models with Sequelize

The first thing I like to do when starting a new project is define what data my application needs to store, so I can model out exactly what data I’m handling.

Create a new file named ./models.js and copy the following code inside of it.

const Sequelize = require("sequelize");

const db = new Sequelize({
  dialect: "sqlite",
  storage: "./database.sqlite"
});

const Post = db.define("post", {
  title: { type: Sequelize.STRING },
  body: { type: Sequelize.TEXT },
  authorId: { type: Sequelize.STRING },
  slug: { type: Sequelize.STRING }
});

db.sync();

module.exports = { Post };

This code initializes a new SQLite database that will be used to store the blog data and also defines a model called Post which stores blog posts in the database. Each post has a title, a body, an author ID, and a slug field.

The title field will hold the title of a post, eg: “A Great Article”
The body field will hold the body of the article as HTML, eg: “
My first post!
”
The authorId field will store the author’s unique ID. This is a common pattern in relational databases: store just the identifier of a linked resource so you can look up the author’s most up-to-date information later.
The slug field will store the URL-friendly version of the post’s title, eg: “a-great-article”

NOTE : If you’ve never used SQLite before, it’s amazing. It’s a database that stores your data in a single file. It’s great for building applications that don’t require a large amount of concurrency, like this simple blog.

The call to db.sync(); at the bottom of the file will automatically create the database and all of the necessary tables once this JavaScript code runs.

Initialize Your Express.js App

The next thing I like to do after defining my database models is to initialize my application code. This typically involves:

Configuring application settings
Installing middlewares that provide functionality to the application
Handling errors
Etc.

Open the ./app.js file and replace its contents with the following code.

const createError = require("http-errors");
const express = require("express");
const logger = require("morgan");
const path = require("path");
const okta = require("@okta/okta-sdk-nodejs");
const session = require("express-session");
const ExpressOIDC = require("@okta/oidc-middleware").ExpressOIDC;

const blogRouter = require("./routes/blog");
const usersRouter = require("./routes/users");

const app = express();
const client = new okta.Client({
  orgUrl: "{yourOktaOrgUrl}",
  token: "{yourOktaToken}"
});

app.set("views", path.join(__dirname, "views"));
app.set("view engine", "pug");

// Middleware
app.use(logger("dev"));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(express.static(path.join(__dirname, "public")));

const oidc = new ExpressOIDC({
  issuer: "{yourOktaOrgUrl}/oauth2/default",
  client_id: "{yourOktaClientId}",
  client_secret: "{yourOktaClientSecret}",
  redirect_uri: "http://localhost:3000/users/callback",
  scope: "openid profile",
  routes: {
    login: {
      path: "/users/login"
    },
    callback: {
      path: "/users/callback",
      defaultRedirect: "/dashboard"
    }
  }
});

app.use(session({
  secret: "{aLongRandomString}",
  resave: true,
  saveUninitialized: false
}));

app.use(oidc.router);

app.use((req, res, next) => {
  if (!req.userinfo) {
    return next();
  }

  client.getUser(req.userinfo.sub)
    .then(user => {
      req.user = user;
      res.locals.user = user;
      next();
    });
});

// Routes
app.use("/", blogRouter);
app.use("/users", usersRouter);

// Error handlers
app.use(function(req, res, next) {
  next(createError(404));
});

app.use(function(err, req, res, next) {
  res.locals.message = err.message;
  res.locals.error = req.app.get("env") === "development" ? err : {};

  res.status(err.status || 500);
  res.render("error");
});

module.exports = app;

Be sure to replace the placeholder variables with your actual Okta information.

Replace {yourOktaOrgUrl} with the Org URL on your dashboard page
Replace {yourOktaClientId} with the Client ID on your application page
Replace {yourOktaClientSecret} with the Client secret on your application page
Replace {aLongRandomString} with a long random string (just mash your fingers on the keyboard for a second)

Let’s take a look at what this code does.

Initialize Node.js Middlewares

Middlewares in Express.js are functions that run on every request. There are many open source middlewares you can install and use to add functionality to your Express.js applications. The code below uses several popular Express.js middlewares, as well as defines some new ones.

// Middleware
app.use(logger("dev"));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(express.static(path.join(__dirname, "public")));

const oidc = new ExpressOIDC({
  issuer: "{yourOktaOrgUrl}/oauth2/default",
  client_id: "yourOktaClientId}",
  client_secret: "{yourOktaClientSecret}",
  redirect_uri: "http://localhost:3000/users/callback",
  scope: "openid profile",
  routes: {
    login: {
      path: "/users/login"
    },
    callback: {
      path: "/users/callback",
      defaultRedirect: "/dashboard"
    }
  }
});

app.use(session({
  secret: "{aLongRandomString}",
  resave: true,
  saveUninitialized: false
}));

app.use(oidc.router);

app.use((req, res, next) => {
  if (!req.userinfo) {
    return next();
  }

  client.getUser(req.userinfo.sub)
    .then(user => {
      req.user = user;
      res.locals.user = user;

      next();
    });
});

The first few middlewares are all standard stuff: they enable logging, parse form data, and serve static files. The interesting thing to take note of is the use of the ExpressOIDC middleware.

This middleware handles the OpenID Connect authentication logic of the application which supports login, logout, etc. The settings being passed into the ExpressOIDC middleware are configuration options which dictate what URLs are used to log the user into the application, and where the user will be redirected once they’ve been logged in.

The next middleware is the session middleware. This middleware is responsible for managing user cookies and remembering who a user is. The secret it takes must be a long random string you define and keep private. This secret makes it impossible for attackers to tamper with cookies.

The oidc.router middleware uses the settings you defined when creating ExpressOIDC to create routes for handling user authentication. Whenever a user visits /users/login, for instance, they’ll be taken to a login page. This line of code is what makes that possible.

Finally, there’s a custom middleware. This middleware creates a req.user object that you will be able to use later on to more easily access a currently logged in user’s personal information.

Initialize Node.js Routes

The route code tells Express.js what code to run when a user visits a particular URL. Here is the route code from the ./app.js.

// Routes
app.use("/", blogRouter);
app.use("/users", usersRouter);

This code tells Express.js that in our (yet to be created) blog and user route files there are functions that should be executed when certain URLs are hit. If a user visits a URL starting with /users, Express.js will look for other matching URLs in the user routes file. If a user visits any URLs starting with the / URL, Express.js will look in the blog routes file to see what to do.

Initialize Error Handlers

The last bit of code in our app above is the error-handling middlewares.

// Error handlers
app.use(function(req, res, next) {
  next(createError(404));
});

app.use(function(err, req, res, next) {
  res.locals.message = err.message;
  res.locals.error = req.app.get("env") === "development" ? err : {};

  res.status(err.status || 500);
  res.render("error");
});

These middlewares will run if any 4XX or 5XX type errors occur. In both cases, they will render a simple web page to the user showing them the error.

Create Express.js Views

Views in Express.js are the equivalent of HTML templates—they’re the place you store front-end code and logic. The views you’ll use in this project will use the Pug templating language which is one of the most popular.

Remove your existing views by running the following command.

rm views/*

Next, create a ./views/layout.pug file. This is a base “layout” template that all other templates will inherit from. It defines common HTML, includes the Bootstrap CSS library, and also defines a simple navigation menu.

block variables
  - var selected = 'Home'

doctype html
html(lang='en')
  head
    meta(charset='utf-8')
    meta(name='viewport' content='width=device-width, initial-scale=1, shrink-to-fit=no')
    link(rel='stylesheet' href='https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css' integrity='sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm' crossorigin='anonymous')
    link(rel='stylesheet', href='/stylesheets/style.css')
    title Blog: #{title}
  body
    div.d-flex.flex-column.flex-md-row.align-items-center.p-3.px-md-4.mb-3.bg-white.border-bottom.box-shadow
      h5.my-0.mr-md-auto.font-weight-normal Blog
      nav.my-2.my-md-0.mr-md-3
        a.p-2.text-dark(href="/", title="Home") Home

        if user == undefined
          a.p-2.text-dark(href="/users/login") Log In
        else
          a.p-2.text-dark(href="/dashboard") Dashboard
          a.p-2.text-dark(href="/users/logout") Logout
    .container
      block content

    hr.bottom
    footer.
      Built with #[a(href='https://expressjs.com/') Express.js], login powered by #[a(href='https://developer.okta.com/') Okta].

Next, create the ./views/error.pug file. This page will be shown when an error occurs.

extends layout

block content
  h1= message
  h2= error.status
  pre #{error.stack}

Next, create the ./views/unauthenticated.pug file. This page will be shown when a user tries to visit a page but they aren’t logged in.

extends layout

block variables
  - var title = "Unauthenticated"

block content
  .unauthenticated
    h2.text-center Whoops!
    p.
      You must be signed in to view this page. Please #[a(href="/users/login", title="Login") login] to view this page.

Now define the ./views/index.pug template. This is the homepage of the website and lists all the current blog posts ordered by date.

extends layout

block variables
  - var title = "Home"

block content
  h2.text-center Recent Posts

  if posts == null
    p.empty.text-center Uh oh. There are no posts to view!

  .posts
    ul
      each post in posts
        .row
          .offset-sm-2.col-sm-8
            li
              a(href="/" + post.slug, title=post.title)= post.title
              span   by #{post.authorName}

The next view to define is ./views/post.pug which displays a single blog post.

extends layout

block variables
  - var title = post.title

block content
  h2.text-center= title

  .row
    .offset-sm-2.col-sm-8
      .body !{post.body}
      p.author Written by #{post.authorName}

Now create the file ./views/edit.pug which contains the blog post editing page markup.

extends layout

block variables
  - var title = post.title

block content
  h2.text-center Edit Post

  .row
    .offset-sm-2.col-sm-8
      form(method="post")
        .form-group
          label(for="title") Post Title
          input.form-control#title(type="text", name="title", value=post.title, required)
        .form-group
          label(for="body") Post Body
          textarea.form-control#post(name="body", rows="6", required)= post.body
        button.btn.btn-primary.submit-btn(type="submit") Update

  .row
    .offset-sm-2.col-sm-8
      .body !{post.body}
      p.author Written by #{post.authorName}

Finally, create ./views/dashboard.pug which will render the dashboard page that users will see once they’ve logged in. This page allows a user to create a new post as well as edit and delete their existing posts.

extends layout

block variables
  - var title = "Dashboard"

block content
  .row
    .offset-sm-2.col-sm-8
      h2 Create a Post

  if post != undefined
    .row
      .offset-sm-2.col-sm-8
        .alert.alert-success(role="alert").text-center
          p Your new post was created successfully! #[a(href="/" + post.slug) View it?]

  .row
    .offset-sm-2.col-sm-8
      form(method="post")
        .form-group
          label(for="title") Post Title
          input.form-control#title(type="text", name="title", placeholder="Title", required)
        .form-group
          label(for="body") Post Body
          textarea.form-control#post(name="body", rows="6", required)
        button.btn.btn-primary.submit-btn(type="submit") Submit

  .row
    .offset-sm-2.col-sm-8
      h2.your-posts Your Posts
      ul.edit
        each post in posts
          li
            a(href="/" + post.slug, title=post.title)= post.title
            form.hidden(method="post", action="/" + post.slug + "/delete")
              button.btn.btn-outline-danger.delete Delete
            a(href="/" + post.slug + "/edit", title=post.title)
              button.btn.btn-outline-secondary Edit

Create Styles

I’m not much of a web designer (that’s why I like using Bootstrap), but every project needs a bit of visual flair. I’ve done my best to create some simple CSS styling.

Since CSS is straightforward and not the focus of this tutorial, you can simply copy the CSS below into the ./public/stylesheets/style.css file.

footer {
  text-align: center;
  font-style: italic;
  margin-top: 1em;
}

.nav {
  float: right;
}

h2 {
  margin-bottom: 2em;
}

.posts ul {
  list-style-type: none;
}

.posts a {
  font-size: 1.3em;
  text-decoration: underline;
  color: #212529;
}

.posts span {
  font-size: 1.1em;
  float: right;
}

.empty {
  font-size: 2em;
  margin-bottom: 5em;
}

.container {
  padding-top: 2em;
}

.unauthenticated p {
  font-size: 1.3em;
  text-align: center;
}

hr.bottom {
  margin-top: 4em;
}

.submit-btn {
  float: right;
}

.alert p {
  font-size: 1.1em;
}

.author {
  font-size: 1.2em;
  margin-top: 2em;
}

.body {
  margin-top: 2em;
  font-size: 1.2em;
}

.edit {
  padding-left: 0;
}

.edit a {
  text-decoration: underline;
  color: #212529;
  font-size: 1.5em;
}

.edit li {
  list-style-type: none;
  line-height: 2.5em;
}

.edit button {
  float: right;
}

.delete {
  margin-left: 1em;
}

.your-posts {
  margin-top: 2em;
}

.hidden {
  display: inline;
}

Create Routes

Routes are where the real action happens in any Express.js application. They dictate what happens when a user visits a particular URL.

To get started, remove the existing routes that the express-generator application created.

rm routes/*

Next, create the two route files that you’ll need.

touch routes/{blog.js,users.js}

The ./routes/blog.js file will contain all of the routes related to blog functionality. The ./routes/users.js file will contain the routes related to user functionality. While you could always put all your logic in the main ./app.js file, keeping your routes in separate purpose-based files is a good idea.

Create User Routes

Since Okta’s oidc-middleware library is already handling user authentication for the application, there isn’t a lot of user-facing functionality we need to create.

The only route you need to define that relates to user management is a logout route — this route will log the user out of their account and redirect them to the homepage of the site. While the oidc-middleware library provides a logout helper, it doesn’t create an actual route.

Open up the ./routes/users.js file and copy in the following code.

const express = require("express");

const router = express.Router();

// Log a user out
router.get("/logout", (req, res, next) => {
  req.logout();
  res.redirect("/");
});

module.exports = router;

The way to understand this route is simple. When a user visits the /logout URL, a function will run that:

Uses the oidc-middleware library to log the user out of their accountRedirects the now logged-out user to the homepage of the site

Create Blog Routes

Since the application you’re building is a blog, the last big piece of functionality you need add is the actual blog route code. This is what will dictate how the blog actually works: how to create posts, edit posts, delete posts, etc.

Open up the ./routes/blog.js file and copy in the following code. Don’t worry if it looks like a lot all at once - I’ll walk you through each route in detail below.

const async = require("async");
const express = require("express");
const okta = require("@okta/okta-sdk-nodejs");
const sequelize = require("sequelize");
const slugify = require("slugify");

const models = require("../models");

const client = new okta.Client({
  orgUrl: "{yourOktaOrgUrl}",
  token: "{yourOktaToken}"
});
const router = express.Router();

// Only let the user access the route if they are authenticated.
function ensureAuthenticated(req, res, next) {
  if (!req.user) {
    return res.status(401).render("unauthenticated");
  }

  next();
}

// Render the home page and list all blog posts
router.get("/", (req, res) => {
  models.Post.findAll({
    order: sequelize.literal("createdAt DESC")
  }).then(posts => {
    let postData = [];

    async.eachSeries(posts, (post, callback) => {
      post = post.get({ plain: true });
      client.getUser(post.authorId).then(user => {
        postData.push({
          title: post.title,
          body: post.body,
          createdAt: post.createdAt,
          authorName: user.profile.firstName + " " + user.profile.lastName,
          slug: post.slug
        });
        callback();
      }).catch(err => {
        postData.push({
          title: post.title,
          body: post.body,
          createdAt: post.createdAt,
          slug: post.slug
        });
        callback();
      });
    }, err => {
      return res.render("index", { posts: postData });
    });
  });
});

// Render the user dashboard
router.get("/dashboard", ensureAuthenticated, (req, res, next) => {
  models.Post.findAll({
    where: {
      authorId: req.user.id
    },
    order: sequelize.literal("createdAt DESC")
  }).then(posts => {
    let postData = [];

    posts.forEach(post => {
      postData.push(post.get({ plain: true }));
    });

    return res.render("dashboard", { posts: postData });
  });
});

// Create a new post
router.post("/dashboard", ensureAuthenticated, (req, res, next) => {
  models.Post.create({
    title: req.body.title,
    body: req.body.body,
    authorId: req.user.id,
    slug: slugify(req.body.title).toLowerCase()
  }).then(newPost => {
    models.Post.findAll({
      where: {
        authorId: req.user.id
      },
      order: sequelize.literal("createdAt DESC")
    }).then(posts => {
      let postData = [];

      posts.forEach(post => {
        postData.push(post.get({ plain: true }));
      });

      res.render("dashboard", { post: newPost, posts: postData });
    });
  });
});

// Render the edit post page
router.get("/:slug/edit", ensureAuthenticated, (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug,
      authorId: req.user.id
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post = post.get({ plain: true });
    client.getUser(post.authorId).then(user => {
      post.authorName = user.profile.firstName + " " + user.profile.lastName;
      res.render("edit", { post });
    });
  });
});

// Update a post
router.post("/:slug/edit", ensureAuthenticated, (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug,
      authorId: req.user.id
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post.update({
      title: req.body.title,
      body: req.body.body,
      slug: slugify(req.body.title).toLowerCase()
    }).then(() => {
      post = post.get({ plain: true });
      client.getUser(post.authorId).then(user => {
        post.authorName = user.profile.firstName + " " + user.profile.lastName;
        res.redirect("/" + slugify(req.body.title).toLowerCase());
      });
    });
  });
});

// Delete a post
router.post("/:slug/delete", (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug,
      authorId: req.user.id
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post.destroy();
    res.redirect("/dashboard");
  });
});

// View a post
router.get("/:slug", (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post = post.get({ plain: true });
    client.getUser(post.authorId).then(user => {
      post.authorName = user.profile.firstName + " " + user.profile.lastName;
      res.render("post", { post });
    });
  });
});

module.exports = router;

NOTE : Make sure you substitute in your values for the placeholder variables towards the top of this file. You need to replace {yourOktaOrgUrl} and {yourOktaToken} with the appropriate values.

This is a lot of code, so let’s take a look at each route and how it works.

Create an Authentication Helper

The first function you’ll notice in the blog routes is the ensureAuthenticated function.

// Only let the user access the route if they are authenticated.
function ensureAuthenticated(req, res, next) {
  if (!req.user) {
    return res.status(401).render("unauthenticated");
  }

  next();
}

This function is a special middleware you’ll use later on that will render the unauthenticated.pug view you created earlier to tell the user they don’t have access to view the page unless they log in.

This middleware works by looking for the req.user variable which, if it doesn’t exist, means that the user is not currently logged in. This will be helpful later on to make sure that only logged in users can access certain pages of the site (for instance, the page that allows a user to create a new blog post).

Create the Homepage

The index route (aka: “homepage route”) is what will run when the user visits the root of the site. It will display all blog posts ordered by date and not much else. Here’s the route code.

// Render the home page and list all blog posts
router.get("/", (req, res) => {
  models.Post.findAll({
    order: sequelize.literal("createdAt DESC")
  }).then(posts => {
    let postData = [];

    async.eachSeries(posts, (post, callback) => {
      post = post.get({ plain: true });
      client.getUser(post.authorId).then(user => {
        postData.push({
          title: post.title,
          body: post.body,
          createdAt: post.createdAt,
          authorName: user.profile.firstName + " " + user.profile.lastName,
          slug: post.slug
        });
        callback();
      }).catch(err => {
        postData.push({
          title: post.title,
          body: post.body,
          createdAt: post.createdAt,
          slug: post.slug
        });
        callback();
      });
    }, err => {
      return res.render("index", { posts: postData });
    });
  });
});

The way this works is by first using Sequelize.js to retrieve a list of all blog posts from the database ordered by the createdAt field. Whenever a new blog post is stored in the database, Sequelize.js automatically assigns it both a createdAt and updatedAt time field.

Once a list of posts have been returned from the database you will iterate over each post retrieving it in JSON format, then use Okta’s Node SDK to retrieve the author’s information via the authorId field.

Finally, you’ll build an array consisting of all the blog posts alongside the author’s name, and will render the index.pug template which then takes that data and displays the full web page.

Create the Dashboard Routes

The dashboard page is the first page users will see after logging in. It will:

Allow users to create a new blog post
Show users a list of their previously created blog posts
Provide buttons that allow a user to edit or delete previously created blog posts

Here’s the code that powers the dashboard route.

// Render the user dashboard
router.get("/dashboard", ensureAuthenticated, (req, res, next) => {
  models.Post.findAll({
    where: {
      authorId: req.user.id
    },
    order: sequelize.literal("createdAt DESC")
  }).then(posts => {
    let postData = [];

    posts.forEach(post => {
      postData.push(post.get({ plain: true }));
    });

    return res.render("dashboard", { posts: postData });
  });
});

// Create a new post
router.post("/dashboard", ensureAuthenticated, (req, res, next) => {
  models.Post.create({
    title: req.body.title,
    body: req.body.body,
    authorId: req.user.id,
    slug: slugify(req.body.title).toLowerCase()
  }).then(newPost => {
    models.Post.findAll({
      where: {
        authorId: req.user.id
      },
      order: sequelize.literal("createdAt DESC")
    }).then(posts => {
      let postData = [];

      posts.forEach(post => {
        postData.push(post.get({ plain: true }));
      });

      res.render("dashboard", { post: newPost, posts: postData });
    });
  });
});

Note that there are technically two routes here. The first route function is run when a user issues a GET request for the /dashboard page, while the second route is run when a user issues a POST request for the /dashboard page.

The first route retrieves a list of all blog posts this user has created, then renders the dashboard page. Note how it uses the ensureAuthenticated middleware we created earlier. By inserting the ensureAuthenticated middleware into the route, this guarantees that this route code will only execute if a currently logged in user is visiting this page.

If a user chooses to create a new blog post, that will trigger a POST request to the /dashboard URL, which is what will eventually run the second dashboard route shown above.

This route uses Sequelize.js to create a new database entry storing the blog posts and author details, then renders the dashboard page once more.

Create the Edit Routes

The edit routes control the pages that allow a user to edit one of their existing blog posts. The code that makes this work is shown below.

// Render the edit post page
router.get("/:slug/edit", ensureAuthenticated, (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug,
      authorId: req.user.id
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post = post.get({ plain: true });
    client.getUser(post.authorId).then(user => {
      post.authorName = user.profile.firstName + " " + user.profile.lastName;
      res.render("edit", { post });
    });
  });
});

// Update a post
router.post("/:slug/edit", ensureAuthenticated, (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug,
      authorId: req.user.id
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post.update({
      title: req.body.title,
      body: req.body.body,
      slug: slugify(req.body.title).toLowerCase()
    }).then(() => {
      post = post.get({ plain: true });
      client.getUser(post.authorId).then(user => {
        post.authorName = user.profile.firstName + " " + user.profile.lastName;
        res.redirect("/" + slugify(req.body.title).toLowerCase());
      });
    });
  });
});

These routes by matching a variable pattern URL. If the user visits a URL that looks like /<something>/edit, then the edit route will run. Because the URL pattern in the route is defined as /:slug/edit, Express.js will pass along the URL route in the req.params.slug variable so you can use it.

These routes handle rendering the edit page as well as updating existing posts when needed.

Create the Delete Route

The delete route is simple: if a user sends a POST request to the URL /<post-url>/delete, then Sequelize.js will destroy the post from the database.

Here’s the code that makes this work.

// Delete a post
router.post("/:slug/delete", (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug,
      authorId: req.user.id
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post.destroy();
    res.redirect("/dashboard");
  });
});

Create the Display Route

The display route is the simplest of them all: it renders a specific blog post on a page. It works much like the other routes above by using variable URL patterns.

When a user visits a URL like /my-great-article, this route will run, query the database for any blog posts whose slug is my-great-article, then display that post on a page.

// View a post
router.get("/:slug", (req, res, next) => {
  models.Post.findOne({
    where: {
      slug: req.params.slug
    }
  }).then(post => {
    if (!post) {
      return res.render("error", {
        message: "Page not found.",
        error: {
          status: 404,
        }
      });
    }

    post = post.get({ plain: true });
    client.getUser(post.authorId).then(user => {
      post.authorName = user.profile.firstName + " " + user.profile.lastName;
      res.render("post", { post });
    });
  });
});

Test Your New CRUD App!

By this point, you’ve built a fully functional Node.js website using Express.js and Okta. To test it out, run the following command to start up your web server then visit http://localhost:3000 in the browser.

npm start

If you were able to copy the code properly, you should be able to log in, create posts, edit posts, and delete posts.

Do More With Node!

I hope you enjoyed building a simple CRUD app with Node.js and Express.js. I’ve found that Express.js has a rich ecosystem of libraries and tools to make web development simple and fun. You can find the source code for the example created in this tutorial on GitHub.

If you’d like to learn more about building web apps in Node, you might want to check out these other great posts:

If you’re interested in learning more about how the underlying authentication components work (OpenID Connect), you may be interested in our OpenID Connect primer series which explains everything you need to know about OpenID Connect as a developer.

Finally, please follow @oktadev on Twitter to find more great resources like this, request other topics for us to write about, and follow along with our new open source libraries and projects!

And… If you have any questions, please leave a comment below!

What Happens If Your JWT Is Stolen?

Randall Degges — Wed, 20 Jun 2018 05:00:00 +0000

All of us know what happens if our user credentials (email and password) are discovered by an attacker: they can log into our account and wreak havoc. But a lot of modern applications are using JSON Web Tokens (JWTs) to manage user sessions—what happens if a JWT is compromised? Because more and more applications are using token-based authentication, this question is increasingly relevant to developers and critical to understand if you’re building any sort of application that uses token-based authentication.

To help explain the concepts fully, I’ll walk you through what tokens are, how they’re used, and what happens when they’re stolen. Finally: I’ll cover what you should actually do if your token has been stolen, and how to prevent this in the future.

This post was inspired by this StackOverflow question. My response to that question has become one of my most popular responses on StackOverflow to date!

What is a Token?

A token in the context of web development is nothing more than an arbitrary value that represents a session. Tokens can be strings like “abc123” or randomly generated IDs like “48ff796e-8c8a-46b9-9f25-f883c14734ea”.

A token’s purpose is to help a server remember who somebody is. Take API services, for example: if you have an API key that lets you talk to an API service from your server-side application, that API key is what the API service uses to “remember” who you are, look up your account details, and allow (or disallow) you from making a request. In this example, your API key is your “token”, and it allows you to access the API.

However, when most people talk about tokens today, they’re actually referring to JWTs (for better or worse).

What is a JSON Web Token (JWT)?

JSON Web Tokens are special types of tokens that are structured in such a way that makes them convenient to use over the web. They have a handful of defining traits:

They are represented as normal strings. Here’s a real JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlJhbmRhbGwgRGVnZ2VzIiwiaWF0IjoxNTE2MjM5MDIyfQ.sNMELyC8ohN8WF_WRnRtdHMItOVizcscPiWsQJX9hmw

Because JWTs are just URL safe strings, they’re easy to pass around via URL parameters, etc.

They contain JSON-encoded data. This means you can have your JWT store as much JSON data as you want, and you can decode your token string into a JSON object. This makes them convenient for embedding information.
They’re cryptographically signed. Understanding how this works is a topic unto itself. For now, just know that it means any trusted party who has a JWT can tell whether or not the token has been modified or changed. This means if your application or API service generates a token that says someone is a “free” user and someone later alters the token to say they are an “admin” user, you’ll be able to detect this and act accordingly. This property makes JWTs useful for sharing information between parties over the web where trust is difficult to come by.

Here’s a small code snippet which creates and validates a JWT in JavaScript using the njwt library. This example is purely here to show you at a glance how to create a JWT, embed some JSON data in it, and validate it.

const njwt = require("njwt");
const secureRandom = require("secure-random");

// This is a "secret key" that the creator of the JWT must keep private.
var key = secureRandom(256, { type: "Buffer" });

// This is the JSON data embedded in the token.
var claims = {
  iss: "https://api.com",
  sub: "someuserid",
  scope: "freeUser",
  favoriteColor: "black"
};

// Create a JWT
var jwt = njwt.create(claims, key);

// Log the JWT
console.log(jwt);
// Jwt {
// header: JwtHeader { typ: 'JWT', alg: 'HS256' },
// body:
// JwtBody {
// iss: 'https://api.com',
// sub: 'someuserid',
// scope: 'freeUser',
// favoriteColor: 'black',
// jti: '903c5447-ebfd-43e8-8f4d-b7cc5922f5ec',
// iat: 1528824349,
// exp: 1528827949 },
// signingKey: <Buffer 9c e9 48 a7 b3 c9 87 be 5f 59 90 a5 08 02 9b 98 5c 5e 1c 29 3f b0 33 c5 8c c8 f9 c8 3e 35 f0 7c 20 a0 aa 65 cc 98 47 b6 31 c5 5c d6 4e 6e 25 29 2b d3 ... > }

// The JWT in compacted form (ready for sending over the network)
var token = jwt.compact();

// Log the compacted JWT
console.log(jwt.compact());
// eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5jb20iLCJzdWIiOiJzb21ldXNlcmlkIiwic2NvcGUiOiJmcmVlVXNlciIsImZhdm9yaXRlQ29sb3IiOiJibGFjayIsImp0aSI6IjkwM2M1NDQ3LWViZmQtNDNlOC04ZjRkLWI3Y2M1OTIyZjVlYyIsImlhdCI6MTUyODgyNDM0OSwiZXhwIjoxNTI4ODI3OTQ5fQ.y7ad-nUsHAkI8a5bixYnr_v0vStRqnzsT4bbWGAM2vw

// Verify the JWT using the secret key
njwt.verify(token, key, (err, verifiedJwt) => {
  if (err) throw err;
  console.log("The JWT has been verified and can be trusted!");
  // The JWT has been verified and can be trusted!
});

How are JSON Web Tokens Used?

JWTs are typically used as session identifiers for web applications, mobile applications, and API services. But, unlike traditional session identifiers which act as nothing more than a pointer to actual user data on the server-side, JWTs typically contain user data directly.

The principal reason JWTs have become popular in recent years (having only been around since 2014) is that they can contain arbitrary JSON data. The touted benefit of a JWT over a traditional session ID is that:

JWTs are stateless and can contain user data directly
Because JWTs are stateless, no server-side session needs to be implemented (no session database, session cache, etc.)

Because JWTs are stateless, when a server-side application receives a JWT, it can validate it using only the “secret key” that was used to create it — thereby avoiding the performance penalty of talking to a database or cache on the backend, which adds latency to each request.

With that said, let’s take a look at how a JWT would typically be used in a modern web application.

A client (a browser or mobile client, typically) will visit some sort of login page
The client will send their credentials to the server-side application
The server-side application will validate the user’s credentials, typically an email address and password, then generate a JWT that contains the user’s information. The information embedded in the JWT will typically be:
The user’s first and last name
The user’s email address or username
The user’s ID (for server-side lookups, if necessary)
The user’s permissions (what are they allowed to do?)
Any other data that is relevant to the application being used
The server-side application will return this token to the client
The client will then store this token so that it can be used to identify itself in the future. For web applications, this might mean the client stores the token in HTML5 Local Storage. For server-side API clients, this might mean storing the token on disk or in a secret store.
When the client makes requests to the server in the future, it will embed the JWT in the HTTP Authorization header to identify itself
When the server-side application receives a new incoming request, it will check to see if an HTTP Authorization header exists, and if so, it will parse out the token and validate it using the “secret key”
Finally, the server-side application will process the request if the token is valid and the cycle will be complete

In short: JWTs are used to identify a client. They are keys to the kingdom as far as the client is concerned.

What Happens if Your JSON Web Token is Stolen?

In short: it’s bad, real bad.

Because JWTs are used to identify the client, if one is stolen or compromised, an attacker has full access to the user’s account in the same way they would if the attacker had instead compromised the user’s username and password.

For instance, if an attacker gets ahold of your JWT, they could start sending requests to the server identifying themselves as you and do things like make service changes, user account updates, etc. Once an attacker has your JWT it is game over.

BUT , there is one thing that makes a stolen JWT slightly less bad than a stolen username and password: timing. Because JWTs can be configured to automatically expire after a set amount of time (a minute, an hour, a day, whatever), attackers can only use your JWT to access the service until it expires.

In theory, that sounds great, right? One of the ways token authentication is said to make authentication more “secure” is via short-lived tokens. That’s one of the core reasons token-based authentication has really taken off in recent years: you can automatically expire tokens and mitigate the risk of relying on forever-cached “stateless” tokens.

In the security world, after all, relying on cached data to make sensitive decisions like who can log into a service and what they can do is considered a bad thing. Because tokens are stateless and allow for some speed improvements over traditional session authentication, the only way in which they can remain somewhat “secure” is by limiting their lifespan so they don’t cause too much harm when compromised.

The only problem here is that if an attacker was able to steal your token in the first place, they’re likely able to do it once you get a new token as well. The most common ways this happens is by man-in-the-middling (MITM) your connection or getting access to the client or server directly. And unfortunately, in these scenarios, even the shortest-lived JWTs won’t help you at all.

In general, tokens should be treated like passwords and protected as such. They should never be publicly shared and should be kept in secure data stores. For browser-based applications, this means never storing your tokens in HTML5 Local Storage and instead storing tokens in server-side cookies that are not accessible to JavaScript.

In general, token-based authentication does not provide any additional security over typical session-based authentication relying on opaque session identifiers. While there are certainly a good number of use cases for token-based authentication, knowing how the technology works and where your weak spots are is essential.

Another interesting thing to consider is that in some cases, a stolen JWT can actually be worse than a stolen username and password.

Let’s pretend, for a moment, that your username and password have been compromised. In this scenario, if the app you’re logging into is protected with multi-factor authentication, an attacker needs to bypass additional identity proofing mechanisms in order to gain access to your account.

While guessing or brute-forcing a username and password is a very realistic scenario, being able to compromise a user’s mutli-factor authentication setup can be quite difficult. Bypassing factors like app-based authorization, SMS verification, face ID, touch ID, etc., is a significantly more challenging than guessing a user’s password.

Because of this, a compromised JWT can actually be a greater security risk than a compromised username and password. Imagine the scenario above where the app a user logs into is protected by multi-factor authentication. Once the user logs in and verifies themselves via multi-factor, they are assigned a JWT to prove who they are. If that JWT is stolen, the attacker no longer needs to bypass MFA directly (like they would have to if they only had the user’s username and password)—they can now directly make requests as the user without additional identity proofing. Quite a big risk.

What to Do if Your JWT is Stolen

Once a JWT has been stolen, you’ll be in a bad situation: an attacker can now impersonate a client and access your service without the client’s consent. But, even though you’re in a bad situation, you’ve still got to make the most out of it.

Here are a number of steps to take if a client’s token has been stolen. These recommendations are not suitable for every type of app, but should provide you with some good ideas to help you recover from this security incident:

Revoke compromised tokens immediately. If you’re using a revocation list on your server to invalidate tokens, revoking a token can instantly boot the attacker out of your system until they get hold of a new token. While it is a temporary solution, it will make the attacker’s life slightly more difficult.
Force your client to change their password immediately. In the context of a web or mobile app, force your user to reset their password immediately, preferably through some sort of multi-factor authentication flow like the ones Okta provides. Forcing a user to change their password can potentially keep attackers out of their account in the event that an attacker tries to use a compromised token to modify user login credentials. By requiring multi-factor authentication, you can have more confidence that the user resetting their credentials is who they say they are and not an attacker.
Inspect the client’s environment. Was the user’s phone stolen so an attacker has access to their pre-authenticated mobile app? Was the client accessing your service from a compromised device like a mobile phone or infected computer? Discovering how the attacker got a hold of the token is the only way to fully understand what went wrong.
Inspect your server-side environment. Was an attacker able to compromise the token from your end? If so, this might involve a lot more work to fix, but the earlier you get started the better.

Once you’ve gone through these steps, you should hopefully have a better understanding of how the token was compromised and what needs to be done to prevent it from happening in the future.

How to Detect Token Compromise

When token compromise does happen, it can cause major problems. Particularly if you (as a service provider) aren’t able to quickly detect that an attacker has compromised a client’s token.

What if you were able to automatically identify when a token was compromised? That would dramatically improve your service’s security, as you could proactively prevent suspicious requests from being fulfilled, thereby protecting your service and your users.

While not easy, this is absolutely possible. Modern machine learning toolkits like TensorFlow allow you to build functional (although complex) pipelines to detect unusual patterns and proactively take charge of the situation.

For example, you could use machine learning to detect unusual client locations. Let’s say you run a website, and your user has logged in from San Francisco and has been making requests for several hours. If you notice that requests start coming from a different geographical region a short time later, you can immediately prevent those requests from being fulfilled, revoke the tokens, and reach out to the user to reset their password, etc.

In a similar manner, you could use machine learning to detect unusual client behavior. If a token is compromised, it’s likely that an attacker will take steps to abuse your service in some way. If you have a user who typically makes five requests per minute on your site, but all of a sudden you notice a massive uptick where the user is making 50+ requests per minute, that might be a good indicator that an attacker has gotten a hold of a user’s token, so you can revoke the tokens and reach out to the user to reset their password.

Pattern detection and recognition through machine learning is a fantastic, modern way to handle some of these more complicated problems.

This is precisely what we do here at Okta — we run an API service that allows you to store user accounts in our service, and we provide developer libraries to handle things like authentication, authorization, social login, single sign-on, multi-factor authentication, etc. When users log into apps powered by Okta, we analyze a number of data points to detect if an account has been compromised, prompt for multi-factor authentication, perform user outreach, etc.

There’s a lot of complexity involved in being proactive about your security, but it’s far better to be prepared than unprepared.

Shameless Plug : If you haven’t checked out our API service, it’s free to use and really fun! You can create an account here: https://developer.okta.com/signup/. And… If you do happen to give it a go, I’d love to hear your thoughts, so please hit me up with any feedback about Okta, token authentication, or JSON Web Tokens. And finally, please follow @oktadev Twitter — we tweet about a lot of interesting security related topics like this.

Happy hacking,

-Randall

How to Prevent Your Users from Using Breached Passwords

Randall Degges — Mon, 11 Jun 2018 05:00:00 +0000

Not too long ago, the National Institute of Standards and Technology (NIST) officially recommended that user-provided passwords be checked against existing data breaches. Today I’m going to show you how you can easily add this functionality to any website you run using PassProtect, an open-source developer library I created specifically for this purpose.

Why Check User Passwords?

The new NIST recommendations mean that every time a user gives you a password, it’s your responsibility as a developer to check their password against a list of breached passwords and prevent the user from using a previously breached password.

This is a big deal in the security community because for many years now, as more and more websites have been breached, attackers have started downloading the breached user credentials and using them to attempt to compromise accounts elsewhere.

For instance, let’s say that your password, “fdsah35245!~!3”, was breached in the well-known Sony data breach back in 2014. Once those passwords were leaked, attackers would download the compromised passwords and use them to try to log into other user’s accounts.

An attacker might, for example, try to log into user accounts using your leaked password because they know that this was a real password that someone was using, and the likelihood of other people using it is (you included) is high.

To combat this, the officially recommended NIST solution is that you check each user-provided password to ensure it isn’t one of these leaked credentials — thereby reducing the odds that an attacker will be able to easily guess user credentials on your site.

How to Get Access to Breached Passwords

The only problem with the NIST recommendation is that it is hard to implement. In order to check a user’s password against a list of breached passwords you need to have a massive database of every set of leaked credentials. This is not only impractical, but a risk on many levels (security, legal, compliance).

To help developers adopt this new NIST recommendation, Troy Hunt created the free service Have I Been Pwned which aggregates all data breaches into a massive database.

Have I Been Pwned allows you to access breached data by either:

Downloading the breached data hashes directly: https://haveibeenpwned.com/Passwords (scroll down on the page to find the download links), or
Using the free and anonymous API: https://haveibeenpwned.com/API/v2

The Have I Been Pwned API allows you to make as many requests as you want, which makes it particularly useful for checking to see if your users’ passwords have been breached.

How to Easily Check Your Users’ Passwords

In order to make it easy for you to check your users’ passwords against the Have I Been Pwned database, I recently created the passprotect-js developer library.

It’s designed as a simple JavaScript library that can be dropped into any web page (anywhere on the page), that will check your users’ passwords against the Have I Been Pwned API service and inform the user if the password they’re using has been involved in a breach:

PassProtect is:

Fast : the entire library is 16k (gzipped).
Mobile friendly : it renders great on devices of all sizes.
Informative : it will explain to users that the password they’re attempting to use has been breached.
Not annoying : it won’t repeatedly annoy the user about the same password over and over again in the current session.
Secure : no passwords are ever stored or shared over the network. PassProtect uses k-Anonymity which means that the only thing that is sent over the network are the first 5 characters of the password hash.

To use PassProtect, all you need to do is drop the following script tag somewhere into the pages on your site:

<script src="https://cdn.passprotect.io/passprotect.min.js"></script>

I hope that by providing some simple tooling we can help developers adopt the new NIST recommendations and promote better overall web security.

Please hit me up if you have any questions or comments!

PS : If you’d like to enable PassProtect’s functionality on every single website you use, you can always go install the PassProtect Chrome extension

And... If you like PassProtect, you might also like the Okta API service. The Okta API stores user accounts for the websites, mobile apps, and API services you’re building and makes it easy to handle things like authentication, authorization, etc. It has an awesome free plan for developers (like you), and you can create a new Okta account and give it a try here: https://developer.okta.com/signup/.

Static Sites vs CMS

Randall Degges — Thu, 07 Jun 2018 05:00:00 +0000

There's a frequent debate amongst development and marketing teams at companies around the world about whether or not their blog or website should be managed through a content management system (CMS) like Wordpress, Drupal, Squarespace, etc. or through a static site generator like Jekyll or Hugo. I've been blogging since 2006, writing websites since 2002, and I've built just about every possible type of website. Today I'd like to explain why static sites are the superior choice in almost every possible circumstance.

Disclaimer: This advice is specifically for web teams comprised of technical people (mainly developers). If your company doesn't have technical staff I still hope you'll find this information useful, but my advice may not apply.

So, why are static sites the best?

Static Sites are Fast

There are no faster websites in the world than websites built using static site generators. This is a fact.

The reason this is true is because dynamic websites, like those powered by Wordpress and Drupal, require that you (the site creator) have a web server running some code (PHP in this case), which responds to incoming web requests, then displays some content (a blog post, etc).

This is a very slow way of doing things, because it means that for each user who visits the site, the PHP code running behind the scenes need to start up, talk to a database, potentially talk to one (or more) caching servers, and execute a lot of logic before being able to render or display the page.

When you use a static site generator like Jekyll or Hugo, however, these tools take your content (your articles, your HTML, etc.) and run some code once to transform them into their final output formats: HTML, CSS, and JavaScript. This way, a visitor to your site is sent the static page files directly without any processing.

This is much faster and simpler.

Fun Fact: Googlebot and all of Google’s search ranking algorithms heavily favor fast websites over slow ones. When two sites have similar content, but one is faster: the faster one will usually have a higher page rank. See: https://moz.com/blog/how-website-speed-actually-impacts-search-ranking for details.

Static Sites are Secure

CMS systems (especially those built on PHP like Wordpress and Drupal) have abysmal security records. It can be incredibly difficult to maintain a CMS, keep it up-to-date, and constantly apply security patches to ensure it won't be easily abused by attackers. Unless you're an expert in the CMS and spend all your time managing it, security issues are bound to crop up.

Google "Drupal hack" or "Wordpress hack" to see what I mean. Millions of Drupal and Wordpress sites are compromised all the time. Here are some examples:

There are hundreds of tools that anyone can easily download and run which attempt to compromise existing Wordpress and Drupal sites automatically, by trying all previously known vulnerabilities against the CMS systems, looking for holes.

This is such a common occurrence that CMS systems like Wordpress and Drupal require specialized hosting systems to ensure this does not happen, and that the scope of security vulnerabilities (when discovered) are minimized as much as possible. The amount of maintenance required to keep a Wordpress / Drupal site secure is a job on its own.

Static sites, on the other hand, are impossible to hack: there is no code running, and thus no vulnerabilities to exploit! For a security company like Okta, where security is fundamental to the company's mission and objective, this is a great benefit.

Static Sites are Friendly for Developers

At Okta, our developer documentation and blog are primarily written / edited / managed by a technical group of people. Using Git and Git tools are inherently native to the team. If your company's site is managed by a primarily technical audience, some subset of this may also be true.

Static site generator tools are well known in the developer community at large. They carry a very positive reputation and almost everyone is familiar with them. Using one is a sign that an organization understands engineers and engineering problems, and is committed to providing quality user experiences.

As web teams continue to scale out the amount of contributors / editors / staff that are working on web projects, sticking to the 80/20 rule is paramount: get 80% of the benefit with 20% of the work. Static site generators are the way to go here:

They are easy to understand for developers and non-technical users alike.
With very minimal instruction ANYONE in the organization can contribute. There is a very low barrier to entry.
They allow for much more controlled editorial than CMS systems do, something that is particularly important when writing technical content.
They allow for more precise editing (eg: code blocks, technical project testing, etc.) These things are not easy to accomplish in CMS systems using their web editors.

Most developers enjoy working with static site generators, and are much happier using those than CMS systems.

For more info: google "Drupal sucks" and "Wordpress sucks". Here are some examples:

PS: Don’t even bother looking at HackerNews comments about Drupal. They're savage.

Static Sites Provide Simple Permissioning

CMS systems like Wordpress and Drupal have their own permission systems. You can create users, admins, and assign people certain types of privileges.

This is also true regarding static site generators if they are built use Git and GitHub, which has a very sophisticated security model that allows very specific controls around who can do what, and when. You can have project admins with unlimited powers, read-only editors who can submit suggested changes to articles pending review, and editors who can review and release changes to the website. Furthermore, most companies already use GitHub to manage employee access to projects, so this fits perfectly into existing workflows.

This model works well in terms of editing privileges for any large editorial team. Furthermore, this process has been used successfully even for enormous websites and teams. For instance: healthcare.gov (the website that powers all health plan selections and receives millions of visitors all the time) is built 100% with Jekyll with tremendous success: https://developmentseed.org/blog/2013/10/24/its-called-jekyll/.

Fun Fact: Remember how much backlash heathcare.gov got when it first came out? The main reason for the really poor initial launch was that they used a CMS system which was unable to withstand user demand and caused a majority of their issues. See: http://www.newsweek.com/inside-healthcaregovs-failure-1449.

After saving the healthcare.gov project by switching to Jekyll, the new standards group inside the government team started rolling out Jekyll as a new standard for modern, secure, government websites.

Static Sites are Scalable

Because websites and blogs are an important channel for any company, uptime, speed, and reliability are paramount.

In this arena, static sites shine through above all other options.

They are infinitely scalable when hosted on Amazon (S3 + Cloudfront). Or, if you'd like a simpler solution: Netlify.
They can be easily deployed worldwide so that users in China see your website just as fast as a user in Kenya, or Tokyo, or California.
They can be globally cached in an extremely simple way that requires no ongoing technical maintenance.
They can be deployed and updated near-instantaneously, without delay.

The above features are not always true of CMS systems (like Wordpress and Drupal). These systems often have caching plugins that must be used to handle higher visitor traffic, and these typically cause technical issues when you want to immediately deploy changes to a website, or recover from mistakes. Getting these working properly can be a very difficult job (we had tremendous issues with this at my previous company, and I've personally seen these issues cause problems at many other companies).

Using CMS systems means that the database server which stores the content (web page content, article content, etc.) must also be highly available. These CMS systems use MySQL as their database and require not only web server scalability, but also database scalability, cache scalability, and other things. Doing a good job at scaling a CMS website is exponentially more difficult than doing so with a static site, which is designed for scale without any additional infrastructure, web servers, or work.

Static Sites are Cheap

Running a static site is inexpensive. For a site serving millions of visitors per month that is globally cached and is highly optimized for speed / availability: most companies would need to spend only a few dollars per month in hosting costs.

Compare this to the cost of running a Drupal website, you would need to pay for:

A company to host the site (this can easily cost thousands of dollars per month or more, for even small installations).
Ongoing support / maintenance costs from contractors (this can be very expensive as well).
Lots of time updating the system every few months, applying patches, taking backups, etc.
Working with contractors to customize the behaviors of Drupal to make it suitable for team needs, etc.

The cost comparison is greatly in favor of static sites in every possible way. Static sites require less time, energy, manpower, and infrastructure cost.

Static Sites are Easy to Use

In order to use a CMS system like Drupal to manage a website, blog, etc., there is a lot that each contributor needs to learn to be successful:

How to request / receive permissions to write / make changes.
How to navigate through the UI and edit / create / manage articles / pages.
How to insert code blocks and other special types of markup using the built-in web editors.
How to publish articles, go through a review process, and preview articles.
How to modify existing articles to fix issues, how to make suggested edits to other people's content / pages, etc.
And many other things..

To successfully run a static site project, there is really almost nothing contributors need to know other than:

How to open a text editor and write their article / content. (this is called markdown)
What folder to store their article in. These folders are usually very easy to find (eg: 2017/my-article-name.md).

Instead of needing to request / get permissions to the website, all someone needs to do is visit the website repository on GitHub, fork it, and then add whatever they want (this includes fixing other people's typos, grammar, etc. in a simple way). This can all be done in the web browser with limited technical knowledge required.

Once someone has made changes to the website, they can create a pull request and an editor on the team will be immediately notified that someone has changes available, can review them, and then either merge them in or ask the contributor to make modifications. GitHub makes collaboration extremely easy.

Static sites can be set up to automatically deploy user changes into a staging environment to make it easier for editors to review changes, and require zero command line knowledge to work.

Static Sites Provide Powerful Editorial

There is no system more powerful for managing large projects and websites than Git and GitHub. The system is designed from the ground up to make collaborating with other project contributors as simple (and powerful) as possible:

You can instantly review any past changes to a page, article, etc. Going back to the beginning of time.
You can easily switch back and forth between changes, edits, etc. Making it possible to fix mistakes instantly and precisely.
You never have to worry about things getting accidentally deleted or removed because Git holds onto these memories indefinitely.
Anyone can get started contributing to the website without any prior permissions needed (they can add their changes, and submit them for review).
Editors immediately are notified when a contributor want to make changes, and can instantly review their changes and either accept or reject them. This makes contributing extremely simple and painless for all parties.

Compare this to the way CMS systems like Wordpress and Drupal manage editorial:

Each contributor must be given access to the system (this is management overhead).
Each contributor must be given special permissions so they know what they are allowed / not allowed to do.
To have editorial notifications enabled, you must use special third party plugins.
Edit history storage is not unlimited, and is very hard to switch out. EG: If someone edits an article incorrectly, and you want to "revert" their changes, it is a very large hassle.
Edit history is limited, so if you delete something accidentally: this can be a massive issue. There may be no way to easily recover this information.
Editing is done "inline": this means editors must modify content directly as opposed to in a separate state where changes can be tested / agreed upon by both parties.

If you compare the two: it is clear that the Git workflow provides more control, safety, and ease of use for editorial for all parties involved.

Static Sites are Customizable

Content management systems are massive programs. They are very complicated, and have many moving parts: the platforms get updated, plugins (first and third-party) get updated, and there are many areas that can be customized.

Customizing CMSes can be an extremely time consuming, difficult, and error-prone task, even for experts.

For instance: supporting developer-friendly web editors that output Markdown, handling custom permissions and workflows to accommodate editorial, and even managing theme files, stylesheets, and custom JavaScript code can become a very time consuming process.

Compare this work with that of customizing a static site generator website: it is vastly simpler. Instead of having to have a contractor spend many hours tweaking things, team members can directly make changes they need, can easily review changes, merge them in, and roll out fixes.

Using a static site generator also enables anyone at your company to easily suggest or contribute changes to the website: style fixes, new components, etc. By enabling more people to easily get involved and contribute, you can greatly scale up output with very little effort. This would be impossible to do using a CMS system.

Another huge part of customization is SEO. This is always a concern. For instance: having tools that can measure things like keyword density, ensure that titles are the correct length, ensure that meta description tags are the correct length, etc.

These things are significantly more powerful using static sites as you can automate these items and codify rules around them. You don’t need to install third-party plugins and learn new flows: you can codify this behavior and instantly enforce it across the entire project.

In regards to more advanced SEO editing (for instance, using HTML5 metadata which Google includes in their search algorithm rankings): a static site generator is your only choice. CMS systems like Wordpress and Drupal don’t support this level of customization at all (unless you're willing to manually edit each and every article's raw HTML), because you’re essentially controlling the output of the program directly. With static site generators, however, there are numerous ways to accomplish this, to ensure that things like:

Dates are correctly formatted and marked up with HTML5.
Time ranges are correctly formatted and marked up with HTML5.
Assets that need to be preloaded or prefetched can be included to speed up rendering of complex code samples / media.
Etc.

Overall: there is nothing more customizable / powerful than a static site generator for contributors or editors to use.

Static Sites Provide "Ownership"

I strongly believe that owning core parts of your product leads to a good user experience.

For instance: here at Okta, we are a security company. Because of this, we have an in-house security team which helps ensure Okta products are held to a higher standard. For our core IT dashboard service: we hire in-house engineers who spend their time and care carefully building quality products for Okta users.

We would not outsource our core engineering team: and thus we should not outsource our technical blog and documentation, either.

Because our blog (and developer docs) are critically important to our success, we should completely own and control this part of the product to ensure we can hold it up to extremely high quality standards.

This is something that becomes vastly more difficult when a third-party company is managing our website, our CMS, and making changes and fixes to our web properties.

Take a look at any outsourced products, and compare them to in-house products: with very few exceptions, in-house projects are almost always better.

Static Sites are Portable

CMS systems like Drupal and Wordpress store all content inside of a database, using very specific formatting. If your company ever decides to migrate to another platform in the future, migrating is a very hard thing to do.

This is because there is no easy way to export your data out of Drupal or Wordpress into a plain text format that can be easily imported into other systems.

CMS systems like Wordpress / Drupal provide a lot of vendor lock in which makes porting your project to another system incredibly hard in the future.

Compare this with static site generators like Jekyll and Hugo: your content is stored in its original format, without modification, forever. Moving from a static site generator to any other system is incredibly easy as there is no vendor lock in whatsoever. This gives you the flexibility in the future to shift to other systems with as little effort as technically possible.

Static Sites are Reliable

One of the major reasons companies prefer static site generators is reliability. Using a static site generator like Jekyll or Hugo allows you do things like:

Automatically test articles for broken URLs.
Automatically find broken images and image links.
Look for broken style rules and obvious UI errors.

Doing these things with a CMS system requires heavy customization and is very brittle.

Using a static site generator gives your organization much more control over the quality of your edits and articles, because you can easily automate testing for them! This reduces the editor’s burden, as well as the burden of the team itself.

Static Sites vs CMS: A Summary

Using a static site generator provides numerous benefits over what any CMS can provide:

They are secure
Developers enjoy using them
They are fast
The are easy to use even for those with minimal technical expertise
They scale with 0 effort
They cost exponentially less money to operate
They require minimal maintenance effort
They have a positive reputation in the developer community, and signify a strong engineering culture and team to outsiders
They support more advanced, useful editorial than any CMS provides
The enable anyone in the organization to contribute to the website, blog, documentation. You can leverage this to more easily expand contribution efforts.
If you decide to move to another platform in the future, migrating away from a static site generator is much easier than anything else

If this post was helpful, you might really enjoy taking a look at our service, Okta: https://developer.okta.com.

We're an API company that stores user accounts and handles things like authentication, authorization, social login, single sign-on, etc. It's easy to get started and we have an epic free plan for developers (like you). If you want to give it a go, you can create a free account here: https://developer.okta.com/signup/.

Announcing PassProtect - Proactive Web Security

Randall Degges — Wed, 23 May 2018 05:00:00 +0000

If you’re reading this article you probably care about web security. You probably use a password manager to manage your passwords, you’ve probably got multi-factor authentication setup for all of your services, and you’re probably already subscribed to Have I Been Pwned? so you’re alerted when one of your logins have been involved in a data breach.

But you’re not most people.

Most web users are completely disconnected from the incredible advancements that have been made in the web security world over the last handful of years. Most web users aren’t notified when their credentials are leaked in a data breach, and to make matters worse, most users whose credentials are breached never reset their passwords.

Wouldn’t it be great if the websites that users visited every day could automatically notify users when the credentials they’re using are unsafe? This would give them the opportunity to change their unsafe passwords before attackers can take advantage of them. It would give them the knowledge they need to take the security of their personal information into their own hands.

This is what our new developer library, PassProtect, enables.

Instead of being the victim during a breach, PassProtect transforms even the most casual internet users into data security experts on par with you and I.

The way PassProtect works is simple, by including a single JavaScript tag in your web pages, your users will instantly start getting notifications if the credentials they’ve entered on your site are unsafe.

<html>
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
    <script src="https://cdn.passprotect.io/passprotect.min.js"></script>
  </body>
</html>

What do users see? An informative notification that gives them the information they need to make a good choice:

PassProtect is built with casual users in mind, and provides simple but informative notifications. To avoid being annoying, PassProtect uses smart caching to ensure notifications are never repeated in a single session in any way that would hurt user experience.

Furthermore, PassProtect piggybacks off the fabulous Have I Been Pwned? service, the largest database of breached credentials on the internet (created by our friend, Troy Hunt).

And because the data PassProtect works with is so sensitive (user passwords), we ensure that PassProtect never stores, collects, or send any password data over the network. Instead, PassProtect relies on k-anonymity (created by our friends at Cloudflare), which just so happens to be the best way to verify that a password exists in a remote database without ever sending that password (or the full hash of that password) over a network. =)

Don’t believe me? Check out the source!

This all sounds great, right!? The only problem is that our goal of dramatically improving the security of casual web users will only be realized if every developer embeds PassProtect in their websites. This is why I also went ahead and built a Chrome Extension for PassProtect as well. Firefox support will be coming soon.

This way, web users who want to go ahead and take advantage of PassProtect directly can do so—this way every website they visit will instantly inherit PassProtect’s functionality automatically!

Nothing is truly secure. At some point or another, all systems will be subject to a vulnerability of some sort. Security will always be a cat-and-mouse game between attackers and defenders, and to win you need to hope for the best but prepare for the worst.

We sincerely hope that PassProtect will help make the negatives (data breaches) a lot more positive by empowering individual users to reset their credentials when necessary and take charge of their personal data security.

If you’d like to get PassProtect for your website, please check out our GitHub repo (which contains far more information). If you’d like to use PassProtect in your browser, please check out our Chrome Extension.

Be safe out there! <3

PS : If you’ve had a chance to play around with PassProtect please let me know what you think! Leave a comment down below or shoot me an email.

Build a Video Chat Service with JavaScript, WebRTC, and Okta

Randall Degges — Thu, 10 May 2018 16:55:34 +0000

Liquid syntax error: Unknown tag 'endcomment'

Please Stop Using Local Storage

Randall Degges — Tue, 30 Jan 2018 05:03:48 +0000

Seriously. Just stop it already.

I don't know what it is, exactly, that drives so many developers to store session information in local storage, but whatever the reason: the practice needs to die out. Things are getting completely out of hand.

Almost every day I stumble across a new website storing sensitive user information in local storage and it bothers me to know that so many developers are opening themselves up to catastrophic security issues by doing so.

Let's have a heart-to-heart and talk about local storage and why you should stop using it to store session data.

What is Local Storage?

I'm sorry if I was a bit grumpy earlier. You don't deserve that! Heck, you might not even be familiar with what local storage is, let alone be using it to store your session information!

Let's start with the basics: local storage is a new feature of HTML5 that basically allows you (a web developer) to store any information you want in your user's browser using JavaScript. Simple, right?

In practice, local storage is just one big old JavaScript object that you can attach data to (or remove data from). Here's an example of some JavaScript code that stores some of my personal info in local storage, echoes it back to me, and then (optionally) removes it:

// You can store data in local storage using either syntax
localStorage.userName = "rdegges";
localStorage.setItem("favoriteColor", "black");

// Once data is in localStorage, it'll stay there forever until it is
// explicitly removed
alert(localStorage.userName + " really likes the color " + localStorage.favoriteColor + ".");

// Removing data from local storage is also pretty easy. Uncomment the lines
// below to destroy the entries
//localStorage.removeItem("userName");
//localStorage.removeItem("favoriteColor");

If you run the JavaScript code above in your browser on a test HTML page, you'll see the phrase “rdegges really likes the color black.” in an alert message. If you then open up your developer tools, you'll be able to see the that both the userName and favoriteColor variables are both stored in local storage in your browser:

Now you might be wondering if there's some way to use local storage so that the data you store is automatically deleted at some point and you don't need to manually delete every single variable you put in there. Luckily, the HTML5 working group (shout out!) has your back. They added something called sessionStorage to HTML5 which works exactly the same as local storage except that all data it stores is automatically deleted when the user closes their browser tab.

What's Cool About Local Storage?

Now that we're on the same page about what local storage is, let's talk about what makes it cool! Even though the whole point of this article is to dissuade you from using local storage to store session data, local storage still has some interesting properties.

For one thing: it's pure JavaScript! One of the annoying things about cookies (the only real alternative to local storage) is that they need to be created by a web server. Boo! Web servers are boring and complex and hard to work with.

If you're building a static site (like a single page app, for instance), using something like local storage means your web pages can run independently of any web server. They don't need any backend language or logic to store data in the browser: they can just do it as they please.

This is a pretty powerful concept and one of the main reasons that local storage is such a hit with developers.

Another neat thing about local storage is that it doesn't have as many size constraints as cookies. Local storage provides at least 5MB of data storage across all major web browsers, which is a heck of a lot more than the 4KB (maximum size) that you can store in a cookie.

This makes local storage particularly useful if you want to cache some application data in the browser for later usage. Since 4KB (the cookie max size) isn't a lot, local storage is one of your only real alternative options.

What Sucks About Local Storage

OK. We talked about the good, now let's spend a minute (or two!) talking about the bad.

Local storage is soooo basic. WHEW. I feel better already getting that off my chest. Local storage is just an incredibly basic, simple API.

I feel like most developers don't realize just how basic local storage actually is:

It can only store string data. Boo. This makes it pretty useless for storing data that's even slightly more complex than a simple string. And sure, you could serialize everything including data types into local storage, but that's an ugly hack.
It is synchronous. This means each local storage operation you run will be one-at-a-time. For complex applications this is a big no-no as it'll slow down your app's runtime.
It can't be used by web workers =/ This means that if you want to build an application that takes advantage of background processing for performance, chrome extensions, things like that: you can't use local storage at all since it isn't available to the web workers.
It still limits the size of data you can store (~5MB across all major browsers). This is a fairly low limit for people building apps that are data intensive or need to function offline.
Any JavaScript code on your page can access local storage: it has no data protection whatsoever. This is the big one for security reasons (as well as my number one pet peeve in recent years).

To keep it short, here's the only situation in which you should use local storage: when you need to store some publicly available information that is not at all sensitive, doesn't need to be used in a high-performance app, isn't larger than 5MB, and consists of purely string data.

If the app you're using doesn't fit the above description: don't use local storage. Use something else (more on this later).

Why Local Storage is Insecure and You Shouldn't Use it to Store Sensitive Data

Here's the deal: most of the bad things about local storage aren't all that important. You can still get away with using it but you'll just have a slightly slower app and minor developer annoyance. But security is different. The security model of local storage IS really important to know and understand since it will dramatically affect your website in ways you may not realize.

And the thing about local storage is that it is not secure! Not at all! Everyone who uses local storage to store sensitive information such as session data, user details, credit card info (even temporarily!) and anything else you wouldn't want publicly posted to Facebook is doing it wrong.

Local storage wasn't designed to be used as a secure storage mechanism in a browser. It was designed to be a simple string only key/value store that developers could use to build slightly more complex single page apps. That's it.

What's the most dangerous thing in the entire world? That's right! JavaScript.

Think about it like this: when you store sensitive information in local storage, you're essentially using the most dangerous thing in the world to store your most sensitive information in the worst vault ever created: not the best idea.

What the problem really boils down to is cross-site scripting attacks (XSS). I won't bore you with a full explanation of XSS, but here's the high level:

If an attacker can run JavaScript on your website, they can retrieve all the data you've stored in local storage and send it off to their own domain. This means anything sensitive you've got in local storage (like a user's session data) can be compromised.

Now, you might be thinking “So what? My website is secure. No attacker can run JavaScript on my website.”

And that's a reasonable point. If your website is truly secure and no attacker can run JavaScript code on your website then you are technically safe, but in reality that is incredibly hard to achieve. Let me explain.

If your website contains any third party JavaScript code included from a source outside your domain:

Links to bootstrap
Links to jQuery
Links to Vue, React, Angular, etc.
Links to any ad network code
Links to Google Analytics
Links to any tracking code

Then you are currently at risk for having an attacker run JavaScript on your website. Let's say your website has the following script tag embedded inside it:

<script src="https://awesomejslibrary.com/minified.js"></script>

In this case, if awesomejslibrary.com is compromised and their minified.js script gets altered to:

Loop through all data in local storage
Send it to an API built to collect stolen information

... then you are completely screwed. In this situation the attacker would have easily been able to compromise anything you had stored in local storage and you would never notice. Not ideal.

As engineers, I think we're frequently susceptible to thinking that we would never embed third-party JavaScript in our websites. But in the real world, this scenario rarely plays out.

At most companies, the marketing team directly manages the public website using different WYSIWYG editors and tooling. Can you really be sure that nowhere on your site are you using third-party JavaScript? I'd argue “no”.

So to err on the side of caution and dramatically reduce your risk for a security incident: don't store anything sensitive in local storage.

PSA: Don't Store JSON Web Tokens in Local Storage

While I feel like I made myself clear that you should never ever store sensitive information in local storage in the previous section, I feel the need to specifically call out JSON Web Tokens (JWTs).

The biggest security offenders I see today are those of us who store JWTs (session data) in local storage. Many people don't realize that JWTs are essentially the same thing as a username/password.

If an attacker can get a copy of your JWT, they can make requests to the website on your behalf and you will never know. Treat your JWTs like you would a credit card number or password: don't ever store them in local storage.

There are thousands of tutorials, YouTube videos, and even programming classes at universities and coding boot camps incorrectly teaching new developers to store JWTs in local storage as an authentication mechanism. THIS INFORMATION IS WRONG. If you see someone telling you to do this, run away!

What to Use Instead of Local Storage

So with all of local storage's shortcomings, what should you use instead? Let's explore the alternatives!

Sensitive Data

If you need to store sensitive data, you should always use a server-side session. Sensitive data includes:

User IDs
Session IDs
JWTs
Personal information
Credit card information
API keys
And anything else you wouldn't want to publicly share on Facebook

If you need to store sensitive data, here's how to do it:

When a user logs into your website, create a session identifier for them and store it in a cryptographically signed cookie. If you're using a web framework, look up “how to create a user session using cookies” and follow that guide.
Make sure that whatever cookie library your web framework uses is setting the httpOnly cookie flag. This flag makes it impossible for a browser to read any cookies, which is required in order to safely use server-side sessions with cookies. Read Jeff Atwood's article for more information. He's the man.
Make sure that your cookie library also sets the SameSite=strict cookie flag (to prevent CSRF attacks), as well as the secure=true flag (to ensure cookies can only be set over an encrypted connection).
Each time a user makes a request to your site, use their session ID (extracted from the cookie they send to you) to retrieve their account details from either a database or a cache (depending on how large your website is)
Once you have the user's account info pulled up and verified, feel free to pull any associated sensitive data along with it

This pattern is simple, straightforward, and most importantly: secure. And yes, you can most definitely scale up a large website using this pattern. Don't tell me that JWTs are “stateless” and “fast” and you have to use local storage to store them: you're wrong!

Non-String Data

If you need to store data in the browser that isn't sensitive and isn't purely string data, the best option for you is IndexedDB. It's an API that lets you work with a database-esque object store in the browser.

What's great about IndexedDB is that you can use it to store typed information: integers, floats, etc. You can also define primary keys, handle indexing, and create transactions to prevent data integrity issues.

A great tutorial for learning about (and using) IndexedDB is this Google tutorial.

Offline Data

If you need your app to run offline, your best option is to use a combination of IndexedDB (above) along with the Cache API (which is a part of Service Workers).

The Cache API allows you to cache network resources that your app needs to load.

A great tutorial for learning about (and using) the Cache API is this Google tutorial.

Please Stop Using Local Storage

Now that we've had a chance to talk about local storage, I hope you understand why you (probably) shouldn't be using it.

Unless you need to store publicly available information that:

Is not at all sensitive
Doesn't need to be used in an ultra high performance app
Isn't larger than 5MB
Consists of purely string data

... don't use local storage! Use the right tool for the job.

And please, please, whatever you do, do not store session information (like JSON Web Tokens) in local storage. This is a very bad idea and will open you up to an extremely wide array of attacks that could absolutely cripple your users.

Have a question? Shoot me an email.

Stay safe out there =)

NOTE: For those of you who made it this far who are wondering why I didn't specifically call out Content Security Policy as a way to mitigate the effects of XSS, I specifically chose not to include this because it cannot help in the situation I described above. Even if you use CSP to whitelist all third-party JavaScript domains, that does nothing to prevent XSS if the third party provider is compromised.

And while we're at it: subresource integrity (while cool) is also not a global solution to this issue. For most marketing tools, ad networks, etc. (which are by far the most commonly used types of third-party JavaScript), subresource integrity is almost never used as the providers of those scripts want to change them frequently so they can silently update functionality for their users.

UPDATE: I'm not the only one who thinks you should never store anything sensitive in local storage. So does OWASP:

... In other words, any authentication your application requires can be bypassed by a user with local privileges to the machine on which the data is stored. Therefore, it's recommended not to store any sensitive information in local storage.

Build Your Own Invoicing Service with Node, Coinbase, Bitcoin, and Okta

Randall Degges — Thu, 25 Jan 2018 10:08:41 +0000

I got into Bitcoin back in 2011. Since then, I've been a fan of cryptocurrencies and have always had an interest in them. I've also built several Bitcoin projects over the years (an information website, an e-commerce site, and several others) to help promote the usage of the cryptocurrency (while having some fun).

The idea of being able to send and receive money almost instantly from anywhere in the world with no middleman is really appealing to a lot of people.

Today, I thought it'd be fun to build a small web invoicing portal (something similar to FreshBooks, but much less sophisticated) that allows you to easily invoice your clients over email and collect payment in Bitcoin.

The client can then pay their invoices using their local currency or Bitcoin (if they have it). In the end: you'll be able to manage and bill your clients and receive payment in Bitcoin.

I do a bit of consulting work myself and will be using this in the future. =)

PS: If you want to skip the article and go straight to the code, go for it! I'm using Node.js, Express.js, and Coinbase to power the application.

Get Started with Coinbase, Okta, and Node.js

Before I walk you through building the application, there are a few things you'll need to do.

You'll need to go create an account with Coinbase. Coinbase is the largest and most popular Bitcoin exchange in the US. It allows you to easily get started using Bitcoin without needing to install software, learn a lot, etc.

You'll also need to create an Okta developer account. Okta is an API service that allows you to create user accounts, and perform simple authentication and authorization for your web apps, mobile apps, and API services.

Finally, you'll need to have Node.js setup on your computer and be ready to do some coding! >:)

Set Up Coinbase

To send invoices and request money from different clients you might be consulting for, you'll need to first generate a Coinbase API key with the proper permissions.

Coinbase has an expansive API that you can use to do a number of things: one of which is send invoices requesting money.
To do this, you'll need to visit the Coinbase API management page, then click the button to create a new API key.

When you see the popup modal that prompts you for permissions, use the settings below:

What you're doing here is requesting API permission to:

View your different Coinbase accounts (wallet:accounts:read)
View any past transactions you've made (wallet:transactions:read)
Create new transactions to request money (wallet:transactions:request)

Once you've finished creating the key, you'll be able to see an API key and API secret value. Copy these down, you'll need them later.

Set Up Okta

Now that your Coinbase account is ready for usage, you need to set up your Okta account. This is what you'll be using to protect your portal so only you can access it.

Log into your Okta dashboard and copy down the Org URL value you see at the top right of the page. You will need this value later. It looks something like this:

You next need to create a new Okta Application. Using Okta, you can manage users for many applications you might have.

To do this, click the large Applications menu item and click Add Application. Then when you are prompted, select the Web application option. This tells Okta that you are building a web application (not an API service, for instance). Behind the scenes, Okta uses this information to set your app up with the proper types of OAuth 2.0 and OpenID Connect.

Now you'll see a page asking you to define your Application settings. Use the values below:

These settings basically tell Okta where your web app will be running (locally in this example) and what sort of security rules to apply.

Once you've finished creating the Application, you'll then be taken to your settings page for this newly created Application. You'll want to copy down two values, your Client ID and Client Secret. These will be needed later.

These credentials will be used to communicate securely with Okta in order to authenticate yourself into the web portal later.

Clone the Project

Now that we've done the boring stuff, let's take a look at some code.

You can either clone the project locally from my GitHub repository:

$ git clone https://github.com/oktadeveloper/crypto-invoicer

Or you can fork the project to your own GitHub account and then clone that locally. This might make it easier to make changes and play around with the code as you follow along below.

Through the rest of this article, I'll assume that you're working inside of the cloned/forked project directory.

Set Up Your Credentials

Now let's take the credentials you gathered earlier and define them as environment variables that you'll use to store these sensitive values.

To do this, you'll want to create a file named .env which looks like the following:

# .env
export OKTA_ISSUER_URI=https://xxx/oauth2/default
export OKTA_CLIENT_ID=xxx
export OKTA_CLIENT_SECRET=xxx
export REDIRECT_URI=http://localhost:3000/authorization-code/callback
export PORT=3000
export SECRET=xxx
export COINBASE_APIKEY_ID=xxx
export COINBASE_APIKEY_SECRET=xxx

Substitute your credentials where you see the xxx placeholder:

OKTA_ISSUER_URI should be set to the value of the Org URL value you copied down earlier, and placed into the URL. The final URL should look something like https://dev-111464.oktapreview.com/oauth2/default.
OKTA_CLIENT_ID and OKTA_CLIENT_SECRET are the Application credentials you generated when you created your Okta Application previously
REDIRECT_URI is a hard-coded URL that will be used as part of the authentication flow. More on this later.
PORT is the HTTP port you'll be running your webserver on. 3000 is standard for Node.js apps
SECRET should be a long, random string you define. This is used to secure your HTTP sessions and keep your authentication data safe. I like to generate these by bashing my hands on the keyboard for a second or two.
COINBASE_APIKEY_ID and COINBASE_APIKEY_SECRET are your Coinbase API credentials

Once you have these settings defined, you'll need to tell your terminal to use these variables. To do this, if you're using a standard Linux/Mac/BSD terminal, you can run the command:

$ source .env

The source command will tell your shell to take the variables defined in this file and make them available to the terminal for usage in your programs later on.

If you're using Windows, you'll need to do something different. Sorry!

Install Dependencies

Now that the setup is completely finished, install all of the project dependencies using npm, the Node.js package manager:

$ npm install

This command will install all of the dependent packages by analyzing the package.json and package-lock.json file in the project directory.

Among these dependencies, there are a few interesting ones:

express is the web framework you'll use to build the app
coinbase-node is the officially supported Coinbase developer library you'll be using to interact with the Coinbase API
oidc-middleware is a popular OpenID Connect middleware maintained by Okta that handles user authentication and authorization for Node.js apps

Build the Frontend

Fair warning: I'm not a great frontend developer. I'm more of a server-side developer.

The first thing I like to do when starting new projects is quickly define the frontend views. This part is more difficult for me, so I like to get it out of the way upfront.

If you take a look at the views directory, you'll notice that there are only three files: base.pug, index.pug, and dashboard.pug. These three views render the entire website.

base.pug is a shared base template that the other two templates extend. More on this in a moment.
index.html is the home page of the site
dashboard.pug is the site's dashboard view

I've defined these HTML views using the pug templating language. This lets you write HTML without all the closing tags and allows you to use whitespace to infer structure.

The base.pug template provides some common HTML that the other two views extend. This prevents you from needing to duplicate HTML that is shared between one or more pages.

Here's what the base.pug template looks like:

doctype html
html(lang="en")
  head
    <!-- Required meta tags -->
    meta(charset="utf-8")
    meta(name="viewport", content="width=device-width, initial-scale=1, shrink-to-fit=no")

    <!-- Bootstrap CSS -->
    link(rel="stylesheet", href="https://bootswatch.com/4/sketchy/bootstrap.min.css")
    link(rel="stylesheet", href="/static/css/style.css")

  body
    .container
      block body

    <!-- Optional JavaScript -->
    <!-- jQuery first, then Popper.js, then Bootstrap JS -->
    script(src="https://code.jquery.com/jquery-3.2.1.slim.min.js", integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN", crossorigin="anonymous")
    script(src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.3/umd/popper.min.js", integrity="sha384-vFJXuSJphROIrBnz7yo7oB41mKfc8JzQZiCq4NCceLEaO4IHwicKwpJf9c9IpFgh", crossorigin="anonymous")
    script(src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta.2/js/bootstrap.min.js", integrity="sha384-alpBpkh1PFOepccYVYDB4do5UnbKysX5WZXm3XxPqe5iKTfUKjNkCk9SaVuEZflJ", crossorigin="anonymous")

This is a pretty standard HTML page that uses the Bootstrap CSS library with the Sketchy Bootswatch theme. This theme makes the entire site look like a mockup. Since this is an example application, I thought the theme was fitting.

The index.pug view is also quite simple:

extends base.pug

block body
  h1.text-center.head Crypto Invoicer

  .row.intro
    .col
    .col-8
      .jumbotron
        h2.text-center A Personal Invoicing Portal

        p.
          This is a personal invoicing portal. Use this portal to bill your clients
          for work done using #[a(href="https://www.coinbase.com/") Coinbase]:
          accept money in USD or Bitcoin.

        p.
          If you're performing work for clients and need a simple way to bill
              them, give Crypto Invoicer a try!

        p.
          Please #[a.btn.btn-primary(href="/login") login] to continue.
    .col

This template simply displays a basic home page that prompts the user to log into their account to continue:

The last view you need to inspect is the dashboard.pug view. This view renders the dashboard page that allows a user to create and view their invoices.

extends base.pug

block body
  script(src="/static/js/sorttable.js")

  ul.nav.nav-pills.justify-content-end
    li.nav-item
      a.nav-link.active(href="/") Home
      li.nav-item
        a.nav-link.active(href="/logout") Logout

  h1.text-center Dashboard

  h2.create-invoice Create Invoice
  .row
    .col
    .col-6
      .jumbotron
        if error
          p.error #{error}

        form.form(method="post")
          .form-group
            label(for="email") To
            input#email.form-control(type="email", placeholder="Client Email", name="email", required=true)
          .form-group
            label(for="description") Description
            input#description.form-control(type="text", placeholder="Description", name="description", required=true)
          .form-group
            label(for="amount") Amount (USD)
            input#amount.form-control(type="number", min="1", step="any", name="amount", required=true)
          button.btn.btn-primary(type="submit") Create Invoice

    .col

  if transactions
    h2 Invoices
    table.table.sortable
      thead.thead-dark
        tr
          td Invoice #
          td Date Created
          td Completed?
          td Client Email
          td Description
          td Amount (USD)
      tbody
        each transaction in transactions
          tr
            td #{transaction.id}
            td #{new Date(transaction.created_at).toLocaleDateString("en-US", { hour12: false, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" })}
            td #{transaction.status}
            td #{transaction.to.email}
            td #{transaction.description}
            td $#{transaction.native_amount.amount}

This page is a bit more complex. It does a few key things:

It creates a form that allows the user to send a client an invoice. This form takes a few input parameters: the client's email address, a description of what is being billed, and finally an amount (in USD) to bill the client.
It lists all past invoices in an HTML table that can be sorted with JavaScript. To do this, you'll use pug to loop through all past transaction objects, and display their data as appropriate.

When you render this page, you'll see the invoice creation form:

And… If you've generated any past invoices, you'll see them listed below:

You'll also notice that if you click one of the table headers, you're able to sort all of the invoices by any column you want.

If you take a look at the dashboard.pug template code above, you can see how this works:

The sorttable JavaScript library is used to provide automatic table sorting in the browser
Pug is being used to display transaction details

Other than these two things, the rest of the page is plain old HTML. Nothing fancy!

Build the Server

Now that you've seen how the frontend code works, let's take a look at the server-side codebase.

Open up the server.js file found in the root of the project folder and follow along below.

Import Dependencies

The first thing I do in the server.js is import all the Node.js dependencies needed to run the app:

"use strict";

const Client = require("coinbase").Client;
const async = require("async");
const bodyParser = require("body-parser");
const express = require("express");
const session = require("express-session");
const ExpressOIDC = require("@okta/oidc-middleware").ExpressOIDC;

Nothing special here! Importing dependencies is standard in just about every app.

Define Globals

The next thing you'll notice in server.js is a section of code that defines a number of global variables:

// Globals
const OKTA_ISSUER_URI = process.env.OKTA_ISSUER_URI;
const OKTA_CLIENT_ID = process.env.OKTA_CLIENT_ID;
const OKTA_CLIENT_SECRET = process.env.OKTA_CLIENT_SECRET;
const REDIRECT_URI = process.env.REDIRECT_URI;
const PORT = process.env.PORT || "3000";
const SECRET = process.env.SECRET;
const client = new Client({
  apiKey: process.env.COINBASE_APIKEY_ID,
  apiSecret: process.env.COINBASE_APIKEY_SECRET
});

let account;
let transactions;

let app = express();

All the const definitions are fairly straightforward: they pull in the environment variable values that were set previously, and store them as JavaScript variables so they can be easily referenced.

The client variable defines a new Coinbase API client (which is later used to talk to the Coinbase API).

The account variable represents a Coinbase Account object. In Coinbase you can have any number of "Accounts": Bitcoin wallets, USD wallets, etc. You can move money between these much like checking accounts at a normal bank. When implementing the invoicing later, you'll need to know which Coinbase Account you want to issue the request for, this determines how you receive the money.

The transactions variable will be our own in-memory cache of all recent invoice transactions available to us via the Coinbase API. This is what we'll use when rendering our dashboard page later on: we'll store a cache of the transactions to avoid making API calls to Coinbase on each page load.

Finally, you'll notice the app variable. This is a standard Express.js convention: create an app object and use that to start up the web server later on.

Configure App Settings and Middleware

Once the globals have been defined, the next thing you need to do is define the app settings and middleware.

There's a section of code commented that contains these two blocks of functionality:

// App settings
app.set("view engine", "pug");

// App middleware
app.use("/static", express.static("static"));

app.use(session({
  cookie: { httpOnly: true },
  secret: SECRET
}));

// Authentication
let oidc = new ExpressOIDC({
  issuer: OKTA_ISSUER_URI,
  client_id: OKTA_CLIENT_ID,
  client_secret: OKTA_CLIENT_SECRET,
  redirect_uri: REDIRECT_URI,
  routes: { callback: { defaultRedirect: "/dashboard" } },
  scope: "openid profile"
});

app.use(oidc.router);

There's only one actual app setting here: app.set("view engine", "pug");, and all it does is tell Express to use the pug templating engine when rendering views.

Below that are the middleware definitions.

The first middleware defined is express.static. This middleware is configured to serve static assets (css, images, javascript) from the static directory in the root of the project folder. This definition tells Express that any requests that start with /static should be routed to that folder, and automatically return whatever files exist there.

This might be a good time to inspect the static folder and see what's in it. There are only two files:

A style.css file which holds some custom styling, and
A sorttable.js script which is used in our frontend to make our HTML table sortable

Next you'll see the express-session middleware defined. What this middleware does is configure Express to store sensitive user information in cookies (which are the safest way to store authentication data). When you are logged into the website via Okta later on, your authentication information will be stored in these cookies that are managed by this library.

NOTE: The SECRET variable that's used when initializing the session library is incredibly important. This long, random string that you previously defined is what keeps your cookies safe from tampering. If this value is ever leaked publicly (on GitHub, etc.) it would be a security catastrophe. All cookie-based systems require a secret key to be used to cryptographically validate the cookie.

The last middleware you'll see is the oidc-middleware. This is a little more complex, as it handles a lot of magic behind the scenes, and makes all the authentication logic in the application work.

The way this middleware works is by fully enabling your app to use OpenID Connect (OIDC) for authentication. When you define the new ExpressOIDC and give it your Okta configuration information, it builds an OIDC object that remembers all your application rules: what URL your application runs one, where to redirect the user after they've logged in, what your secret application keys are, etc.

Once this new object is created, it contains an Express router object that is then enabled below with the app.use(oidc.router); call. This line registers some magical routes behind the scenes: the main one of which is /login.

When this line of code is executed any requests to /login will redirect you to your dedicated login page (hosted by Okta), and prompt you to log into the application. Once the user has been logged in, they will then be redirected BACK to your Node.js application, where they will be logged in and able to access the dashboard page.

Define Helpers

Let's skip towards the bottom of the server.js file now and take a look at the updateTransactions function:

// Helpers
function updateTransactions(cb) {
  transactions = [];
  let pagination = null;

  async.doWhilst(
    function(callback) {
      account.getTransactions(pagination, (err, txns, page) => {
        if (err) {
          return callback(err);
        }

        pagination = page.next_uri ? page : false;

        txns.forEach(txn => {
          if (txn.type === "request") {
            transactions.push(txn);
          }
        });

        callback();
      });
    },
    function() {
      return pagination ? true: false;
    },
    function(err) {
      if (err) {
        return cb(err);
      }

      cb(null, transactions);
    }
  );
}

The purpose of this helper function is to build an in-memory cache of Coinbase transactions.

Each time you request money from a client and send them an invoice, Coinbase creates a transactional record. There are many different types of transactions that Coinbase logs, so what this function does is iterate through all available transactions, pruning out just the ones relevant to invoicing, then stores them in the global transactions array variable for later usage.

The idea here is that each time the dashboard is displayed, instead of talking to the Coinbase API and performing this logic in real-time, the app will simply pull the latest list of transactions out of the cache instead.

In this function I'm using the async library to perform a do-while loop that:

Talks to the Coinbase API and requests a list of transactions
Tries to determine whether there are any more "pages" of transactions left to iterate through (because there may be many transactions, it might require many requests to the Coinbase API to retrieve them all)
Filters out only the transactions that are of the type "request", as these are the "request" money transactions that this app generates
Stores them in the global transactions array for later usage

Define Startup Jobs

The next thing you'll do is define the jobs that need to run each time this Node.js server starts up.

If you take a look at the startup jobs code block, you'll see what I mean:

// Startup jobs
client.getAccounts({}, (err, accounts) => {
  if (err) {
    console.error(err);
  }

  accounts.forEach(acct => {
    if (acct.primary) {
      account = acct;
      console.log("Found primary account: " + account.name + ". Current balance: " + account.balance.amount + " " + account.currency + ".");

      console.log("Downloading initial list of transactions.");
      updateTransactions(err => {
        if (err) {
          console.error(err);
        }
      });
    }
  });
});

What this code does is:

Use the Coinbase API to list all Accounts (these are the places you can store money in Coinbase)
Look through each Account until it finds the primary (this is usually your Bitcoin wallet used to store Bitcoin)
Sets the global account variable to this value

Then, once the proper Account object has been found, this code will execute the updateTransactions helper function defined earlier, to build the initial in-memory cache of transactions.

This way, shortly after the web server starts running all transaction data will be available for querying.

Define Server Management Code

Towards the bottom of the server.js file you'll see a few things:

// Cron jobs
setInterval(() => {
  updateTransactions(err => {
    if (err) {
      console.error(err);
    }
  })
}, 1000 * 60 * 60);

// Server management
oidc.on("ready", () => {
  app.listen(PORT);
});

oidc.on("error", err => {
  console.error(err);
});

The setInterval() call essentially tells this Node.js process to update the cache of transaction data once per hour (in milliseconds). This way, all transaction information will be at most one hour old.

Finally, the Express app itself will be launched once the authentication library has finished preparing itself.

NOTE: It's important not to run the web server (app.listen(PORT);) until the OIDC library emits the "ready" event. This could result in odd security edge cases where a user making requests to protected pages on your website runs into errors if they make a request before the OIDC library has finished configuring itself.

Create Routes

Now that we've gone through the rest of the server.js code, let's look at the final section we skipped from earlier (the routes):

// App routes
app.get("/", (req, res) => {
  res.render("index");
});

app.get("/dashboard", oidc.ensureAuthenticated(), (req, res) => {
  res.render("dashboard", { transactions: transactions });
});

app.post("/dashboard", oidc.ensureAuthenticated(), bodyParser.urlencoded(), (req, res) => {
  account.requestMoney({
    to: req.body.email,
    amount: req.body.amount,
    currency: "USD",
    description: req.body.description
  }, (err, txn) => {
    if (err) {
      console.error(err);
      return res.render("dashboard", { error: err });
    }

    updateTransactions((err, transactions) => {
      if (err) {
        console.error(err);
        return res.render("dashboard", { error: err.message });
      }

      return res.render("dashboard", { transactions: transactions })
    });
  });
});

app.get("/logout", (req, res) => {
  req.logout();
  res.redirect("/");
});

The first route just displays the home page of the site. Since all we need here is to show a simple template, there's nothing special we need to do other than render the page.

The app.get("/dashboard") route is what displays the dashboard page when requested. What's important to note here is the additional middleware it uses: oidc.ensureAuthenticated(). This middleware forces the user to log in before being able to access this page.

If you try to visit the /dashboard page before logging in, for instance, you'll be redirected to the login page and forced to authenticate.

Once the user has authenticated, however, they'll be allowed into the dashboard page, which simply renders itself using the in-memory cache of transaction data.

The app.post("/dashboard") route is what handles the invoicing.

When a user fills out the invoice form and clicks "submit", this route is processed and receives the invoicing data. It then talks to Coinbase using the Coinbase API and generates a proper money request (and email). Finally, before refreshing the page and showing the new list of transactions, this code will force a refresh of the transaction data cache.

By forcing the cache refresh after each new invoice is created, this prevents an issue where after creating an invoice you would not see it appear in the list below.

When invoices are generated and Coinbase sends out an email, the client receives an email that looks something like this:

This is quite nice because then a click can simply click the "Complete this payment." button, and be redirected to Coinbase where they can complete the transaction using either Bitcoin or their local currency (USD) to pay.

Piece It Together

As I've hopefully shown you, building Bitcoin invoicing software using Node.js can be fairly straightforward.

The Coinbase API provides a lot of rich functionality. Paired with Okta for authentication and several open source Node.js libraries, you can quickly throw together complicated applications in a small amount of time.

If you're interested in building cryptocurrency apps of your own, I highly recommend you create a Coinbase account and check out their fantastic API documentation. They have a good number of libraries and tools available to help you build your applications in a fun and fast way.

I'd also recommend creating an Okta developer account which you can use to store users for your web apps, mobile apps, and API services, as well as handle authentication, authorization, OAuth 2.0, OpenID Connect, Single Sign-On, etc.

Finally, if you'd like to see more articles like this, tweet @oktadev and let me know! <3 You can also look at some similar articles we've written recently:

Protect Your Cryptocurrency Wealth Tracking PWA with Okta written by my colleague @mraible
Build a Cryptocurrency Comparison Site with Vue.js by yours truly

Webhooks vs Serverless

Randall Degges — Mon, 22 Jan 2018 18:10:39 +0000

When you’ve built a successful software-as-a-service product, you tend to run into interesting technical (and business) questions. My favorite question is: “How do we add more functionality to our platform faster?” It’s an interesting question because everyone wants to build features faster.

In a perfect world, you’d be able to hire 100,000 engineers, split them into teams of four (with no managers!), and have each team own a feature: spec it out, build it, iterate on it with user feedback, and do it all in perfect harmony with every other team.

But let’s get real. This isn’t a perfect world, there’s no way a company would ever have four engineers work in a team without management (ha)!

So while you may not be able to build features at a fast enough pace to keep up with your product and user growth, you can cheat your way around it with a popular hack: platform extensibility.

Instead of requiring your engineers to sit down and develop every single feature every single user has ever requested, you can turn your product into a “platform” that your customer’s developers can build against. This way, if a customer wants a feature badly enough, they can integrate with your platform APIs and BAM: the previously unavailable feature can now be made available! It’s ingenious.

So how do you (as a successful business owner) allow other developers to extend your platform? You’ve got a lot of choices. Most of them are horrible, however, so I’m only going to talk about the most popular two: webhooks and serverless.

Serverless is the Answer!

If you’ve been following the internet hype train over the last few years (specifically, since 2014), you’ll be familiar with the term “serverless”, also known as “lambdas”, “functions-as-a-service”, etc.

What all these terms basically refer to is a pattern known as serverless extensibility.

In order to accommodate your customers extending your platform, you allow them to upload some code to your servers that you will run when certain events happen in your product.

I’ll give you a good example.

Let’s say you’re building an application hosting platform (a-la Heroku). Heroku provides functionality like running your application code, logging errors, and provisioning infrastructure (databases, etc.).

If a customer is using your platform and wants to send an email to their accounting team every time a new database is provisioned, this can be somewhat tricky unless your platform provides either a feature to do this, or extensibility options so the customer can do it on their own.

So, you decide to allow serverless extensibility. A customer can now upload some code (in JavaScript) to run on your platform every time a new piece of infrastructure is provisioned.

The customer reads through your docs, and writes a small function that looks something like this:

module.exports = sendEmail(event) {
  if (event.type === "provision" && event.service === "database") {
    // some code to send an email to the accounting department
  }
}

And then uploads it to your website.

This is pretty cool for the customer! Without needing to bug you and wait for your engineering team to build this email feature out, they were able to write some code to accomplish exactly what they wanted!

And not only can customers “hook” into your platform when infrastructure is being provisioned: they can hook in anywhere! Your platform provides tons of different extensibility options to make it possible for customers to run their code after or before almost every major platform event!

There are a few core benefits to this:

The customer can easily build out features they need, and not be bottlenecked by the speed of your engineering team
You lose fewer customers because they’ve now got a way to work around issues in your product
You’re able to iterate more quickly on your core platform product because you’re now able to narrow your scope

The Flip Side of Serverless

So now that you’ve built out serverless extensibility functionality for your customers you’ve opened up an infinite amount of customization options. But at what cost?

John, who runs Engineering for one of your largest customers, didn’t sign up for this. Your serverless extensibility created a bunch of ongoing work for him and his team:

He has to figure out how your serverless functions work, what hooks are available, etc. This is a high learning curve and requires all of his engineers to have a thorough understanding of your product in order to be productive.
Because your serverless platform only supports running JavaScript ES5 code at the moment, John’s team of C# engineers are having issues writing their complex application logic in JavaScript which they are not all familiar with.
John’s team doesn’t have any insight into how your serverless platform is running his code: they can’t figure out how to monitor server resources, how to do proper unit and integration testing, how to look for failures, etc.
John’s team now has to manage code in many different places as opposed to just one GitHub repository. Now, each serverless function John’s team writes must be manually uploaded into the right place in your platform website, maintained, and updated from time to time. Because there is no direct way to integrate these serverless functions into the team’s existing codebase, this code is now fragmented across your platform which makes it hard to work with.
John’s team is now in a sticky security situation: they’ve got to write proprietary code and store it on YOUR platform. They’ve also got to store sensitive credentials like their email account information, and any other related credentials required to run their serverless software. The security team at John’s company isn’t thrilled.

The larger the company, the more challenging this becomes. Coordinating between different groups of engineers to figure out where a particular piece of functionality is located is difficult and time-consuming. Updating previous hooks becomes a test of patience. And documentation for the team’s codebase becomes exponentially larger to include all of the domain-specific knowledge required to write, update, and maintain these serverless hooks.

These side effects negate the purpose of the original goal: to let customers get functionality they need faster.

And these are just the customer facing side effects you’ll notice. There’s a vast array of other messes this will cause you and your company:

You’ve got to build secure, isolated code execution environments to run customer code in a sandbox. This is incredibly hard in practice. If you search for “docker escalation” on Google, you’ll see what I mean. Even amazing services like Amazon Lambda (the first really serverless player) that have incredibly large security teams can expose themselves to funny security issues.
You’ve got to ensure you respect the customer’s software IP that is now running in your infrastructure
You’ve got to scale your infrastructure to support arbitrary amounts of customer code in addition to worrying about your own service issues
You’ve got to expose more and more transparent tools to allow your customers more insight into your system: error logs, performance monitoring, etc. The list can ultimately go on forever.
You’ve got to write documentation to explain each and every hook you support and how it works. You’ve also got to show users how to upload the code to your platform, how to test it, etc.

Bottom line? Building serverless extensibility functionality into your product will likely be the most expensive thing you ever do, engineering-wise–both for you and your users.

Webhooks, Going Beyond Serverless Extensibility

An older approach that’s been tested time and time again, is webhooks. While webhooks are not “old” by any means, they predate serverless extensibility patterns by at least seven years. My buddy Jeff Lindsay coined the term back in 2007.

The idea behind webhooks is simple: instead of you running a customer’s code on your platform, you instead just fire off an HTTP POST request to the customer every time something happens, and the customer can then perform whatever logic they need based on those incoming requests.

Simple, right?

This is a great approach because it’s easier to manage and scale for all parties involved.

It’s simpler for your company because you now only need to fire off HTTP requests when events happen. You don’t need to worry about executing someone else’s software, scaling it, etc. The most complicated thing you have to do is retry failed HTTP requests (which is mandatory for pretty much all HTTP requests anyhow!).

Webhooks in the Wild

Twilio

Twilio is one of the best known API services in the world. Twilio provides API services to manage telephony stuff: phone calls, SMS messages, MMS messages, etc.

Since day one, Twilio has provided core webhook support in their platform.

Let’s say you’re building an SMS application:

You buy a phone number through Twilio
Every time that phone number receives an SMS message, Twilio sends an HTTP POST request to your web server with the message data inside
You then receive an HTTP POST request to your web app, where you parse the request, figure out what the message said, and then take some action (maybe you send a response, for instance)

Using this simple back-and-forth messaging pattern, webhooks allow Twilio customers to easily integrate with the platform and build high-value apps without the hassle.

NOTE: My good friend Carter Rabasa at Twilio recently released support for serverless extensibility in addition to their core webhook support. This was a smart move, as they now appeal to everyone (even people who crazily prefer serverless extensibility patterns!).

Heroku

Remember Heroku from the serverless example before? I hope so!

Heroku’s application hosting platform recently started supporting webhooks, and it’s everything I ever dreamed of, and then some!

Heroku customers are now able to easily hook into their app infrastructure on Heroku, and perform complex logic to scale their services more easily, cut down cost, keep their ops team informed of issues, etc.

Github

GitHub webhooks have been around forever, and are the foundation of many popular developer services like Travis CI.

GitHub webhooks allow you to hook into just about every possible action that can be taken on a source repository. They’re excellent for analyzing code, tracking team performance, automating testing and deploys, as well as a number of other great use cases.

Webhooks In Your Product

Implementing serverless extensibility is hard–both for you and your customers. While there are some people who prefer it, it can be a lot of work for everyone involved.

As someone who’s been building developer tools and API services for nearly 17 years now, one of which generates nearly 30 billion API requests per month, I’d encourage you to take some time to think about the best possible way for you to open your platform up for customization.

Picking the wrong extensibility options can be a painful mistake, so it’s a good idea to think through the tradeoffs of both approaches, and pick what makes the most sense for you.

If you need some help deciding, please drop me a line or tweet at me, I’d be happy to help you out.

Summary

While both serverless extensibility and webhooks serve the same purpose, one is dramatically simpler than the other.

Webhooks are a simple solution to a complex problem, while serverless extensibility is a complex solution to a complex problem.

In computer science, as well as many other areas of professional and personal life, I like to take the simple path.

I hope this has been useful.

-Randall