TL;DR: check the code on Github
I recently decided to use Swagger as the underlying technology for a Node.js REST API. Swagger (or it’s new “enterprise-friendly” OpenAPI branding) allows you to easily define a RESTful API using a JSON or YAML schema. Not only does it enforce you to follow all of REST’s best practices, it also provides a few very interesting tools that simplify the development process. A couple of examples are the Swagger Editor, that allows you to edit the API spec and see changes in real time, Swagger UI that automatically builds beautiful documentation, and Swagger Codegen, that generates the first version of the API endpoints’ code. Furthermore, there are many tools and integrations built for Swagger by its community.
While Swagger looked like a great fit for what I was looking for and everything started out nicely, some limitations soon became apparent. The first that I encountered is related to the use of JSON Web Tokens (JWT) for authentication purposes. Swagger’s specification allows for two types of mechanisms: OAuth, and what they call “apiKey”. Since JWT is definitely not OAuth, we have to use use “apiKey” to define that the JWT token will be sent in the HTTP Authorization header as “Bearer token_string“:
|
1 2 3 4 5 |
securityDefinitions: Bearer: type: apiKey name: Authorization in: header |
Furthermore, if we want to have different roles and manage the access to each API endpoint based on the user’s role, we will have to extend the Swagger spec, as it does not allow this for “apiKey” authentication. We can allow for role-based access as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
securityDefinitions: /protected: x-swagger-router-controller: main-controller get: operationId: protectedGet description: "Protected endpoint, only accessible to admins and users" security: - Bearer: [] x-security-scopes: - admin - user responses: "200": description: "Success" schema: $ref: "#/definitions/Resource" '403': description: "Access Denied" schema: $ref: "#/definitions/Error" |
After the Swagger configuration is defined, we need to write the code to actually make this work. Here I will use Express and swagger-tools to care care of all the heavy lifting:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
var app = require('express')(); var swaggerTools = require('swagger-tools'); var YAML = require('yamljs'); var auth = require('./api/helpers/auth'); var swaggerConfig = YAML.load('./api/swagger/swagger.yaml'); swaggerTools.initializeMiddleware(swaggerConfig, function (middleware) { //Serves the Swagger UI on /docs app.use(middleware.swaggerUi()); app.use(middleware.swaggerSecurity({ //manage token function in the 'auth' module Bearer: auth.verifyToken })); var routerConfig = { controllers: './api/controllers', useStubs: false }; app.use(middleware.swaggerRouter(routerConfig)); app.listen(3000, function() { console.log("Started server on port 3000"); }); }); |
As you can see in line 13, the security checks are handed off to the verifyToken function in the auth module. Here is the code:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 |
'use strict'; var jwt = require('jsonwebtoken'); var sharedSecret = 'shh'; var issuer = 'my-awesome-website.com'; //Here we setup the security checks for the endpoints //that need it (in our case, only /protected). This //function will be called every time a request to a protected //endpoint is received exports.verifyToken = function (req, authOrSecDef, token, callback) { //these are the scopes/roles defined for the current endpoint var currentScopes = req.swagger.operation["x-security-scopes"]; function sendError() { return req.res.status(403).json({message: 'Error: Access Denied'}); } //validate the 'Authorization' header. it should have the following format: //'Bearer tokenString' if (token && token.indexOf("Bearer ") == 0) { var tokenString = token.split(' ')[1]; jwt.verify(tokenString, sharedSecret, function (verificationError, decodedToken) { //check if the JWT was verified correctly if (verificationError == null && Array.isArray(currentScopes) && decodedToken && decodedToken.role) { // check if the role is valid for this endpoint var roleMatch = currentScopes.indexOf(decodedToken.role) !== -1; // check if the issuer matches var issuerMatch = decodedToken.iss == issuer; // you can add more verification checks for the // token here if necessary, such as checking if // the username belongs to an active user if (roleMatch && issuerMatch) { //add the token to the request so that we //can access it in the endpoint code if necessary req.auth = decodedToken; //if there is no error, just return null in the callback return callback(null); } else { //return the error in the callback if there is one return callback(sendError()); } } else { //return the error in the callback if the JWT was not verified return callback(sendError()); } }); } else { //return the error in the callback if the Authorization header doesn't have the correct format return callback(sendError()); } }; |
We just verify that the request presents a valid token (lines 21 through 27) and that the role of the user (which is saved in the token) matches one of the roles of the endpoint (line 13 and 29). The final piece of the puzzle is issuing a JWT with the user’s role as part of its payload:
|
1 2 3 4 5 6 7 8 |
exports.issueToken = function (username, role) { var token = jwt.sign({ sub: username, iss: issuer, role: role }, sharedSecret); return token; }; |
Just return the token when the user correctly logs in, and you’re set:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
exports.loginPost = function (args, res, next) { var role = args.swagger.params.role.value; var username = args.body.username; var password = args.body.password; if (role != 'user' && role != 'admin') { var response = {message: 'Error: Role must be either "admin" or "user"'}; res.writeHead(400, {'Content-Type': 'application/json'}); return res.end(JSON.stringify(response)); } else if (username == 'username' && password == 'password' && role) { var tokenString = auth.issueToken(username, role); var response = {token: tokenString} res.writeHead(200, {'Content-Type': 'application/json'}); return res.end(JSON.stringify(response)); } else { var response = {message: "Error: Credentials incorrect"}; res.writeHead(403, {'Content-Type': 'application/json'}); return res.end(JSON.stringify(response)); } }; |
And that’s basically it! All the code is available on Github, so feel free to check it out and test it for yourself.