chefbot-auth v1.0.1

Chefbot Auth

This module provides Authentication and Authroization for the ChefBot Micro-services using the OAuth2 standard. It makes communication easier among clients and the Authorization Server. Currently the only supported OAuth2 flow is the client_credentials grant.

Quick start

Resource server

• Include this library in your resource server (protected API) as a dependency npm i chefbot-auth
• Secure the desired endpoints with the checkJwt middleware.
• For fine-grained permissions check, validate the scopes with the checkScopes middleware.
• Define the CHEFBOT_AUTH_API_ID environment variable provided by the Authorization Server. This is the unique ID for the API you want to secure.

Client API

• Include this library in your client API as a dependency npm i chefbot-auth
• Request a JWT token using the generateToken function. You'll need to provide the following required arguments client_id , client_secret and target_api_id which are registered on the Authorization Server.

3rd party integrations

• In order to generate a JWT token, send a POST request to this endpoint https://chefbot.us.auth0.com/oauth/token

Detailed explanation

How does the client_credentials grant work?

Take a look at the spec for futher details

Resource server

The resource server (an API you want to secure) it's a simple node.js + express project. The changes you need to do are:

• Register your API with the Authorization Server, let's say you registered it as https://my-data-management-api.com with these scopes users:read users:write products:read products:write
• In your API project, include this library as a dependency npm i chefbot-auth
• Tell the chefbot-auth how you are export CHEFBOT_AUTH_API_ID=https://my-data-management-api.com
• Secure your routes with the provided middlewares as follows:

// Content for my-data-management-api/index.js

const express = require("express");
const { checkJwt, checkScopes } = require("chefbot-auth");

const app = express();

// ... All the required express config


// Open route without JWT validation
app.get("/products", checkJwt, (req, res) => {
  // Custom logic here
  res.json(data);
});

// Protected route with JWT validation only
app.get("/products/prices", checkJwt, (req, res) => {
  // Custom logic here
  res.json(data);
});

// Protected routes with JWT and scopes validation for fine-grained permissions check
app.get("/users", checkJwt, checkScopes(["users:read"]), (req, res) => {
  // Custom logic here
  res.json(data);
});

app.post("/users", checkJwt, checkScopes(["users:read", "users:write"]), (req, res) => {
  // Custom logic here
  res.json(data);
});

Client API

In this context a client it's a different API or Resource Server that needs to communicate with your protected API (which is another Resource Server). In order to request and send data to your protected API, the client needs to be registered with the Authorization Server and we should grant the scopes that service is allowed to. Therefore you will get a client ID and a client secret. Let's say we registered the client https://my-client.com. Now we want to get the users from the https://my-data-management-api.com API. These steps are required:

• Register the client API with the Authorization Server, and grant the users:read scope
• In your API project, include this library as a dependency npm i chefbot-auth
• Generate a JWT token
• Send the token as a header Authorization: Bearer ${GENERATED_TOKEN}
• Make a request to the secured API as follows:

// Content for my-client/index.js

const axios = require("axios");
const { generateToken } = require("chefbot-auth");

async function getUsers() {

  // Step 1: Get the token for the target resource server -> my-data-management-api  
  const { access_token } = await generateToken(CLIENT_API_CLIENT_ID, CLIENT_API_CLIENT_SECRET, "https://my-data-management-api.com")
    
  // Step 2: Make your request including the received token   
  const options = {
    method: "get",
    url: "https://my-data-management-api.com/users",
    headers: { "Authorization": `Bearer ${access_token}` },
  };

  const response = await axios(options)
  
  
  // ... Custom logic
 
}

3rd party integrations

If you don't own the source code of an external integration, let's say a Webhook but you need to communicate with a protected resource, you can generate a JWT token manually and include it as a header in your 3rd party integration. For this purpose, the Authorization Server exposes a token endpoint which returns the JWT with the proper scope and expiration. Follow these steps:

• Register your 3rd party service as a client with the Authorization Server
• Grant the desired scopes and set the expiration time
• Generate a JWT manually:

curl --request POST \
  --url https://chefbot.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"3RD_PARTY_SERVICE_CLIENT_ID","client_secret":"3RD_PARTY_SERVICE_CLIENT_SECRET","audience":"https://my-data-management-api.com","grant_type":"client_credentials"}'
  

The audience parameter is the target API you want to fetch from.