Making Tax Digital (MTD) for Income Tax went live on 6 April 2026, and it's already mandatory for self-employed people and landlords whose qualifying income is over £50,000. That threshold drops to £30,000 in April 2027 and to £20,000 in April 2028, so the population it covers roughly triples over the next two years.

In practice, that means a lot of small businesses now need software that can send their figures to HMRC, and someone has to build that software.

The first time you open HMRC's developer documentation, it's a wall of acronyms: MTD, ITSA, OAuth scopes, fraud prevention headers, and obligations. It looks intimidating, and a lot of it is genuinely fiddly. But the path from zero to your first authenticated API call is more approachable than it looks once someone walks you through it in order.

That's what this guide does. I built the HMRC integration for a Making Tax Digital app, and I'm going to take you through the same steps I took, in the order I took them: what MTD is, how to get a sandbox app, how the OAuth login flow works, what those fraud prevention headers are, and how to make a real call. The code is Node and TypeScript, but the ideas carry over to any language.

Table of Contents

• What Making Tax Digital Actually is

• Step 1: Create a Sandbox Application

• Step 2: Understand the OAuth Scopes

• Step 3: The OAuth 2.0 Authorization Code Flow

• Step 4: Fraud Prevention Headers (the Part Nobody Warns You About)

• Step 5: Make Your First Authenticated Call

• Common Gotchas that Will Cost You an Afternoon

• Where to Go Next

What Making Tax Digital Actually is

Making Tax Digital is HMRC's programme to move tax record-keeping and filing into software.

Instead of one big annual Self Assessment return typed into a website, MTD for Income Tax asks people to keep digital records and send HMRC a cumulative update of their income and expenses every quarter, then a final declaration at the end of the year.

(For the official scope and timeline, see GOV.UK's MTD for Income Tax guidance.)

For developers, the important part is that HMRC doesn't give you a single "file my taxes" button. It gives you a set of REST APIs on its Developer Hub: one to list a person's businesses, one to read their filing obligations (what's due and when), one to submit the quarterly figures, one to trigger a tax calculation, and so on.

You compose these into a journey. Every one of them sits behind the same two gates: an OAuth 2.0 access token, and a set of fraud prevention headers. Get those two things right and the rest is ordinary JSON over HTTPS.

Step 1: Create a Sandbox Application

You never start against live taxpayer data. HMRC runs a full sandbox at test-api.service.hmrc.gov.uk that mirrors the production host (api.service.hmrc.gov.uk) and lets you create fake taxpayers to test with.

Here is the practical sequence:

1. Register for a free account on the HMRC Developer Hub.

2. Create an application. You get a client ID and a client secret. Treat the secret like a password: keep it in an environment variable, never in your source.

3. Set a redirect URI. This is the URL HMRC sends the user back to after they log in. For local work something like http://localhost:3000/auth/hmrc/callback is fine. It has to match exactly later, character for character.

4. Subscribe your application to the APIs you need. This is the step beginners miss. Listing it isn't enough. You click into each API and subscribe. If you forget, calls come back 403 Forbidden with no obvious reason.

In the code, the only thing that differs between sandbox and production is the base URL, so it's worth keeping those in config rather than hard-coding them:

const config = {
  sandbox: {
    baseUrl: 'https://test-api.service.hmrc.gov.uk',
    authUrl: 'https://test-api.service.hmrc.gov.uk/oauth/authorize',
    tokenUrl: 'https://test-api.service.hmrc.gov.uk/oauth/token',
  },
  production: {
    baseUrl: 'https://api.service.hmrc.gov.uk',
    authUrl: 'https://api.service.hmrc.gov.uk/oauth/authorize',
    tokenUrl: 'https://api.service.hmrc.gov.uk/oauth/token',
  },
};

One thing I learned the hard way: pick the environment from an explicit setting, not from NODE_ENV. You'll eventually want a production deployment that still points at the HMRC sandbox during a beta, and if your URLs are keyed off NODE_ENV alone, that combination forces production HMRC and rejects your sandbox credentials with client_id is invalid. A small HMRC_BASE_URL environment variable that always wins saves you that confusion.

Step 2: Understand the OAuth Scopes

When your app asks a user for access, it asks for specific scopes, which are named permissions. For MTD Income Tax the ones you want are read:self-assessment and write:self-assessment (HMRC also exposes read:vat and write:vat for the VAT APIs). HMRC documents these in its OAuth 2.0 authorisation guide. You join them with spaces:

const scopes = ['read:self-assessment', 'write:self-assessment'].join(' ');

The user sees these spelled out on HMRC's consent screen, so only ask for what you actually use.

Step 3: The OAuth 2.0 Authorization Code Flow

This is the heart of the integration, and it's the standard three-legged OAuth dance. Think of it as your app, the user, and HMRC passing a baton. There are four moments: send the user to HMRC, HMRC sends them back with a code, you swap the code for tokens, and later you refresh those tokens.

3a. Send the User to HMRC

You build an authorization URL and redirect the browser to it. The query string carries your client ID, the scopes, your redirect URI, response_type=code, and a state value:

function getAuthorizationUrl(state: string): string {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: hmrcConfig.clientId,
    scope: hmrcConfig.scopes,
    state: state,
    redirect_uri: hmrcConfig.redirectUri,
  });
  return hmrcConfig.authUrl + '?' + params.toString();
}

That state value matters. It's your defense against cross-site request forgery (CSRF). You generate a random, unguessable string, store it server-side, attach it here, and check it again when the user comes back. If the value that returns doesn't match one you issued, you reject the callback. A common pattern is to generate a UUID and stash it with the user's ID and a timestamp:

const state = uuidv4();
await setStateToken(state, { createdAt: Date.now(), userId });
res.redirect(getAuthorizationUrl(state));

The user now logs in on HMRC's own pages (with their Government Gateway credentials) and approves the scopes. Your app never sees their password, which is the whole point of OAuth.

3b. Handle the Callback

HMRC redirects back to your redirect URI with two query parameters: code and state (or an error if the user declined). First validate the state, then make it single-use by deleting it immediately so it can never be replayed:

const stored = await getStateToken(state);
if (!state || !stored) {
  return redirectError('Invalid or expired authorization request');
}
await deleteStateToken(state); // single-use: delete the moment it validates

// Optional but sensible: expire stale requests (here, 10 minutes).
if (Date.now() - stored.createdAt > 10 * 60 * 1000) {
  return redirectError('Authorization request has expired. Please try again.');
}

3c. Exchange the Code for Tokens

The code is short-lived and useless on its own. You exchange it, server to server, for an access token and a refresh token. This is a POST to the token endpoint with grant_type=authorization_code, form-encoded, including your client secret. The secret is why this happens on your backend and never in the browser:

async function exchangeCodeForTokens(code: string) {
  const response = await axios.post(
    hmrcConfig.tokenUrl,
    new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      client_id: hmrcConfig.clientId,
      client_secret: hmrcConfig.clientSecret,
      redirect_uri: hmrcConfig.redirectUri,
    }).toString(),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
  );

  return {
    accessToken: response.data.access_token,
    refreshToken: response.data.refresh_token,
    expiresIn: response.data.expires_in, // seconds until the access token dies
  };
}

Store these tokens server-side, tied to the user, and never send them to the client. The access token is what authorises every later API call. Note expires_in: HMRC access tokens are short-lived (currently four hours), so you'll need step 3d.

3d. Refresh the Token

When the access token expires, you don't make the user log in again. You use the refresh token to get a fresh pair, with grant_type=refresh_token:

async function refreshAccessToken(refreshToken: string) {
  const response = await axios.post(
    hmrcConfig.tokenUrl,
    new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: hmrcConfig.clientId,
      client_secret: hmrcConfig.clientSecret,
    }).toString(),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
  );
  return {
    accessToken: response.data.access_token,
    refreshToken: response.data.refresh_token,
    expiresIn: response.data.expires_in,
  };
}

A good habit is to check the stored token's expiry before each call and refresh proactively if it's close to running out. HMRC's OAuth documentation has the full lifecycle.

Step 4: Fraud Prevention Headers (the Part Nobody Warns You About)

Here's the surprise. Most APIs are happy with a bearer token. HMRC is not. By law, it requires your software to send a set of fraud prevention headers on every MTD call: a couple of dozen Gov-Client-* and Gov-Vendor-* headers describing the device, the network path, and the software making the request. They help HMRC detect credential abuse across thousands of third-party vendors.

This guide is about getting connected, so I'll keep this high level: read HMRC's Fraud Prevention Headers specification carefully, because the rules are precise and the failure modes are quiet.

The single most important decision is the connection method, sent in Gov-Client-Connection-Method. A server-mediated web app uses WEB_APP_VIA_SERVER; a server-mediated mobile app uses MOBILE_APP_VIA_SERVER. That choice decides which other headers are required and which are forbidden, so don't just emit everything.

The genuinely good news for beginners is that HMRC gives you a Test Fraud Prevention Headers API that inspects your request and tells you exactly which headers are missing or malformed. Build against that validator from your first commit and you turn a guessing game into a checklist.

You don't need the full depth of that spec to get your first sandbox call working, but you will need it before you go anywhere near production data, so budget real time for it rather than leaving it to the end.

Step 5: Make Your First Authenticated Call

Now you have a token and your headers. Time for a real request. Every MTD call sets two things on top of the token: an Accept header that pins the API version, and the fraud headers:

async function request(method, path, accessToken, req, data = null, apiVersion = '2.0') {
  const headers = {
    Authorization: `Bearer ${accessToken}`,
    Accept: `application/vnd.hmrc.${apiVersion}+json`,
    ...hmrcConfig.getFraudHeaders(req),
  };
  // Only set a JSON Content-Type when there is actually a body (see gotcha 3).
  if (data !== null && data !== undefined) {
    headers['Content-Type'] = 'application/json';
  }
  const res = await axios({ baseURL: hmrcConfig.baseUrl, method, url: path, headers, data });
  return res.data;
}

A great first call is "list this person's businesses", which uses their National Insurance number (NINO) and the Business Details API. It's read-only, so it's a safe way to confirm your token and headers are accepted:

// GET /individuals/business/details/{nino}/list  (Business Details API v2.0)
const businesses = await request(
  'GET',
  `/individuals/business/details/${nino}/list`,
  accessToken,
  req,
  null,
  '2.0',
);

Once that returns, the natural next call is obligations: what quarterly updates are due and when. This one is on a newer API version, which is the perfect lead-in to the gotchas:

// GET /obligations/details/{nino}/income-and-expenditure  (Obligations API v3.0)
const obligations = await request(
  'GET',
  `/obligations/details/${nino}/income-and-expenditure`,
  accessToken,
  req,
  null,
  '3.0',
);

To test these in the sandbox, you create a fake taxpayer using HMRC's "Create Test User" API, which hands you a NINO and Government Gateway credentials to log in with during the OAuth flow.

Common Gotchas that Will Cost You an Afternoon

A few traps catch nearly everyone the first time:

1. Pin the API Version, or Get a 406.

Different HMRC APIs live at different versions: Business Details is on 2.0, Obligations on 3.0, the calculation APIs on later versions again. The version lives in the Accept header (application/vnd.hmrc.3.0+json). Send the wrong version, or forget the header, and HMRC replies 406 Not Acceptable. When a call mysteriously fails, check the version first.

2. The state Token is Single-Use.

Validate it, then delete it immediately, before you do anything else. If you leave it lying around, you've weakened the CSRF protection it exists to provide. Expire stale ones too.

3. Don't send Content-Type: application/json on a bodyless GET.

This one is genuinely surprising. HMRC's edge (CloudFront) rejects a GET that carries a JSON Content-Type with no body as a 403 Bad request, which can break every read endpoint at once. Only set Content-Type when there's an actual body to send, as in the snippet above.

4. Subscribe Your App to Each API.

As mentioned in step 1, an unsubscribed API returns 403, which reads like an auth problem but is not.

5. The Redirect URI Must Match Exactly.

A trailing slash or http versus https mismatch produces an opaque error on the consent screen. Copy it, don't retype it.

Where to Go Next

That's the whole spine: register a sandbox app and subscribe it, run the OAuth Authorization Code flow to get tokens, attach fraud prevention headers, and make versioned JSON calls.

From here, the rest of MTD is more of the same: submit the cumulative quarterly figures, trigger a tax calculation, read the result, and eventually submit the final declaration. Each is another endpoint with the same two gates you've already cleared.

The kindest thing I can tell a beginner is to lean on HMRC's own tooling: the sandbox, the test users, and especially the fraud-header validator. Drive each of those to a clean result and the integration stops feeling like a regulatory maze and starts behaving like an ordinary, if unusually careful, REST API.

I work on TapTax, a Making Tax Digital app for UK sole traders, which is where I picked up the details above.

About the author: Solomon Amos is the founder of TapTax and built its HMRC Making Tax Digital integration. He has spent the last three years as a lead technical architect on HMRC digital modernisation programmes, and holds a PhD in engineering, with research in machine learning. You can find him on LinkedIn.

A Slack read uses that user's workspace. A GitHub issue is created as that user, in a repository they can access. An agent can make the wrong call, but it must never act with the wrong user's access.

The fix has two parts, and both appear in the first half of this tutorial:

1. Each user grants access separately. Alice authorizes Slack for herself. Bob authorizes it for himself.

2. Your agent passes an identifier, not a token. A string like alice@example.com selects whose grant to use. One function turns it into a token at the moment of the call, and that token never reaches your model inputs, your tool schemas, or your logs.

Most agent tutorials stop before either point. They hand you an API key, wire up one function, and the model calls it. The design works until a second person shows up.

To make the pattern concrete, you'll build a command-line agent that watches a Slack channel, decides on its own which messages describe real work, files a GitHub issue for those, and replies in the Slack thread with the issue link. Every call runs as one user's own OAuth grant.

You'll write the OAuth flow yourself: the consent redirect, the state check, the token exchange, an encrypted store, and the refresh path. None of it is long, and seeing it whole is what makes the identity argument checkable instead of a claim you take on faith.

Two topics stay out of scope here: we won't cover Model Context Protocol servers or voice or realtime hosts. The identity pattern holds in both settings, but the surrounding plumbing deserves its own article.

Table of Contents

• What You'll Build

• Prerequisites

• What Are AI Agent Tools?

• Why a Shared Token Breaks

• Architecture Overview

• How to Register the Slack and GitHub OAuth Apps

• How to Run the Consent Flow

• How to Store Tokens Encrypted, Keyed by User

• How to Run Tool Calls as the Current User

• How to Handle Refresh and Revocation

• How to Add a Second Provider

• Full Walkthrough

• How to Apply the Pattern to Other Use Cases

• What Went Wrong When I Built This

• Conclusion

What You'll Build

The agent is called channel-watcher-agent. Each run does four things:

1. Reads recent messages from a Slack channel.

2. Asks a model, message by message, whether the text describes a bug or a concrete action item.

3. Files a GitHub issue for the messages that qualify.

4. Replies in the original Slack thread with a link to the new issue.

Nobody clicks a button to start any of it. Slack already ships a "create an issue from this message" action, which is a different product. Here the agent reads the channel, forms its own judgment, and acts only on what it judges worth acting on.

The stack stays small on purpose:

Three of those five ship with Node. The only packages you install are the AI SDK and its friends.

By the end you'll have:

• Two OAuth apps, Slack and GitHub, that a user consents to once.

• An encrypted token store keyed by user and provider.

• An agent that resolves the current user to an identifier and never lets a token reach the model.

• A tool loop where the model decides whether to file an issue at all.

• A demonstration that a second user's run stops instead of reading the first user's data.

The finished code lives at github.com/saif-shines/channel-watcher-agent.

Prerequisites

Accounts and tools:

• Node.js 22.13 or newer, plus npm. The token store uses node:sqlite, which is stable from that version on.

• A Slack workspace where you can install apps, and a channel to watch. A throwaway channel works best.

• A GitHub account and a repository that can absorb test issues.

• An API key for a model provider the AI SDK supports. Anthropic is used in the examples.

• mkcert, to issue a local HTTPS certificate. How to Register the Slack and GitHub OAuth Apps explains why an ordinary http://localhost callback will not do.

Useful background, though none of it is a hard requirement:

• async and await, and reading a small Node script.

• OAuth 2.0 at a high level: an app redirects a user to a provider, the user consents, the app receives a token.

• Tool calling, sometimes called function calling. The next section covers what the tutorial needs.

One warning before starting: The agent writes to real systems. It opens real GitHub issues and posts real Slack messages. Use a test Slack channel and a throwaway GitHub repository while you're still checking that it only acts on messages you intend.

What Are AI Agent Tools?

A tool is a function you hand the model along with your input. The model can't run that function itself. It can only ask: call fileGithubIssue with this title and this body. Your code performs the call, returns the result, and the model uses that result to choose the next step.

Request, execute, return. The exchange is the whole mechanism, and everything called an "agent" is a loop around it.

How a Tool Differs from an API

Tools and APIs wrap the same call but are written for different readers.

An API is written for you. It assumes you read the documentation, and that you know thread_ts is the field that turns a Slack message into a threaded reply.

A tool is written for a model that has read nothing. So a tool carries its own explanation:

• A name the model can reason about, like fileGithubIssue.

• A description in plain language, including when not to use the tool.

• A schema for the inputs, so the model knows title is a required string.

Below is one tool from the project. Most of the code is explanation rather than logic:

const fileGithubIssue = tool({
  description: 'File a GitHub issue for an actionable Slack message',
  inputSchema: z.object({
    title: z.string(),
    body: z.string(),
  }),
  execute: async ({ title, body }) => {
    // ... the actual API call goes here
  },
});

The description and inputSchema are the parts the model sees. The execute function is yours alone. Identity gets settled inside execute, so the model never learns which account the call ran against.

Why Models Handle Tools Better Than Raw API Calls

Pasting a curl command into the input and asking the model to fill in the blanks is possible. But this approach fails in predictable ways.

Tools work better for three reasons:

1. The schema is enforced before your code runs. A malformed tool call gets rejected and retried by the SDK. A malformed URL fails at runtime instead.

2. Results return to the model. After fileGithubIssue returns, the model can read the new issue URL and use it in the Slack reply. The chaining is what makes the second step possible.

3. Credentials stay out of the conversation. The model asks for an action by name and never sees a token. A token it never sees can't leak into a completion, a log line, or a prompt-injection payload.

Reason three is what the rest of this tutorial builds toward. You'll keep tokens out of the model on purpose: the agent holds an identifier, and a token appears only at the moment of the provider call.

Most Agents Need More Than One App

Few useful agents talk to a single app. A support agent reads Zendesk and updates Salesforce. A standup agent reads GitHub and posts to Slack. A scheduling agent reads Gmail and writes to Google Calendar.

Each app brings its own OAuth registration, scope names, token lifetime, and refresh behavior. Multiply the list by every user of the agent, and the real problem appears.

Why a Shared Token Breaks

One shared credential for everybody works in a demo and fails once a second person shows up. Picture the quick version of the Slack half: create a Slack app, install it, copy the bot token into .env, and let every tool call use it.

Three problems arrive together.

First, every run uses the same permissions. The bot sees every channel it was invited to, no matter who triggered the run. Ask the agent about a channel you were never in, and the bot reads it anyway. The agent has become a way around your own workspace permissions.

Second, the audit trail is also wrong. Every GitHub issue says the bot opened it. Every Slack reply comes from the bot. Asked why an issue exists, the honest answer is "an agent filed it for somebody, and we can't tell who."

And third, revocation stops working. A user leaves the company and their Slack account is deactivated. The agent keeps running, because it never used their credentials.

The alternative is per-user grants. Each user authorizes the apps for themselves. That creates a new requirement, though: somewhere to keep those grants.

The Distinction is One Field in One Response

Slack makes the difference unusually easy to see. When a user finishes the consent screen, the token exchange returns both kinds of token in the same JSON object:

{
  "ok": true,
  "access_token": "xoxb-REDACTED-BOT-TOKEN",
  "token_type": "bot",
  "authed_user": {
    "id": "U0A1B2C3D",
    "scope": "channels:history,chat:write,users:read",
    "access_token": "xoxp-REDACTED-USER-TOKEN",
    "token_type": "user"
  }
}

The top-level access_token is the bot. The nested authed_user.access_token is the person who just consented. Reading conversations.history with the first one returns every channel the app was invited to. Reading it with the second returns only the channels that users can already see. The same split governs writes: chat.postMessage with a user token posts under that person's name.

Two fields, one letter apart in the prefix, and the entire permission model of your agent hangs on which one you store. This tutorial requests only user scopes, so Slack issues no bot token at all.

Tokens Must Stay Out of the Model and the Logs

Per-user tokens become the most sensitive data in the system. Two destinations are off limits:

• The model: Keep tokens out of inputs, tool descriptions, and tool return values. A model that has seen a token can repeat it, and prompt injection turns any tool result into untrusted input.

• Your logs: Tool inputs and outputs are exactly what you want to log while debugging an agent. Tokens traveling in those payloads land in your log store permanently.

This tutorial keeps tokens on one narrow path. Your code passes an identifier, a stable reference to one user. One helper turns that identifier into a token, and from there the token goes straight into a provider call and nowhere else. It's never named in a tool schema, never attached to anything the model can read, and never returned from a tool.

Why You Own the OAuth Apps and the Store

The point of writing the flow yourself isn't the plumbing. It's control over who may use whose grant.

In this tutorial the users are teammates. Each person connects their own Slack and GitHub, and the agent acts as whoever triggered the run. The same design holds when those users are customers of your product: each person still has their own grant, and a wrong mapping means one person's run using someone else's access. Only the source of the identifier changes. A session for teammates, a tenant record for customers.

Architecture Overview

Two flows matter, and they happen at different times. Keeping them separate is most of the work.

Connection time happens once per user, per app. The user consents, and tokens land in your store. The agent isn't running.

Runtime happens on every execution. The agent resolves the current user to an identifier and does its work. No consent screens and no browser.

CONNECTION TIME (once per user, per app)

  Your user              connect.js              Slack / GitHub
     |                       |                         |
     |-- "connect Slack" --->|                         |
     |<--- consent link -----|                         |
     |----------------------- OAuth consent ---------->|
     |                       |<--- redirect + code ----|
     |                       |---- exchange code ----->|
     |                       |<---- tokens ------------|
     |                       |                         |
     |                  [encrypt, store                |
     |                   under (identifier,            |
     |                   provider)]                    |
     |                       |                         |


RUNTIME (every agent run)

  Your agent             Token store             Slack / GitHub
     |                       |                         |
  [resolve identifier        |                         |
   from your own session]    |                         |
     |                       |                         |
     |-- getAccessToken( --->|                         |
     |     identifier,       |                         |
     |     provider )        |                         |
     |<---- token -----------|                         |
     |                       |                         |
     |------------------ API call as user ------------>|
     |<----------------- result -----------------------|
     |                       |                         |
  [model sees result,        |                         |
   never a token]            |                         |

Three properties follow from the shape.

The identifier replaces the token in your agent code. Everything above the token store handles a string like alice@example.com or user_8f21c. The string is worthless on its own: without the store and its encryption key, it opens nothing.

One identity spans many apps. A single identifier has a Slack row and a GitHub row beneath it. A third app doesn't create a third identity to reconcile.

Authorization stays in your code. The store answers which tokens belong to an identifier. The store can't know whether the request deserved an answer. Deciding that the caller may act as that identifier happens before any call.

One rule follows, and bending it defeats the whole design: resolve the identifier server-side from an authenticated session. Never accept an identifier from a request body, a query parameter, or a browser. An identifier accepted from a client is an "act as any user" endpoint.

How to Register the Slack and GitHub OAuth Apps

The walkthrough uses Slack and GitHub as the two providers end to end. Both need the same three things: a registered app, a redirect URI, and a set of scopes. The details differ enough to be worth walking through separately.

The Redirect URI Has to Use HTTPS

Most tutorials that touch OAuth hand you http://localhost:3000/callback and move on. Slack rejects it. Slack's documentation states flatly that "a Redirect URL must also use HTTPS", and it makes no exception for localhost. GitHub is more relaxed and accepts either, so a single HTTPS callback satisfies both.

The rule looks pedantic, because on localhost the request never leaves your machine and there's nothing on the wire to intercept. Slack applies it uniformly anyway, and a uniform rule with no exemptions is a defensible choice for a provider handing out credentials: every exemption is a branch somebody has to get right, and "is this really localhost" is a question that has been answered incorrectly before.

mkcert issues a certificate signed by a local authority it adds to your system trust store, so the browser accepts it without a warning:

mkcert -install
mkcert localhost

That writes localhost.pem and localhost-key.pem into the current directory. A tunneling service such as ngrok also works, but its free URLs rotate, which means re-editing both app registrations every session.

The Slack App, and the One Setting That Matters

At api.slack.com/apps, create an app in your workspace. Then open OAuth & Permissions and set two things.

Add https://localhost:3000/callback under Redirect URLs.

Then find the scopes. The page has two sections, and choosing the wrong one silently rebuilds the shared-bot design:

Under User Token Scopes, add:

• channels:history: read messages in public channels the user belongs to

• chat:write: post as the user

• users:read: turn user IDs into names

Leave Bot Token Scopes empty. Copy the Client ID and Client Secret from Basic Information.

The GitHub OAuth App

Under Settings → Developer settings → OAuth Apps → New OAuth App, set the Authorization callback URL to the same https://localhost:3000/callback, then generate a client secret. GitHub documents the web application flow in full if you want the surrounding detail.

GitHub's scope for issue creation depends on the repository:

• repo covers private repositories, and grants read and write access to code along with it.

• public_repo is the narrower choice, and enough when your test repository is public.

Take the narrower one when you can. A scope you didn't need is a scope you have to explain later.

The Environment File

Both apps produce a client ID and a client secret, and the store needs an encryption key. Generate the key first:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

Then fill in .env:

OAUTH_REDIRECT_URI=https://localhost:3000/callback
TLS_CERT_PATH=./localhost.pem
TLS_KEY_PATH=./localhost-key.pem

SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

TOKEN_ENCRYPTION_KEY=

SLACK_CHANNEL_ID=C0XXXXXXXXX
GITHUB_REPO=your-name/your-test-repo

Those client secrets authenticate your application to the providers. They're not user credentials, and they never belong in a browser.

How to Run the Consent Flow

Everything provider-specific belongs in one place, so that adding a third provider later means adding an entry rather than a branch.

Step 1: Describe Each Provider Once

const REDIRECT_URI = process.env.OAUTH_REDIRECT_URI;

export const providers = {
  slack: {
    label: 'Slack',
    authorizeUrl: 'https://slack.com/oauth/v2/authorize',
    tokenUrl: 'https://slack.com/api/oauth.v2.access',

    // These go in `user_scope`, not `scope`. Scopes listed under `scope` grant
    // a bot token, and a bot token is what this project exists to avoid.
    userScopes: ['channels:history', 'chat:write', 'users:read'],

    buildAuthorizeUrl(state) {
      const url = new URL(this.authorizeUrl);
      url.searchParams.set('client_id', process.env.SLACK_CLIENT_ID);
      url.searchParams.set('user_scope', this.userScopes.join(','));
      url.searchParams.set('redirect_uri', REDIRECT_URI);
      url.searchParams.set('state', state);
      return url.toString();
    },
    // exchangeCode and refresh follow below
  },
};

The user_scope parameter is the whole argument in one line. Slack reads scope for bot permissions and user_scope for user permissions. This project sets only the second, so the response comes back with no bot token in it at all.

The state parameter isn't optional. It's a random string you generate, send to the provider, and check on the way back. Without it, any page on the internet can point a browser at your callback URL with an attacker's code attached, and your server will happily exchange it and store the attacker's token under your user's identifier.

Step 2: Exchange the Code, and Take the Right Token

async exchangeCode(code) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      code,
      client_id: process.env.SLACK_CLIENT_ID,
      client_secret: process.env.SLACK_CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
    }),
  });

  const json = await response.json();

  // Slack answers HTTP 200 even when the exchange failed. The `ok` field
  // is the real status.
  if (!json.ok) {
    throw new Error(`Slack token exchange failed: ${json.error}`);
  }

  return normalizeSlackTokens(json.authed_user);
}

Two details in that function cost real debugging time when missed.

Slack returns HTTP 200 for failures. Checking response.ok tells you the HTTP request succeeded, which it did. The json.ok field is the one that reports whether the OAuth exchange worked.

json.authed_user, not json. This is the fork from the section above, expressed as one property access. Reading json.access_token here would compile, run, store a token, and quietly give every user of your agent the same bot identity.

Normalizing the result keeps the rest of the codebase provider-agnostic:

function normalizeSlackTokens(authedUser) {
  return {
    accessToken: authedUser.access_token,
    refreshToken: authedUser.refresh_token ?? null,
    expiresAt: authedUser.expires_in
      ? Date.now() + authedUser.expires_in * 1000
      : null,
    scope: authedUser.scope,
  };
}

GitHub's version of the same function differs in two ways worth noting:

async exchangeCode(code) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    // Without this header GitHub answers with a form-encoded body.
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Accept: 'application/json',
    },
    body: new URLSearchParams({
      code,
      client_id: process.env.GITHUB_CLIENT_ID,
      client_secret: process.env.GITHUB_CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
    }),
  });

  const json = await response.json();
  if (json.error) {
    throw new Error(
      `GitHub token exchange failed: ${json.error_description ?? json.error}`
    );
  }

  // OAuth App tokens carry no expiry, so there is nothing to refresh.
  return {
    accessToken: json.access_token,
    refreshToken: null,
    expiresAt: null,
    scope: json.scope,
  };
}

The Accept: application/json header is easy to skip and produces a confusing failure: response.json() throws on a body that came back as access_token=gho_...&scope=repo.

Step 3: Catch the Redirect

OAuth needs somewhere to land. For a command-line tool, a server that starts, handles one callback per provider, and exits is enough. Because Slack demands HTTPS, the scheme in OAUTH_REDIRECT_URI decides which kind of server to start:

function createCallbackServer(handler) {
  if (redirect.protocol !== 'https:') {
    return createHttpServer(handler);
  }

  try {
    return createHttpsServer(
      {
        cert: readFileSync(process.env.TLS_CERT_PATH),
        key: readFileSync(process.env.TLS_KEY_PATH),
      },
      handler
    );
  } catch (err) {
    throw new Error(
      `Could not read the TLS certificate (${err.code ?? err.message}).\n` +
        'Generate a locally-trusted one with mkcert:\n' +
        '  mkcert -install\n' +
        '  mkcert localhost\n' +
        'then point TLS_CERT_PATH and TLS_KEY_PATH at the two files it writes.'
    );
  }
}

A missing certificate is going to happen to somebody, and ENOENT on its own explains nothing about OAuth. The catch block spends four lines saying what to run instead.

The handler itself is where state gets checked:

const pending = new Map();

function handleCallback(request, response) {
  const url = new URL(request.url, redirect.origin);

  if (url.pathname !== redirect.pathname) {
    response.writeHead(404).end('Not found');
    return;
  }

  const state = url.searchParams.get('state');
  const entry = pending.get(state);

  if (!entry) {
    response.writeHead(400).end('State mismatch. Start the flow again.');
    return;
  }

  pending.delete(state);

  const error = url.searchParams.get('error');
  if (error) {
    response.writeHead(400).end(`Authorization denied: ${error}`);
    entry.reject(new Error(`[${entry.provider}] authorization denied: ${error}`));
    return;
  }

  entry.finish(url.searchParams.get('code'), response);
}

The pending map is the state check. A state value gets into that map only when this process generated it, and it's deleted the moment it's used. An unrecognized state means the callback didn't come from a flow you started, and a state that arrives twice means a replay. Both fall out of one Map lookup.

Generating the state and waiting for its callback:

function connect(providerName) {
  const provider = providers[providerName];
  const state = randomBytes(16).toString('hex');

  console.log(`\n[${providerName}] authorize as "${IDENTIFIER}":`);
  console.log(provider.buildAuthorizeUrl(state));

  return new Promise((resolve, reject) => {
    pending.set(state, {
      provider: providerName,
      reject,
      async finish(code, response) {
        const tokens = await provider.exchangeCode(code);
        saveGrant(IDENTIFIER, providerName, tokens);
        response
          .writeHead(200, { 'Content-Type': 'text/html' })
          .end(`<p>${provider.label} connected. You can close this tab.</p>`);
        resolve();
      },
    });
  });
}

randomBytes(16) and not Math.random(). A predictable state parameter is the same as no state parameter.

Running it walks each unconnected provider in turn:

[slack] authorize as "alice@example.com":
https://slack.com/oauth/v2/authorize?client_id=123.456&user_scope=channels%3Ahistory%2Cchat%3Awrite%2Cusers%3Aread&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback&state=1159699dbf1a808fd33ba31c7b643505

Notice what that URL doesn't contain: any scope parameter. Slack has no instruction to mint a bot token, so it won't.

How to Store Tokens Encrypted, Keyed by User

The store answers one question: which token belongs to this user, for this provider? Everything else about it follows from keeping that answer safe.

node:sqlite has shipped with Node since v22.5, and stopped requiring a flag in v22.13. That makes a real database available with nothing to install:

import { DatabaseSync } from 'node:sqlite';
import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';

const KEY = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY ?? '', 'base64');

if (KEY.length !== 32) {
  throw new Error(
    'TOKEN_ENCRYPTION_KEY must be 32 bytes, base64-encoded. ' +
      `Got ${KEY.length} bytes.`
  );
}

const db = new DatabaseSync(
  process.env.TOKEN_DB_PATH ?? new URL('../tokens.db', import.meta.url).pathname
);

// One row per user, per provider. expires_at stays outside the ciphertext so
// a token's freshness can be checked without decrypting it.
db.exec(`
  CREATE TABLE IF NOT EXISTS grants (
    identifier TEXT    NOT NULL,
    provider   TEXT    NOT NULL,
    ciphertext BLOB    NOT NULL,
    iv         BLOB    NOT NULL,
    auth_tag   BLOB    NOT NULL,
    expires_at INTEGER,
    PRIMARY KEY (identifier, provider)
  )
`);

The composite primary key is the isolation guarantee, written down. (identifier, provider) means Alice's Slack row and Bob's Slack row can't collide, and no query that supplies both parts can return somebody else's grant.

expires_at sits outside the ciphertext deliberately. Checking whether a token needs refreshing is something you do before every call. Decrypting to find out would mean decrypting constantly, so the one field that isn't a secret stays readable.

Encryption is AES-256-GCM, which authenticates as well as encrypts:

function encrypt(payload) {
  const iv = randomBytes(12);
  const cipher = createCipheriv('aes-256-gcm', KEY, iv);
  const ciphertext = Buffer.concat([
    cipher.update(JSON.stringify(payload), 'utf8'),
    cipher.final(),
  ]);
  return { ciphertext, iv, authTag: cipher.getAuthTag() };
}

function decrypt({ ciphertext, iv, authTag }) {
  const decipher = createDecipheriv('aes-256-gcm', KEY, iv);
  decipher.setAuthTag(authTag);
  const plaintext = Buffer.concat([
    decipher.update(ciphertext),
    decipher.final(),
  ]);
  return JSON.parse(plaintext.toString('utf8'));
}

Three rules govern that pair, and breaking any one of them is worse than not encrypting at all, because it looks like it worked:

1. A fresh IV per encryption: Reusing an initialization vector with GCM is a catastrophic failure, not a minor one. randomBytes(12) on every call, stored beside the ciphertext.

2. Keep the auth tag: GCM produces a tag that proves the ciphertext wasn't altered. Without setAuthTag on the way back, you have encryption without integrity, and decipher.final() won't complain.

3. Encrypt the whole token object, not each field. One ciphertext for { accessToken, refreshToken, scope } means one IV and one tag to manage rather than three of each.

Writing and reading are then unremarkable:

export function saveGrant(identifier, provider, tokens) {
  const { ciphertext, iv, authTag } = encrypt(tokens);
  db.prepare(
    `INSERT INTO grants (identifier, provider, ciphertext, iv, auth_tag, expires_at)
     VALUES (?, ?, ?, ?, ?, ?)
     ON CONFLICT (identifier, provider) DO UPDATE SET
       ciphertext = excluded.ciphertext,
       iv         = excluded.iv,
       auth_tag   = excluded.auth_tag,
       expires_at = excluded.expires_at`
  ).run(identifier, provider, ciphertext, iv, authTag, tokens.expiresAt ?? null);
}

The ON CONFLICT clause matters more than it looks. Re-consenting has to replace a grant rather than fail or duplicate it, and re-consenting is exactly what a user does after a revocation or a scope change.

The encryption key itself lives in .env here, which is right for a tutorial and wrong for production, where it belongs in a secrets manager or a KMS. Losing it makes every stored grant unreadable and forces every user to consent again. That is a real outage, but it's a better one than the alternative: a stolen database file that hands over working tokens for every user of your agent.

How to Run Tool Calls as the Current User

Runtime has three moves: resolve the identifier, fetch a token with it, and wrap the whole thing as a tool.

Step 1: Resolve the Identifier, Then Authorize

An identifier is any stable string that represents one user, an email address, a user ID, a tenant-scoped key.

// In a real app this comes from your authenticated session, resolved
// server-side. Never accept it from client input.
const IDENTIFIER = process.argv[2] ?? 'channel-watcher-agent';

Reading the identifier from argv keeps the demo runnable without a login, and it makes the isolation test later in this tutorial a single command. A real application replaces the line:

// Real app: resolve from your authenticated session, server-side.
const session = await getSession(request);                  // your auth
const identifier = await lookupIdentifier(session.userId);  // your database

Order matters in those two lines. Authenticate the caller first, then look up which identifier the caller may act as. An identifier arriving from a client turns the endpoint into a reader of any user's Slack.

Step 2: Turn the Identifier into a Token, Late

One function stands between the identifier and every provider call:

const REFRESH_WINDOW_MS = 60_000;

export async function getAccessToken(identifier, providerName) {
  const grant = readGrant(identifier, providerName);

  if (!grant) {
    throw new Error(
      `[${providerName}] no grant for "${identifier}".\n` +
        `Connect it first: node src/connect.js ${identifier}`
    );
  }

  const expiringSoon =
    grant.expiresAt !== null &&
    grant.expiresAt !== undefined &&
    grant.expiresAt - Date.now() < REFRESH_WINDOW_MS;

  if (!expiringSoon) {
    return grant.accessToken;
  }

  if (!grant.refreshToken) {
    throw new Error(
      `[${providerName}] token for "${identifier}" expired and no refresh ` +
        'token is stored. The user has to consent again.'
    );
  }

  const refreshed = await providers[providerName].refresh(grant.refreshToken);
  saveGrant(identifier, providerName, refreshed);
  return refreshed.accessToken;
}

Call this immediately before the API call, not once at startup. A long agent run can outlive a twelve-hour token, and resolving tokens up front means discovering that at the least convenient moment. Fetching late costs one cheap database read and removes the whole class of problem.

Also, the sixty-second window isn't padding for its own sake. A token with four seconds left passes a naive expiry check and then expires in flight. Refreshing anything inside the window means the token handed back is good for at least a minute of work.

Finally, a missing grant raises an error rather than falling back. There's nothing sensible to fall back to. The correct outcome for an unconnected user is a stop, with a message saying how to connect.

Step 3: Wrap Provider Calls as Tools

Identity gets injected here, one layer below anything the model can influence:

export function buildTools(identifier) {
  const [owner, repo] = process.env.GITHUB_REPO.split('/');

  const fileGithubIssue = tool({
    description: 'File a GitHub issue for an actionable Slack message',
    inputSchema: z.object({
      title: z.string(),
      body: z.string(),
    }),
    execute: async ({ title, body }) => {
      const token = await getAccessToken(identifier, 'github');
      return createIssue(token, owner, repo, { title, body });
    },
  });

  const replyInSlackThread = tool({
    description:
      'Reply in the original Slack thread (e.g. with the created issue link)',
    inputSchema: z.object({
      text: z.string(),
      thread_ts: z.string(),
    }),
    execute: async ({ text, thread_ts }) => {
      const token = await getAccessToken(identifier, 'slack');
      return postThreadReply(
        token,
        process.env.SLACK_CHANNEL_ID,
        text,
        thread_ts
      );
    },
  });

  return { fileGithubIssue, replyInSlackThread };
}

Compare what the model controls against what it can't. The model chooses title, body, and text. The model can't choose the user. identifier is a closure argument, fixed before the model ran, and it appears in no inputSchema. There's no input that makes the model file an issue as somebody else, because the account isn't one of its inputs.

Return values deserve one audit each. createIssue returns the issue number, URL, and title. postThreadReply returns a timestamp. Neither returns a token, and neither returns the raw provider response, which is where a token would hide if one were going to.

The provider calls themselves are ordinary HTTP:

export async function createIssue(token, owner, repo, { title, body }) {
  const response = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/issues`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        Accept: 'application/vnd.github+json',
        'X-GitHub-Api-Version': '2022-11-28',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ title, body }),
    }
  );

  const json = await response.json();

  if (!response.ok) {
    // 403 here usually means the grant is missing the `repo` scope.
    throw new Error(
      `GitHub issue creation failed (${response.status}): ${json.message}`
    );
  }

  return { number: json.number, url: json.html_url, title: json.title };
}

Step 4: Read the Channel

Slack's conversations.history returns clean JSON, with one gap: messages carry a user ID, never a display name. Turning those into names means a users.info call each, which is what users:read was in the scope list for.

export async function readChannel(token, channelId, limit = 20) {
  const { messages } = await slackCall(token, 'conversations.history', {
    channel: channelId,
    limit: String(limit),
  });

  const authors = await resolveAuthors(
    token,
    messages.filter((m) => m.user).map((m) => m.user)
  );

  return messages
    .filter((message) => message.text)
    .map((message) => ({
      author: authors.get(message.user) ?? 'unknown',
      userId: message.user,
      text: message.text,
      ts: message.ts,
    }))
    .reverse(); // oldest first
}

Three small decisions in that function:

1. Names cost one users.info call per unique author. Caching them per run keeps a channel full of one person's messages from producing twenty identical lookups. A lookup that fails falls back to the user ID rather than throwing, since an unresolvable name isn't a reason to abandon the run.

2. Messages without text get dropped. Channel joins and purpose changes arrive as message objects with no body, and there's nothing for the model to triage in them.

3. .reverse() isn't cosmetic. Slack returns newest first. A model reading a conversation backwards will misread which message answered which.

The ts field then does double duty. It identifies a message, which makes it both the thread anchor for replies and the key for remembering what the agent already handled:

const state = await loadState();
const processed = new Set(state[IDENTIFIER]?.processedTs ?? []);
const newMessages = messages.filter((m) => !processed.has(m.ts));

Key that state by identifier, as the snippet does. A single flat list lets one user's processed messages hide another's, which reintroduces cross-user bleed in the one place the whole design exists to prevent.

Step 5: Run the Tool Loop

Hand the model both tools and let it decide:

const { text } = await generateText({
  model: anthropic(process.env.MODEL),
  tools,
  stopWhen: stepCountIs(5),
  prompt: `You triage messages from a dev team's Slack channel.

Message from ${message.author}: "${message.text}"
Message timestamp (thread_ts): ${message.ts}

Decide if this message is actionable (a bug report or concrete action item) or just noise (chit-chat, join notices, already-resolved chatter).

If actionable: file a GitHub issue with a clear title and body drafted from the message, then reply in the original Slack thread (use the exact thread_ts above) with a short note and the created issue's URL.

If not actionable: do nothing and briefly say why.`,
});

The loop is what makes the second step possible. The model reads the message and may call fileGithubIssue. The AI SDK runs the tool, feeds the result back into context along with the new issue URL, and calls the model again. Now the model can reply in the thread with a URL it couldn't have known on the first pass. Then it stops.

stopWhen: stepCountIs(5) caps the rounds. Without a bound, a confused model can retry a failing tool indefinitely. Five rounds is generous for two tools.

A deterministic version is also reasonable: classify with a structured-output call, then call both tools yourself in a fixed order when the message qualifies.

The fixed sequence is easier to test and gives up real flexibility. A loop lets the model skip the reply, or file without replying, and adding a third tool needs no new branching. Choose the loop when the set of actions varies per input, and the fixed sequence when it never does.

One note on the provider line, for accuracy about what ran. The snippet above uses @ai-sdk/anthropic, which suits a direct Anthropic API key. My own tests went through an OpenAI-compatible gateway, which changes only the provider construction:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const gateway = createOpenAICompatible({
  name: 'gateway',
  baseURL: `${process.env.GATEWAY_BASE_URL}/v1`,
  apiKey: process.env.GATEWAY_API_KEY,
});
// then: model: gateway(process.env.MODEL)

The tools, the loop, and the token handling are identical either way. Only the model argument changes.

How to Handle Refresh and Revocation

Tokens end in two different ways, and only one of them is your code's problem**.** Expiry is routine and recoverable. Revocation is a decision somebody made, and the correct response is to ask for consent again.

The two providers in this tutorial sit at opposite ends of the range, which makes them a useful pair.

GitHub: Tokens That Don't Expire, Until They Do

An OAuth App user token has no expiry timestamp. There's no refresh token to store and no refresh call to make, which is why github.refresh() in this project does nothing but explain itself:

async refresh() {
  throw new Error(
    'GitHub OAuth App tokens do not expire. A failure here means the ' +
      'grant was revoked — send the user through consent again.'
  );
}

"Does not expire" is not the same as "lasts forever," and GitHub revokes tokens for several reasons worth knowing:

• The user revokes the authorization from their account settings.

• The token goes unused for one year.

• The token gets pushed to a public repository or gist, at which point GitHub revokes it automatically.

• The app accumulates more than ten tokens for the same user and scope combination, and the oldest are revoked.

The third one deserves a moment. GitHub scans public pushes for its own token formats and kills what it finds. That is a safety net, not a strategy, and the one thing it can't protect is a token in a private repository or a log file.

GitHub Apps behave differently from OAuth Apps, which is a common source of confusion when reading GitHub's documentation. A GitHub App's user access token expires in eight hours and comes with a refresh token good for six months. If you build on GitHub Apps instead, the Slack-shaped refresh path below is the one you want.

Slack: Rotation is Opt-in and Permanent

By default, a Slack user token doesn't expire either. Token rotation changes that, and it comes with a warning worth repeating: rotation can't be turned off once it's turned on. Enable it on a test app first.

With rotation on, tokens live twelve hours and arrive with a refresh token. The refresh call reuses the same endpoint as the initial exchange, with a different grant type:

async refresh(refreshToken) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: process.env.SLACK_CLIENT_ID,
      client_secret: process.env.SLACK_CLIENT_SECRET,
    }),
  });

  const json = await response.json();
  if (!json.ok) {
    throw new Error(`Slack token refresh failed: ${json.error}`);
  }

  return normalizeSlackTokens(json.authed_user ?? json);
}

Store the new refresh token, not just the new access token. Refresh tokens rotate too. Writing back only the access token leaves you holding a spent refresh token, and the failure arrives twelve hours later, which is a long time to wait to learn something.

That write-back is why getAccessToken calls saveGrant after refreshing rather than returning the token and moving on.

Treat a Dead Grant as a Normal State

A revoked grant isn't an exception in the exceptional sense. Users leave, administrators tighten scopes, and people change their minds about what an agent may do.

The shape that works is the one getAccessToken already uses: catch the failure, and surface a fresh authorization link rather than a stack trace. connect.js with the same identifier lets the user re-consent, ON CONFLICT overwrites the dead row, and nothing else in your user record changes.

How to Add a Second Provider

A second provider costs one OAuth app, one entry in the providers object, and one tool. Keeping identity in a single string is what buys the discount.

The agent has used two providers all along. Worth noticing is what the second one didn't require: no second identity, no second consent server, and no second token table.

export const providers = {
  slack: { /* ... */ },
  github: { /* ... */ },
};

Google Calendar as a third means a third entry with its own authorizeUrl, tokenUrl, scopes, and exchangeCode. The consent server loops over Object.keys(providers), so it picks the new one up without modification. The store already keys on (identifier, provider), so it needs no migration. Then one more tool:

const createCalendarEvent = tool({
  description: 'Create a calendar event',
  inputSchema: z.object({ summary: z.string(), start: z.string() }),
  execute: async ({ summary, start }) => {
    const token = await getAccessToken(identifier, 'google-calendar');
    // ...one more provider call
  },
});

The identifier doesn't change, your user table doesn't change, and the model's view of the world grows by exactly one tool.

The cost that doesn't scale down is the provider-specific knowledge. Each new provider brings its own scope vocabulary, its own error format, and its own answer to whether tokens expire. Slack and GitHub disagreed on all three, and a third will disagree differently. The registry pattern contains that knowledge in one object per provider rather than spreading it through your agent, but it doesn't make the knowledge unnecessary.

One caveat on consent: A grant is per user, per provider. Alice connecting Slack but not Calendar means her calendar tool calls fail, and failure is correct there, since she never consented. Treat it as a prompt to connect rather than an error, a point the Failure Modes section returns to.

Full Walkthrough

Clone the repository, install, and fill in .env:

git clone https://github.com/saif-shines/channel-watcher-agent.git
cd channel-watcher-agent
npm install
cp .env.example .env
# fill in both client IDs and secrets, the encryption key, channel ID, repo

Then connect. The command starts the callback server and prints one link per unconnected provider:

npm run connect

[slack] authorize as "channel-watcher-agent":
https://slack.com/oauth/v2/authorize?client_id=123.456&user_scope=channels%3Ahistory%2Cchat%3Awrite%2Cusers%3Aread&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback&state=1159699dbf1a808fd33ba31c7b643505
[slack] connected.

[github] authorize as "channel-watcher-agent":
https://github.com/login/oauth/authorize?client_id=Iv1.abc&scope=repo&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback&state=e6d13461099c391367266235f8313630
[github] connected.

All providers connected. Run: node src/index.js channel-watcher-agent

Open each link, consent, and the tab confirms. The state parameter in those URLs is checked on the way back. A callback carrying anything else gets a 400 and never reaches the token exchange.

Then run the agent against a channel holding ordinary chatter:

node src/index.js

The output from that run, against a channel with three unremarkable messages:

[channel-watcher-agent] 3 messages fetched, 3 new.

--- Alex: "Sending draft message" ---
The message "Sending draft message" is noise — it appears to be a test or
accidental send, not a bug report or concrete action item.

...

No tools called, and no issues filed. The negative case matters more than it looks. An agent with write access that can't say no is a liability, and a run over ordinary chatter is the cheapest available test of its restraint.

Now post an actual bug report in the channel:

hey the /export endpoint is timing out for any file over 50MB, been happening since yesterday's deploy

Run the agent again, and the state file keeps the earlier messages from being triaged twice.

Authorship is the part that matters. The GitHub account behind the identifier opens the issue, using that user's own OAuth grant, not a shared bot. The Slack reply comes from that person too. Revoke their access and the next run fails at getAccessToken, which is the correct outcome.

What Changes for a Second User

The identifier comes from the command line, so isolation is testable without building a login first:

node src/index.js                     # the identifier you already authorized
node src/index.js alice@example.com   # a different user entirely

The second command never reads the channel. It stops:

[slack] no grant for "alice@example.com".
Connect it first: node src/connect.js alice@example.com

The refusal is the whole point. Nothing about the agent changed between the two commands. Same providers, tools, and code. Only the identifier differed, and Alice hasn't consented, so no row exists to decrypt and the run stops before touching Slack.

A shared-bot version behaves differently. The second command would read the channel and file an issue as the bot, because no per-user grant was ever involved.

Once Alice consents, everything downstream follows her grant. readGrant returns her row. getAccessToken decrypts her token. The Slack read returns the channels she can see, and her GitHub account authors the issue.

Production replaces argv with a session lookup:

const identifier = await lookupIdentifier(session.userId);

Testing the Isolation Without Credentials

The repository includes a test suite that replaces fetch with stand-in Slack and GitHub endpoints, so the request building, response parsing, storage, and refresh logic all run without a single OAuth app registered:

npm test

Three of those tests are worth naming, because they check the claims this tutorial makes rather than the code's internals:

• Slack exchange keeps the user token and discards the bot token. The fixture returns both. The test asserts the stored value is the xoxp- one.

• Two users get two different tokens from identical tool inputs. Same text, same thread_ts, two identifiers, two different Authorization headers reaching the provider.

• A tool built for an unconnected user fails instead of falling back. It also asserts that zero provider calls were attempted, since failing after leaking a request isn't much of a failure.

Tests that pass on the first run are worth distrusting, so I checked these by breaking the code on purpose. Substituting the bot token for the user token, ignoring the identifier in buildTools, and exposing identifier in the model-visible schema each fail at least one test.

How to Apply the Pattern to Other Use Cases

Nothing in the pattern is specific to Slack triage. The shape is: read from one app, decide with a model, write to another app, all as one user.

Swapping the providers produces a different product:

Every row uses the same three pieces: a provider entry, a token lookup by identifier, and a tool. Only three things change: the OAuth app registrations, the API calls inside execute, and the input you write for the model.

The input is where your product lives. OAuth is plumbing. Deciding which messages deserve an issue, and what the issue should say, is judgment, and judgment is the part worth your weeks.

The same code supports two deployment shapes:

• Internal team agent: The identifier is the teammate who triggered the run. Runs on a schedule or a command.

• Customer-facing agent: The identifier comes from your tenant and user records. Runs on customer data, inside customer accounts.

The code stays identical. The consequences of a wrong identifier do not.

What Went Wrong When I Built This

These are problems I hit while building the project, in roughly the order they showed up. If you hit the same ones, the fix is usually small.

Slack Won't Save the Redirect URL

The symptom arrives before any code runs: the Slack app configuration page refuses to accept http://localhost:3000/callback.

Slack requires HTTPS on redirect URLs with no exception for localhost. Issue a local certificate with mkcert, register the https:// form, and point TLS_CERT_PATH and TLS_KEY_PATH at the files it wrote. GitHub accepts either scheme, so the same HTTPS URL works for both apps.

The Browser Warns That the Certificate Isn't Trusted

mkcert -install is the step that adds mkcert's local authority to your system trust store, and skipping it leaves a certificate no browser recognises.

Running it once fixes every certificate mkcert issues afterwards. A self-signed certificate made with openssl will always warn, since nothing trusts it.

The Redirect URI Doesn't Match

Both providers compare the redirect_uri you send against the one registered with the app, and the comparison is exact. A trailing slash, 127.0.0.1 in place of localhost, http where you registered https, or a different port all fail.

The error arrives before consent, on the provider's own page, which at least makes it easy to spot. Keep OAUTH_REDIRECT_URI as the single source and pass it in both the authorize URL and the token exchange, as the provider registry does.

The Callback Port is Already in Use

connect.js binds the port from OAUTH_REDIRECT_URI, and port 3000 is popular. An unhandled EADDRINUSE produces a stack trace that says nothing about OAuth, so the project catches it and says what to do instead.

Changing the port means changing it in three places: .env, the Slack app's redirect URLs, and the GitHub app's callback URL. Missing one produces the previous failure.

The State Check Rejects a Legitimate Callback

State values live in memory and are deleted once used. Restarting connect.js after opening the link, or refreshing the callback tab, both produce a state that's no longer in the map.

Both are correct rejections. Generate a fresh link and start again.

Tool Calls Return Permission Errors or Empty Results

A missing scope or a revoked grant causes both.

GitHub answers 403 with "Resource not accessible" when the grant lacks repo. Slack answers 200 with ok: false and an error like missing_scope. Fix the scope list, then send the user through consent again, since an existing grant doesn't gain scopes retroactively.

A partially-scoped grant fails at the point of use rather than at connection time, which is what makes the symptom look mysterious. The consent screen succeeded, the token stored fine, and the failure arrives during a tool call hours later.

The Agent Reads Channels it Shouldn't

The single most likely cause is storing json.access_token instead of json.authed_user.access_token during the Slack exchange. Both are strings, both are truthy, and both work (one works as the app rather than the person).

The tell is the scope of what comes back. A user token returns only that person's channels. If conversations.history returns a channel the current user was never in, a bot token is in the store.

A Tool Call Runs as the Wrong User

Passing a token or identifier belonging to somebody else will do the wrong thing correctly.

Two habits prevent it. Resolve the identifier server-side after authenticating the caller, never from client input. Then take the identifier as a closure argument in buildTools and let each execute fetch its own token, so no code path can pass a stray credential.

Refresh Works Once and Then Stops

Refresh tokens rotate. A refresh that writes back the new access token but keeps the old refresh token succeeds immediately and fails on the following cycle, which puts twelve hours between the bug and its symptom.

saveGrant takes the whole normalized token object for this reason. Write back everything the refresh returned.

The Agent Files Duplicate Issues

Two causes. A missing or unwritten state file makes every run triage everything again. Or stopWhen allows enough rounds for a confused model to retry a tool that already succeeded.

Check the state file first. Then check whether the tool's return value clearly signals success, because an ambiguous result invites a retry.

Conclusion

You've built an agent that reads a Slack channel, judges which messages describe real work, files GitHub issues for those, and closes the loop with a threaded reply. Every call ran as one specific user's own OAuth grant, through an OAuth flow and a token store you wrote yourself.

Five ideas carry over to any provider:

• A tool is an API call plus an explanation for a model, and the explanation is most of the work.

• The identifier replaces the token in your agent code. Everything above one small function handles a reference to a user rather than a credential, so tokens never reach your model inputs or your logs.

• Connection time and runtime are separate flows. Consent happens once per user, per app. Runtime resolves an identifier and fetches a token late.

• Authorization stays yours. A token store answers which tokens belong to an identifier. Whether a caller may act as that identifier is a question only your code can answer.

• Multi-provider support is a registry problem, not an architecture problem, once identity lives in one string.

The detail that carries the most weight is also the smallest: authed_user.access_token rather than access_token. One property access decides whether your agent respects the permissions your workspace already has or quietly routes around them.

From here, keep the shape and swap the providers. Point the read half at Gmail and the write half at Linear, then rewrite the input for the model. The identity plumbing doesn't change.

The full source is at github.com/saif-shines/channel-watcher-agent.

This write-up reconstructs what we learned building Scalekit, a hosted version of the token vault you just built.

But if you ask them why a specific HTTP request exists or what breaks if you remove it, they often can't give a good explanation.

That's because OAuth is usually taught backward, in my opinion. Most tutorials start with definitions and sequence diagrams before establishing why the protocol was designed that way in the first place.

In this guide, we're going to fix that. We'll build up OAuth 2.0 concept by concept, starting from a real engineering problem and arriving at the protocol solutions naturally. By the time we write the code in Spring Boot, every parameter, redirect, and token will make total sense.

Here's What We'll Cover:

• The Problem Before OAuth

• What OAuth 2.0 Actually Is (And Isn't)

• Application Registration: Where Credentials Come From

• The Four Roles in OAuth 2.0

• Access Tokens and Scopes

• The Authorization Code Flow

• Why The Two-Step Redirect Exists

• Token Expiration and Refresh Tokens

• PKCE: Protecting Public Clients

• state vs. PKCE: Stopping Different Attacks

• OAuth 2.0 vs. OpenID Connect (OIDC) & JWTs

• What is OAuth 2.1?

• Production Security Pitfalls to Avoid

• Final Thoughts

The Problem Before OAuth

Imagine we're building TravelBuddy, a Spring Boot application that helps users plan trips.

TravelBuddy has a feature that automatically detects scheduling conflicts and inserts trip itineraries directly into the user's Google Calendar.

To do this, TravelBuddy needs access to Google Calendar's API. Specifically, it needs to read existing events and write new ones on behalf of the user, Alice.

How would we have solved this back in 2005 before OAuth existed?

The Password Sharing Anti-Pattern

Without a protocol like OAuth, TravelBuddy would've to ask Alice for her Google username and password.

Alice would type her Google password directly into TravelBuddy's UI. TravelBuddy would store her password in its database and use those credentials to log into Google whenever it needed to fetch or create calendar events.

This approach works, but it creates massive security and operational problems:

1. Over-privileged access: TravelBuddy only needs to manage calendar events. But because it has Alice's actual Google password, it can also read her Gmail, look at her Google Drive files, delete her photos, or change her account password. There's no way to give TravelBuddy limited access.

2. No revocation granular control: If Alice wants to stop TravelBuddy from accessing her calendar, her only option is to change her Google password. Doing so breaks every other application she previously authorized.

3. Storage liability for TravelBuddy: TravelBuddy is now storing plaintext or decryptable passwords for thousands of Google accounts. A single SQL injection or database leak on TravelBuddy's side compromises the master keys to its users' entire digital lives on Google.

4. Phishing normalization: Training users to enter their primary Google credentials into third-party apps teaches them terrible security habits.

We need a way for Alice to give TravelBuddy permission to perform specific actions on Google Calendar without ever giving TravelBuddy her Google password.

That capability is called delegated authorization, and that's precisely what OAuth 2.0 provides.

What OAuth 2.0 Actually Is (And Isn't)

OAuth 2.0 is an open standard for delegated authorization.

It provides a framework that allows a user to grant a third-party application limited access to their resources on another service without sharing their credentials.

Before moving forward, we must address the single most common misconception in web development.

Authentication vs. Authorization

Developers swap these terms constantly, but they answer two fundamentally different questions:

• Authentication (AuthN): Who are you? (Identity)

• Authorization (AuthZ): What are you allowed to do? (Permissions)

OAuth 2.0 is strictly an authorization framework. It doesn't specify how to authenticate a user, how to issue identity details, or how to store user accounts. It only cares about issuing permission keys (tokens) so one service can talk to another on a user's behalf.

When you click "Log in with Google" on a website, that interaction uses an extension built on top of OAuth called OpenID Connect (OIDC), which we'll cover later. But core OAuth 2.0 is entirely about authorization.

Application Registration: Where Credentials Come From

Before TravelBuddy can initiate an OAuth flow, we must register TravelBuddy in the Google Cloud Console.

During registration, Google prompts TravelBuddy for two key details:

1. Application Name & Logo: Presented on the user consent screen.

2. Redirect URIs: The exact callback URLs (for example, https://travelbuddy.com/login/oauth2/code/google) where Google is permitted to send authorization codes.

Once registered, Google issues two credentials to TravelBuddy:

• client_id: A public identifier (like a username) that identifies TravelBuddy. It;s safe to embed in public links or frontend code.

• client_secret: A confidential key (like a password) used by TravelBuddy's backend server to authenticate itself when exchanging authorization codes for tokens.

The Four Roles in OAuth 2.0

OAuth 2.0 defines four roles. Let's map them directly to our TravelBuddy example so these terms stop being abstract definitions.

• Resource Owner: The user who owns the data. In our example, this is Alice. She owns her Google Calendar.

• Client: The third-party application trying to access the user's data. In our example, this is TravelBuddy (our Spring Boot backend). It's called a "client" because it acts as a client to the API.

• Authorization Server: The server that authenticates the user, obtains their consent, and issues access tokens. In our example, this is Google's OAuth server (accounts.google.com).

• Resource Server: The server hosting the protected user data. In our example, this is the Google Calendar API (www.googleapis.com/calendar).

Notice how Google's responsibilities are split into two separate roles: the Authorization Server (which issues tokens) and the Resource Server (which hosts the API). In large organizations, these are frequently separate services maintained by different teams.

Access Tokens and Scopes

Instead of handing TravelBuddy her password, Alice approves the issuance of an Access Token.

An access token is a string of characters that acts like a temporary keycard. When TravelBuddy makes an HTTP request to Google Calendar, it presents this token in the headers.

An access token has three critical properties that passwords lack:

1. Limited Scope: It can only be used for specific permissions.

2. Limited Lifetime: It expires automatically after a short period (typically minutes or hours).

3. Revocable: Alice or Google can revoke the token at any point without impacting Alice's account password.

What is a Scope?

A scope is a string that defines the exact permission being requested. Instead of asking for "Google account access", TravelBuddy asks for specific scopes.

When TravelBuddy redirects Alice to Google, it specifies the requested scopes:

• Read calendar events: https://www.googleapis.com/auth/calendar.events.readonly

• Create/Edit calendar events: https://www.googleapis.com/auth/calendar.events

When TravelBuddy redirects Alice to Google, it specifies the requested scopes. Google displays these exact permissions to Alice:

"TravelBuddy would like permission to view and edit your Google Calendar events."

If Alice agrees, the access token Google issues will be bound strictly to those requested scopes. If TravelBuddy tries to use that same token to read Alice's emails, Google's Resource Server will reject the request with a 403 Forbidden status code.

The Authorization Code Flow

Now that we know the roles and tokens, how does TravelBuddy actually get an access token?

The standard, most secure flow for server-side applications (like our Spring Boot app) is the Authorization Code Flow.

Here's the sequence of events. We'll walk through every step in detail immediately after the diagram.

Let's break this down step-by-step.

Step 1: User Initiates Action

Alice is using TravelBuddy's UI and clicks "Connect Google Calendar."

Step 2: TravelBuddy Constructs Redirect URL

TravelBuddy's backend doesn't prompt for credentials. Instead, it generates a URL pointing to Google's Authorization Server and instructs Alice's browser to redirect there.

This URL looks like this:

GET https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=TRAVELBUDDY_CLIENT_ID&redirect_uri=https://travelbuddy.com/login/oauth2/code/google&scope=https://www.googleapis.com/auth/calendar.events&state=xyz123

Let's analyze what each parameter does:

• response_type=code: Tells Google we're using the Authorization Code flow.

• client_id: A public identifier Google gave to TravelBuddy when TravelBuddy registered as a developer app.

• redirect_uri: The URL where Google should send Alice back once she completes consent.

• scope: The permissions TravelBuddy is asking for.

• state: A random string generated by TravelBuddy to prevent Cross-Site Request Forgery (CSRF) attacks.

Step 3: Alice Authenticates and Consents

Alice's browser lands on Google's domain (accounts.google.com).

Google verifies whether Alice is logged in. If not, Google asks her to log in. TravelBuddy never sees this interaction.

Once authenticated, Google displays the consent screen listing TravelBuddy's name and the requested scopes.

Step 4 & 5: Google Issues an Authorization Code

Alice clicks "Approve." Google's authorization server redirects Alice's browser back to TravelBuddy's registered redirect_uri, attaching a short-lived Authorization Code and the state parameter in the query string:

GET https://travelbuddy.com/login/oauth2/code/google?code=4/0AX4XfWh...&state=xyz123

TravelBuddy's backend verifies that the returned state matches what it originally sent. If it matches, TravelBuddy takes the code.

Step 6 & 7: TravelBuddy Exchanges the Code for a Token

Now TravelBuddy's backend server makes a direct, server-to-server POST request to Google's token endpoint (https://oauth2.googleapis.com/token):

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=4/0AX4XfWh...&
redirect_uri=https://travelbuddy.com/login/oauth2/code/google&
client_id=TRAVELBUDDY_CLIENT_ID&
client_secret=TRAVELBUDDY_CLIENT_SECRET

Google validates the authorization code and TravelBuddy's client_secret. If valid, Google responds with a JSON payload containing the access token:

{
  "access_token": "ya29.a0ARrdaM...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1//04rG...",
  "scope": "https://www.googleapis.com/auth/calendar.events"
}

Step 8 & 9: Calling the API

TravelBuddy now stores this access token securely and uses it to call the Google Calendar API on Alice's behalf:

GET /calendar/v3/users/me/calendarList HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer ya29.a0ARrdaM...

Google Calendar receives the request, extracts the Bearer token, checks with Google's auth infrastructure to verify it is valid and scoped correctly, and returns Alice's calendar data.

Why The Two-Step Redirect Exists

At this point, a junior developer almost always asks a great question:

"Why do we have Step 4 and 6? Why doesn't Google just return the access token directly in the redirect back to the browser in Step 4?"

Why bother returning a temporary authorization_code to the browser, only to immediately make another backend call to exchange it for the actual access_token?

The answer boils down to Front-Channel vs. Back-Channel security.

• The Front-Channel (the browser): The browser is an untrusted, highly exposed environment. Redirect URIs pass through browser histories, system logs, referrer headers, and browser extensions. If Google returned an access token directly in the browser's URL, that high-privilege token could easily leak or be intercepted by malicious extensions.

• The Back-Channel (server-to-server): The direct HTTPS network call between TravelBuddy's backend server and Google's auth server is private and encrypted. It bypasses the browser completely.

The Authorization Code acts as a temporary, single-use ticket (usually expiring in under 60 seconds). Even if an attacker steals the authorization code from the browser's URL history, they can't exchange it for an access token because they don't possess TravelBuddy's client_secret.

Token Expiration and Refresh Tokens

Access tokens are intentionally designed to be short-lived, typically expiring after one hour (expires_in: 3600).

Why? Because if an access token leaks, the window of opportunity for an attacker is strictly limited to whatever time remains before expiration.

But having Alice re-authenticate and click "Approve" every hour would offer a terrible user experience. TravelBuddy needs to sync calendars in the background while Alice is asleep.

To solve this, OAuth 2.0 introduces Refresh Tokens.

How Refresh Tokens Work

Depending on provider configuration (for example, passing access_type=offline and prompt=consent for Google), Google returns both an access_token and a long-lived refresh_token during the initial code exchange.

Then TravelBuddy encrypts and stores the refresh_token securely in its database.

When the access_token expires, TravelBuddy makes a background request directly to Google's token endpoint, presenting the refresh_token and client_secret.

Finally, Google validates the refresh token and issues a brand-new access_token without involving Alice at all.

PKCE: Protecting Public Clients

The Authorization Code flow we just discussed relies on TravelBuddy keeping its client_secret confidential. That is why TravelBuddy is classified as a Confidential Client. It runs on a server where developers can safely store environment variables and secrets.

But what if TravelBuddy is a Single Page Application (React/Vue running directly in the browser) or a Native Mobile App (iOS/Android)?

These are Public Clients. Anyone can open browser developer tools or decompile an Android .apk file to extract any embedded client_secret.

Without a secret, how can public clients safely use the Authorization Code flow? If a malicious app on a mobile device intercepts the authorization code, it could exchange that code for tokens because there is no client_secret stopping it.

To solve this, OAuth 2.0 introduced PKCE (Proof Key for Code Exchange, pronounced "pixie").

How PKCE Works

Before starting the flow, the client generates a cryptographic, random string called the code_verifier. The client hashes this string (typically using SHA-256) to produce the code_challenge.

In Step 2 of the Auth flow, the client sends the code_challenge and hash method code_challenge_method=S256) to the Authorization Server. The Authorization Server stores the code_challenge and returns the authorization code as usual.

In Step 6, when exchanging the code for tokens, the client sends the original unhashed code_verifier.

The Authorization Server hashes the provided code_verifier using SHA-256 and checks if it matches the stored code_challenge. If it matches, it proves that the app requesting the token is the exact same app that initiated the request.

Note: Modern OAuth security guidelines recommend using PKCE for all applications, including confidential backend applications like Spring Boot.

state vs. PKCE: Stopping Different Attacks

Developers often confuse state and PKCE because both involve random strings sent during the OAuth flow. But they protect against completely different attack vectors:

OAuth 2.0 vs. OpenID Connect (OIDC) & JWTs

Earlier, I emphasized that OAuth 2.0 is purely for authorization (permissions), not authentication (identity).

Yet, almost every app you use has a "Sign in with Google" button. How does that work?

Enter OpenID Connect (OIDC)

OpenID Connect is an identity layer built directly on top of OAuth 2.0.

While core OAuth issues an access_token meant for an API, requesting the openid scope instructs the Authorization Server to issue an ID Token alongside the access token:

When TravelBuddy requests the openid scope alongside calendar permissions:

scope=openid profile email https://www.googleapis.com/auth/calendar.events

Google's token endpoint responds with both an access_token AND an id_token.

• Access Token: Intended for the Resource Server (Google Calendar). TravelBuddy doesn't need to read its contents. It just passes it along in headers.

• ID Token: Intended specifically for TravelBuddy. It contains cryptographically signed information about Alice (for example, her Google User ID, full name, email, and profile picture URL).

What is a JWT?

An ID Token is almost always formatted as a JWT (JSON Web Token, pronounced "jot").

A JWT is a compact, URL-safe string containing three parts separated by dots: Header.Payload.Signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoding the middle section (Payload) reveals plain JSON:

{
  "sub": "google-user-id-98765",
  "iss": "https://accounts.google.com",
  "aud": "TRAVELBUDDY_CLIENT_ID",
  "email": "alice@gmail.com",
  "exp": 1711900000
}

Base64URL encoding is not encryption. Anyone who holds a JWT can read its contents. But because the token is signed using Google's private key, TravelBuddy's backend can verify Google's public signature locally without needing to call Google's servers to confirm Alice's identity on every request.

Is an Access Token always a JWT?

No. OAuth 2.0 intentionally doesn't mandate any specific format for access tokens.

An access token can be:

1. An Opaque Token: A completely random string (for example, ya29.a0ARrdaM...). The client and resource server must look up its meaning by querying the authorization server.

2. A Structured Token (like a JWT): Contains embedded claims so the resource server can validate it self-sufficiently.

What is OAuth 2.1?

If you work with modern security guidelines, you'll hear about OAuth 2.1.

OAuth 2.1 is not an overhaul of OAuth 2.0. It's a consolidation draft that incorporates years of security best practices into a single specification:

1. Mandatory PKCE: PKCE is required for all Authorization Code flows, including confidential server-side apps like Spring Boot.

2. Deprecation of Legacy Grants: The Implicit Grant (which returned tokens directly in browser URLs) and the Resource Owner Password Credentials Grant (which collected passwords directly) are removed entirely.

3. Exact Redirect URI Matching: Wildcards in redirect URIs are prohibited to prevent open-redirect exploits.

Production Security Pitfalls to Avoid

Building OAuth integrations in production requires careful attention to detail. Here are five of the most common security mistakes backend engineers make and how to avoid them:

1. Storing Tokens in Browser localStorage

If you're building a SPA client that receives access or refresh tokens, never store tokens in localStorage or sessionStorage.

Any script running on your page, including third-party analytics, chat widgets, or compromised npm dependencies, can read localStorage through a Cross-Site Scripting (XSS) vulnerability.

Fix: Store tokens inside HTTP-Only, Secure, SameSite cookies managed by your backend, or use a backend-for-frontend (BFF) architecture where tokens never reach the browser at all.

2. Leaking the Client Secret

It sounds obvious, but client_secret strings end up in public GitHub repositories constantly. Remember: any secret included in Android/iOS apps, React single-page apps, or frontend code is public.

Fix: Keep client secrets inside environment variables on server-side environments. Use PKCE for public clients where secrets can't be protected.

3. Requesting Unnecessary Scopes (Scope Creep)

Asking for full account access when you only need read permission makes users suspicious and increases your liability if a token leaks.

Fix: Follow the principle of least privilege. Request only the specific scopes your app needs immediately. If TravelBuddy later adds a feature to analyze emails, request the Gmail scope dynamically when the user activates that feature.

4. Assuming an OAuth Token Proves Identity

Just because an app receives an access_token from an API doesn't mean it can treat that token as proof of who logged in.

If an attacker passes a valid access token obtained from a different application (a confused deputy attack), your system might accept it if it only checks token validity without checking who the token was issued to aud / audience claim).

Fix: Use OpenID Connect (and validate the id_token claims including aud and iss) when authenticating users.

5. Skipping state or PKCE Validation

If you manually build OAuth flows without checking the state parameter, your application is vulnerable to Login Cross-Site Request Forgery (CSRF). An attacker could trick a user's browser into completing an OAuth flow using the attacker's authorization code, linking the victim's session to the attacker's account data.

Fix: Always generate a cryptographically strong, non-guessable state parameter bound to the user's session, or rely on established security frameworks like Spring Security that enforce this automatically.

Final Thoughts

OAuth 2.0 can feel overwhelming when viewed entirely as a web of specs, RFCs, and terminology.

When you strip away the jargon, OAuth solves one core problem: allowing a user to give an application permission to access their data without handing over their password.

Every moving part in the protocol exists to support that core mission safely:

• Scopes restrict permissions.

• Access Tokens provide temporary, revocable access.

• Authorization Codes keep tokens out of vulnerable browser URLs.

• Refresh Tokens maintain long-term access without harassing the user.

• PKCE protects public applications that can't keep secrets.

• OpenID Connect adds a standardized identity layer on top.

The next time you integrate an OAuth provider in Spring Boot or debug a token error in production, don't focus on memorizing the diagrams. Look at the HTTP request, ask which specific boundary it is crossing, and the design choices will make immediate sense.

Among the many authentication methods available, GitHub OAuth has emerged as a useful tool for improving user login experience while strengthening security measures.

Django, a Python web framework, has recently gained popularity in web development due to its efficiency and versatility. Adding GitHub OAuth to your Django projects helps improve the authentication process.

Django developers can use GitHub OAuth to access a user's GitHub profile and (with permission) their repositories to personalize the user experience and tailor application services.

This article will walk you through how to implement GitHub OAuth. You'll see the benefits to your Django projects as we go. By embracing this technology, you can give users a seamless login experience while adhering to strict security standards.

Prerequisites

If you wish to follow this guide, you need to have a basic understanding of these tools or have them installed on your PC:

• GitHub
• Django
• Django Rest Framework

How to Create a GitHub OAuth Application

You must sign into your GitHub account to create a GitHub OAuth application.

First, login to your GitHub account, click on your GitHub profile picture, and select Settings.

Login to GitHub and select "Settings" from the sidebar menu

Then, once the new page comes up, scroll to the bottom and select Developer Settings.

Scroll to the bottom and select "Develop Settings"

Select OAuth Apps and click on New OAuth App.

Creating a new OAuth app

Define your OAuth application by naming it.

• The Homepage URL should be the URL that leads to the homepage of your website.
• The Authorization callback URL should be a site, or a page users view after their GitHub account has been authenticated.

Once you are done defining it, click Register application.

Register your application once all the info has been filled in

Next, you'll need a client secret and a client ID key to access your GitHub OAuth app on your Django project.

The Client ID is already defined once you create an application. Click Generate a new client secret to create a client secret key.

Creating a client secret key

You might be prompted to sign in. Do so to continue.

Sign in to continue

Once you log in, your client's secret key will be generated. Copy and save it on your .env file.

Copy your secret key to your .env file

Now that you’ve set up your GitHub OAuth application, let’s connect it to your Django project.

How to Integrate GitHub OAuth with Django

This part will link your Django project's GitHub OAuth application to it using the social-auth app package.

First, install the dj-rest-auth package and define it on your settings.py.

pip install dj-rest-auth

Then configure dj-rest-auth package on your settings.py.

# Application definition
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "django.contrib.sites",
    "rest_framework",
    "rest_framework.authtoken",
    "dj_rest_auth",
    "allauth",
    "allauth.account",
    "allauth.socialaccount",
    "allauth.socialaccount.providers.github",
    "oauth2_provider",
    "users",
]

You'll need to enable the authentication classes for dj-rest-auth by updating REST_FRAMEWORK and AUTHENTICATION_BACKENDS on your settings.py.

Optionally, you can configure allauth if you intend to use templates. Do this on your settings.py file.

AUTHENTICATION_BACKENDS = ("allauth.account.auth_backends.AuthenticationBackend",)

REST_USE_JWT = True  # Use JWT for authentication with dj-rest-auth
SITE_ID = 1 #Set site ID

SITE_ID = 1  # Set the site ID

# Disable email verification for simplicity
ACCOUNT_EMAIL_VERIFICATION = "none"
LOGIN_REDIRECT_URL = "/"  # Redirect URL after successful login
LOGOUT_REDIRECT_URL = "/"  # Redirect URL after logout

SOCIALACCOUNT_PROVIDERS = {
    "github": {
        "APP": {
            "client_id": "YOUR_GITHUB_CLIENT_ID",
            "secret": "YOUR_GITHUB_SECRET_KEY",
            "key": "",
            "redirect_uri": "http://localhost:8000/accounts/github/login/callback/",
        }
    }
}

A Django app is required for this guide. Let's call it users. Head over to the views of the Django app and define the following code:

from allauth.socialaccount.providers.github.views import GitHubOAuth2Adapter
from allauth.socialaccount.providers.oauth2.client import OAuth2Client
from dj_rest_auth.registration.views import SocialLoginView

class GitHubLogin(SocialLoginView):
    adapter_class = GitHubOAuth2Adapter
    callback_url = CALLBACK_URL_YOU_SET_ON_GITHUB
    client_class = OAuth2Client

# Define the urls.py on the Django app
urlpatterns += [
    path('github/', GitHubLogin.as_view(), name='github_login')
    ]

How to Set Up a New Application

To specify the GitHub OAuth credentials, you'll need to log into the Django social application model. This will provide your Django project with an additional degree of protection. Because of this, changing the OAuth credentials will be simple and won't damage your existing code.

Start by logging into your Django admin, clicking Social Applications, and selecting Add Application. This will prompt you to create a new application.

On Django admin, select "Social applications"

You will be prompted to enter information on the new page.

• Select GitHub as the provider.
• Give your social app a name.
• Enter the Client Secret and Client ID created from your GitHub OAuth app.
• Select the site on Available sites and move it to Chosen sites. Once done, click Save. This will create a new application.

Create/Add a Social application

Change your site domain to localhost since this is still the development phase.

Select, "Site" to change the existing the site domain

Select example.com and change it to http://127.0.0.1:8000/ then Save.

Change your site domain from example.com to http://127.0.0.1:8000/

How to Test the Defined Social App

Once you are done defining and setting up the social Django app on your project, you will need to test it and make sure that it works.

If you open the route http://127.0.0.1:8000/auth/github/, you'll need to enter some information such as Access token, ID token, and code.

We'll manually get this information, as the front end is meant to get and parse this information.

Go to the GitHub registration page to test the defined social app

To do this, head over to https://github.com/settings/apps and select Personal access tokens then select Generate new token. Use the second option, Generate new token (classic), since this guide is focused on authenticating users just to get their GitHub user info.

On GitHub settings, select "Personal access tokens" then select "Generate new token".

Give the token a name and select scopes. Ensure you check all the user scopes. Then generate a new token.

Define your new token

Your new token should look like this. Ensure you store it somewhere safe.

Copy the generated personal access token generated by GitHub.

Head over to http://127.0.0.1:8000/auth/github/. Enter the access token generated and voilà! Your user access token and GitHub username will be sent as a response on the body.

Using your token and GitHub username ensure the backend system works

How to Implement OAuth Authentication Flow

You have successfully installed and tested the dj-rest-auth package. Next, you will learn how to test the OAuth flow and how it obtains user data from GitHub.

To test the GitHub OAuth authentication flow, you'll need to send a request to https://github.com/login/oauth/authorize.

You can do so by either using curl:

"https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://127.0.0.1:8000/auth/callback/&scope=user"

(and making sure you use the same redirect URI defined in your GitHub OAuth application) or opening https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://127.0.0.1:8000/auth/callback/&scope=user on your browser. It will redirect you to an authorization page.

Send a request to GitHub OAuth authentication flow

Click Authorize YOUR USERNAME to authorize the user.

Click "Authorize" to authorize your GitHub user

You will be redirected to a URL showing the code. With the code, you can generate the access token needed to authenticate the user.

Use the code from GitHub to generate an access token for your auth

To get the access token, send a request to this URL: https://github.com/login/oauth/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=CODE

Or you can choose to use curl to send the request.

"https://github.com/login/oauth/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=CODE"

This should either download the access token for you or return it as a response body depending on how you defined it. The response should look like this:

Your response from your backend authentication system

Now, with this token, you can authenticate your user when they make any request.

Conclusion

In conclusion, setting up GitHub OAuth on Django is a helpful way to enable users to log in to your web applications using their GitHub credentials.

By following this guide, you can enhance your application's security and access your users' data which improves the user experience of your Django app.

In this article, we will give you a quick rundown of how to set up a GitHub OAuth application.

Create Your Application

Begin by navigating to your GitHub settings (make sure you are logged in!). Scroll down to the bottom of the sidebar and click "Developer Settings".

This will take you to the application page:

You may see some applications you've previously authorised.

Click the "New OAuth App" button to create a new application.

Fill in the form and click "Register application". This will create your application and take you to the settings page.

For OAuth applications, you will need the Client ID. You will also need to generate a client secret. Click the "Generate a new client secret" to do so.

Make sure to save this secret in a secure location as you will not be able to view it again.

Using Your New Application

Now that you have a client ID and secret, you can use your OAuth application in your project.

If you want to learn how to do so, freeCodeCamp's curriculum can teach you.

Happy coding!

There is, of course, a more complex process involved in setting up social login, but for a user it's as simple as clicking a button to log in.

The ease of not having to remember an ID/password and just being able to signup/login through the click of a button is extremely beneficial to the user.

What if I Told You This Was Way More Secure? 😉

Social logins really help us achieve a few things:

• Support for multiple devices
• Single Sign On
• Simple to implement
• The ability to share data for users without having to release personal information
• Ability revoke an active session i.e not allow a third party access to the login and data
• There are no long-lasting credentials being exchanged

So What Technology Drives Social Login? 🤔

The underlying protocol used is something called OAuth. It is defined as:

An open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.

Now with a basic understanding of social login and the above definition you probably have some idea of how this works – but let me use a simple example to explain how to use OAuth.

I remember my friend Sumedh describing it as an interaction between a Mother, Father, and their Son. Imagine that the mother wants some groceries from the market and she wants the son to buy them for her.

Before I go into the conversation let me set some context.

Mother: The user of the application

Son: Third party client or in technical terms the OAuth Client

Father: The Social Account or in technical terms the OAuth Provider

The conversation could possibly go like this:

Mother: Hey son, go to the market and bring me some coffee powder. Take the required money from your father.

Son: Okay.

Son (OAuth client) goes to father (OAuth provider)

Son: Hey dad, mom told me to take money from you since she wants some things from the market.

Father (OAuth provider) asks mother (User) about the permission to give money to their son (OAuth client)

Father: Hey, shall I give him the money and how much?

Authorization of your application takes place here.

Mother: Yes, please give it to him.

Permission grant by mother (User)

Son (OAuth client) gets the required things from the market and returns them to mother (User). Here returning things to mother (User) can be thought of redirecting the user (or logging them) into the third party site.

For a more technical understanding of how this works in code, Richard Schneeman has this amazing video below:

Now Lets Put All of This in Context

Let's take as an example the DEV Community. If you wanted to create an account on the DEV Community using Twitter, what would happen?

Basically, if the "Sign up with Twitter" button exists, then the initial setup between the OAuth Client (Dev.to) and the OAuth Provider (Twitter) is already done.

The Client triggers a permission granting page for the OAuth Provider based on the credentials it receives from the initial setup. This looks something like below:

Once you login and grant permission, the OAuth Provider redirects you back to the client and the client gets a token to access your information from the OAuth Provider. This access token enables the client to get specific data from the provider

Based on that data the client then creates an account and logs you in

What Happens on Successive Login?

Thats a good question. Now OAuth has multiple grant types, and based on that we have different ways to get an access token from the OAuth Provider.

For all subsequent logins, the OAuth Client will hit the provider and generate a new access token to get access to the data and do the login.

Thus this enables us to achieve Single Sign On, the ability to share data for users without having to release personal information, the ability to revoke access, and the ability to not have long lasting credentials exchanged.

This all leads to a more secure experience.

Conclusion

I hope this short blog post helps you understand why social logins are more secure than the traditional username/password option. I will be writing about the different OAuth Grant types in the future and will be providing code examples as well.

Thanks for reading! I really hope that you find this article useful. I'm always interested to know your thoughts and happy to answer any questions you might have in your mind. If you think this post was useful, please share it to help promote this piece to others.

Thanks for reading! :)

P.S Do feel free to connect with me on LinkedIn or Twitter

This post is originally from www.jaredwolff.com

Privacy.

Performance.

Brilliant looks.

Can you have all three?

(Of course!)

Having a statically generated blog is great. Many folks use services like Disqus and Google Analytics to make them even better. Not surprising if you were one of them! Privacy concerns are are the forefront of everyone’s attention. So, rather than keeping the status quo, it’s time to do something about it!

If you've been looking to protect your site visitor's privacy and improve performance this blog post is for you.

In this article we'll be using DigitalOcean’s Docker droplet. It allows you to host several different applications/services on one (virtual) machine. By the end of it you'll know how to run your own comments server using Commento. Plus i’ll share a few tricks i’ve learned along the way to make it much easier for you.

Leeeets go!

Reverse Proxy

One of the most important aspects of this setup is the reverse proxy. A reverse proxy acts like a router. Requests come in for a certain domain. That request is then routed to the service associated with that domain.

Here’s a diagram from the Nginx Reverse Proxy + Let’s Encrypt Helper documentation. It'll help illustrate the idea.

Another benefit is that there’s an extra layer of protection to the outside world. Your websites run in a private network and the only access is through the Nginx reverse proxy. Point your DNS to the server and Nginx handles all the magic.

Here's how to get it setup:

1. Go ahead and set up your Digital Ocean Droplet. All the info you need is right here. The $5 version is more than sufficient.

2. Go here to clone the repository. You can also run this in your terminal. Make sure you SSH into your Digital Ocean droplet first!

   git clone git@github.com:evertramos/docker-compose-letsencrypt-nginx-proxy-companion.git

3. Change directories to the cloned repository.

4. Copy .env.sample to .env and update the values inside. I had to change the IP value to the IP of my Digital Ocean Droplet. I left all the other ones alone.
5. Run docker-compose up -d to start everything. (you can run without the -d option to make sure everything starts ok. Or you can attach the log output using docker container logs -f <container name

When pointing your sub-domains to this server, make sure you use an A record. Here's an example of mine:

Depending on your DNS provider, you'll have to figure out how to set an A record. That is beyond the purpose of this article though!

Setting Up Commento with Docker Compose

Here is the current docker compose file i'm using for Commento. It includes a few more environment variables for configuring Github, Gitlab and Google. It also includes the environment variables for setting the SMTP settings. These parameters are important. Otherwise you can't receive password reset or moderation emails!

version: '3'

services: commento: image: registry.gitlab.com/commento/commento container_name: commento restart: always environment: COMMENTO_ORIGIN: https://${COMMENTS_URL} COMMENTO_PORT: 8080 COMMENTO_POSTGRES: postgres://postgres:postgres@postgres:5432/commento?sslmode=disable COMMENTO_SMTP_HOST: ${SMTP_HOST} COMMENTO_SMTP_PORT: ${SMTP_PORT} COMMENTO_SMTP_USERNAME: ${SMTP_USERNAME} COMMENTO_SMTP_PASSWORD: ${SMTP_PASSWORD} COMMENTO_SMTP_FROM_ADDRESS: ${SMTP_FROM_ADDRESS} COMMENTO_GITHUB_KEY: ${COMMENTO_GITHUB_KEY} COMMENTO_GITHUB_SECRET: ${COMMENTO_GITHUB_SECRET} COMMENTO_GITLAB_KEY: ${COMMENTO_GITLAB_KEY} COMMENTO_GITLAB_SECRET: ${COMMENTO_GITLAB_SECRET} COMMENTO_GOOGLE_KEY: ${COMMENTO_GOOGLE_KEY} COMMENTO_GOOGLE_SECRET: ${COMMENTO_GOOGLE_SECRET} COMMENTO_TWITTER_KEY: ${COMMENTO_TWITTER_KEY} COMMENTO_TWITTER_SECRET: ${COMMENTO_TWITTER_SECRET} VIRTUAL_HOST: ${COMMENTS_URL} VIRTUAL_PORT: 8080 LETSENCRYPT_HOST: ${COMMENTS_URL} LETSENCRYPT_EMAIL: ${EMAIL} depends_on:

• postgres networks:
• db_network

• webproxy

  postgres: image: postgres container_name: postgres environment: POSTGRES_DB: commento POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres networks:

• db_network volumes:

• postgres_data_volume:/var/lib/postgresql/data

  networks: db_network: webproxy: external: true

  volumes: postgres_data_volume:

To set the environment variables, put them inside an .env file. Make sure the .env file is in the same directory as docker-compose.yml. When you run docker-compose up it will apply the variables set in the .env file. Nothing gets set if they're left blank.

Set the required COMMENTS_URL and EMAIL or you may run into problems. The best way to set these is by pacing them in the .env file. Here is an example:

COMMENTS_URL=comments.your.url EMAIL=you@your.url

Getting OAuth Key & Secret

Commento works with most popular OAuth providers. Thus visitors can leave comments without making an account.

The instructions are similar for each. I've outlined the steps for all of them below.

Twitter

1. Login to Twitter.com and apply for a developer account: https://developer.twitter.com/en/application/use-case

   

2. Describe how you'll use the API. You can use what I wrote.

   

3. Double check your entry and click Looks Good!

   

4. Agree to the terms of service.

   

   

5. They'll tell you to check your email for a confirmation. Confirm your email and you should be able to create your first app!

6. Once approved to to Get started click Create an app.

   

7. Next screen, again click Create an app

   

8. Enter all the appropriate details. For the callback URL, use https://<your URL>/api/oauth/github/callback where <your URL> is your Commento subdomain.

   

9. Finally, once you're done filling out the information to go the Keys and Tokens area. Save both the key and token. Enter them into the .env file. You can use COMMENTO_TWITTER_KEY and COMMENTO_TWITTER_SECRET

   

Gitlab

1. Login to Gitlab.com and go to to top right and click Settings

2. Then click on Applications

   

3. Enter a name for your app. I put Commento.

4. Set the Redirect URI to https://<your URL>/api/oauth/gitlab/callback

5. Select the read_user scope.

   

6. Click the green Save Application button

7. Copy the Application ID and Secret and place them in your .env file using COMMENTO_GITLAB_KEY and COMMENTO_GITLAB_SECRET

   

Github

1. To get your OAuth key and secret, you'll need to go to this URL: https://github.com/settings/developers

2. Once there, click on New OAuth App

   

3. Enter your details. For the callback URL, use https://<your URL>/api/oauth/github/callback where <your URL> is your Commento subdomain.

   

   Note: Make sure you include https in your URLs.

4. Grab the Client ID and Client secret and put that into your .env file using COMMENTO_GITHUB_KEY and COMMENTO_GITHUB_SECRET

   

Google

Setting up Google is just about as tedious to set up as Twitter. Despite how scary I just made it out to be, it's completely doable. Here are the steps.

1. Go to this URL: Google Developer Console

2. Create a new project

   

3. Click the GoogleAPIs logo in the top left corner to go back once you have a project. (Make sure the dropdown next to the GoogleAPIs logo is the same as your new project!)

4. Then, click Credentials on the left side.

5. Update the Application Name and Authorized Domains in the OAuth consent screen

   

6. Click Create credentials then OAuth client ID

   

7. On the Create OAuth client ID enter the subdomain associated with Commento to Authorized Javascript origins. Then, enter the full callback URL. For example https://comments.jaredwolff.com/api/oauth/google/callback. Make it yours by replacing comments.jaredwolff.com with your URL.

   

   Once entered, click the create button.

8. Grab the client ID and client secret

   

9. Update your .env file using COMMENTO_GOOGLE_KEY and COMMENTO_GOOGLE_SECRET

Install your application

You've entered your OAuth Credentials email, domain and SMTP credentials. It's time to wrap this show up!

1. Once you're done editing your .env file. Run docker-compose up (For files not named docker-compose.yml, use the -f flag. Example: docker-compose -f commento.yml up
2. Watch the output for errors. If it looks good you may want to kill it (CTRL+C) and run with the -d flag

3. On first start, Commento will prompt you with a login screen.

   

4. Create a new account by clicking Don't have an account yet? Sign up.

5. Enter your information and click Sign Up

6. Check your email and click the included link:

   

7. Log in with your freshly made account.

8. Then, click Add a New Domain.

   

9. Once created go to Installation Guide. Copy the snippet and place it where ever you want your comments to live. In my case, I put the snippet in an area just after my <article> tag.

   

10. Re-compile your site and check for success!

    

    Checkmark! Finally, I recommend you try logging in with each individual OAuth configuration. That way you know it working for your website visitors. ?

Alternatives

I spent a good chunk playing around with some of the alternatives. This is by no means a definitive guide on what will work best for your site. Here are some of the top ones as of this writing:

https://utteranc.es/#configuration

https://github.com/netlify/gotell

https://github.com/eduardoboucas/staticman

https://posativ.org/isso/

https://www.remarkbox.com

https://www.vis4.net/blog/2017/10/hello-schnack/

https://github.com/gka/schnack

There's also a huge thread over at the Hugo blog which has a ton more links and resources as well:

https://discourse.gohugo.io/t/alternative-to-disqus-needed-more-than-ever/5516

Conclusion

Congrats! You are now hosting your own comments server! ?

In this article you've learned how to harness the power of Docker and a Nginx Reverse Proxy. As an added bonus, you know how to set up OAuth credentials! That way future setup will be easy peasy.

By the way, this is only the tip of the iceberg. You can set up the same server for analytics, data collection and more. All the example code including code for other applications can be found here.

Finally, if you're looking pay for Commento head to www.commento.io and sign up for the service. You'll be supporting awesome open source software!

If you have comments and questions let's hear em'. Start the conversation down below. ???

Most of the times I try to learn something new and put it into practice, I quickly start to feel like I’m lost in a myriad of dance moves. I’m desperately trying to find the right way to do things, while not really understanding what’s going on or how I ended up on the wrong side of the room…

Just trying things out until something works.

Maybe it’s because of the way my learning process works, or maybe guides and tutorials are targeted at more experienced or technical people. But, after I’m done wrapping my head around the subject, I always feel like there should be an easy guide for understanding the key concepts and making it easier to apply them in a project.

So this time, I’ve decided to stop wishing for it and make it myself, using the last thing that I learned.

And that thing was OAuth 2.0.

What is OAuth?

Let’s start with the basics: OAuth stands for Open Authorization. It’s a process through which an application or website can access private user data from another website.

This other website usually works only as a trusted identity provider. It gives the requesting app some basic information about you so that the app can create a profile. This way, you don’t have to fill in a boring sign-up form and deal with yet another password ?

You’ve already used this at least a gazillion times, in fact you used it every time you clicked on “Log in with Facebook / Google / GitHub / …”. Next, you were shown a consent screen that displayed which information from your (let’s say) Facebook profile you’re allowing that-hot-new-app.com to read (and sometimes, write). After that, since that-hot-new-app.com trusts the identity provided by Facebook, they can create a profile for you on their database using the data that they received.

The communication between that-hot-new-app.com and Facebook usually ends here. This is why your profile picture won’t change all across the Internet if you change it on Facebook. They just never go back to Facebook and ask for updated data.

When marimba rhythms start to play…

There’s another purpose for building this kind of mechanism, one with way more potential: using the identity provider as a service provider (in an ongoing manner). This means communicating with it regularly to supply enhanced features for your users.

A nice example of this is Relive, a service that connects with different sports tracking apps to create Earth view videos of your run or ride. Every time you finish an activity, Relive prompts you offering to create a video from it. If you say yes, they’ll process it, and notify you when it’s ready for social media bragging… I mean sharing ?

There’s really no technical difference between these two usages. That’s why you should be cautious about where you log in with your social media or Google/Gmail account.

It might sound scary, but there's really nothing to fear. Just bear in mind that you’re authorizing that-hot-new-app.com to access that information about you that’s detailed in the consent screen, potentially on a recurrent basis. Be aware of the permissions you grant, and make sure you know how to disable them whenever you don’t feel trusting anymore.

For instance, if you are using your Google account for accessing that-hot-new-app.com but don’t want to allow that anymore, just go to your Google account settings and disable their access.

All the main identity providers offer control over this.

All right, but how do you dance the OAuth?

Before you land on that-hot-new-app.com and even click on “Log in with YourFavoriteIdentityProvider”, someone — probably a developer — has to create an application on the provider’s site.

This is a way of registering that-hot-new-app.com so that, later, the provider knows who’s asking for private data.

In this step, the developer will set up some information about the application, like the app's name or website and — most importantly — a redirect URI. The provider (like Google or Facebook) will use this to contact the requesting app and tell them that the user said yes ?

I promise you won't have to write it by hand, we pride ourselves on our paperlessness.

Once the app is registered, the provider will give that-hot-new-app.com a clientId and a clientSecret which will be used in the communications between them. They work sort of like a username and password for the application.

You'll get the clientID and clientSecret right after you click on Save application

It's very important that you keep your clientSecret in a secure location and don't share it with strangers. If someone gets access to it, they could request private user data from the provider on your behalf, and then use it for evil!

We don't want that.

Hands on waists or shoulders

Apart from setting up all those things, the developer has to find out what kind of data the provider gives access to, and how it’s segmented.

These “segments” are known as scopes and they define access rights, usually separated in read/write categories. So, for example, that-hot-new-app.com can request for “profile:read” and “contacts:read” scopes. This means they can read whatever the provider assigns to the “profile” and “contacts” segments. Other things won’t be accessible, for example your posts or what content you like.

Well, just to make things simple for now on, let’s say that that-hot-new-app.com is a website that integrates with Typeform, a service for creating beautiful and smart forms and also the company I work for. You definitely want in on the hottest thing right now, and quick, so on their website you click on “Log in with Typeform” to get right into the action. What’s next?

Here’s a home-made, organic, and cholesterol-free diagram to use as a map for the whole thing. It may look a bit complicated but don’t worry, we’ll examine each step up next.

Colorful notes bring joy to my heart

Authorize: the first step in the OAuth dance

So, you take the initiative and click on “Connect with Typeform”. Here, that-hot-new-app.com (THNA from now on, ’cause I’m getting tired of writing dash-separated words) will send you to Typeform’s authorize endpoint (/oauth/authorize) and provide:

• their clientId (remember, that’s THNA’s username)
• their desired scopes (or access rights)
• and their redirect URI again (Typeform already knows it from when we set up the whole thing, but we send it again as an extra layer of security)

That URL will look something like this:

https://api.typeform.com/oauth/authorize?client_id=yourClientId&scope=accounts:read+forms:read+results:read

Typeform will use this information to generate a consent screen where you can review what sort of things you’re authorizing THNA to see and do.

Once you have thoroughly read what you’re consenting to and happily click on “Allow”, Typeform will send you to the redirect URI with a temporary, like so:

https://that-hot-new-app.com/auth/redirect?code=xxxXXXxxxXXXxxx

Token: it takes 2 to tangOAuth ?

All this back and forth feels like someone’s taking you for a tango spin, right?

The second step of the OAuth dance is when THNA receives that code, and exchanges it for an OAuth Token.

So THNA takes that code and sends it back again to Typeform, along with the redirect URI (yes, again!), and the client secret (that’s the app’s password!).

As reward for a dance well danced, THNA will get a shiny OAuth Token ✨ which it can use to interact with Typeform on behalf of the user, that is… you!

Stay with me, sway with me

From now on, in every request THNA makes to Typeform on your behalf, they’ll have to include an Authorization header with that access token. With it, Typeform (or any other provider) can identify:

• who’s asking for the data (in this case, THNA)
• who’s the data about (you!)
• and also make sure they have the correct authorization to access that data (only what you consented to).

Ready for the dance floor ?

So now that you know all the steps and spins of the OAuth dancing technique you should be ready to create your own choreographies, I mean, integrations, and make the Internet an even greater place.

Drawings by yours truly, cover photo by Gez Xavier Mansfield on Unsplash.