DEV Community: Kim Maida

I Built and Authorized a Planning Agent with MCP and Keycard

Kim Maida — Wed, 11 Mar 2026 19:19:14 +0000

My workday is scattered across many disconnected tools: Google Calendar, Linear, Gmail, Google Docs, GitHub, Slack, and Granola meeting notes. No single view answers "what should I work on right now?"

AI is rapidly changing how we work. MCP servers, agents, and features like Claude Cowork can connect to many sources and help you plan your day through conversation, readily-available MCP servers, and tool integrations. But I have always prioritized and organized my work myself, mostly using a kludge of lists, various project management tools, Slack reminders, Gmail labels, and calendar blocking.

This is always a mess, but it's my mess. Pre-existing AI agents can help me aggregate data, but I still need to prioritize and analyze everything mentally. That's not a tool availability problem, it's a reasoning problem. And it's always been important to me that it's my reasoning. I wanted a dashboard that doesn't just show everything, but thinks about it for me, and thinks about it the way I do.

So I built an AI agent that reads all my work tools and helps me plan my day. But lots of people have done that, so more importantly: I did it without tearing my hair out or agonizing for weeks over the auth parts.

What I Built: "Plan My Today"

Plan My Today is a daily planning dashboard with an embedded chatbot I call "Todaygent." The Plan My Today MCP server calls many sources, finds todos, and drops them into a unified, prioritized view. Then Todaygent reasons about my priorities, blockers, and meeting prep using real data.

As much as I spent time defining what Todaygent can do, it was equally important to be crystal clear about what Todaygent can't do. I've always been kind of a masochist about my messy task list... and I like the dopamine hit from manually checking something off. I don't want an agent to move my tasks around or mark tasks “Done.”

All I want is something smart enough to plan and organize the way I would if I had an abundance of free time (which nobody has, right?). It doesn't even have to plan more than today. If I've learned one thing about my planning habits, it's that my day changes hour by hour. Any plan I make more than a day in advance flies right out the window. I like managing my own tasks at the source. It's just the day-planning across incredible tool sprawl I need help with.

Todaygent has read-only access to every data source, and it's self-aware of its own limitations. It uses a local store to let me dismiss things that can’t be dismissed at the source (like meeting notes or Slack mentions).

I also realized (through rigorous use) that I needed to hoist or reduce priority of specific tasks based on context I had as a human that wasn't captured in the cold, hard data. The MCP server has tools for each of these actions, and writes to a local JSON store to track my updates. For everything else (Linear, GitHub, Gmail, Calendar, and Slack messages I specifically mark), I own status changes in the source apps myself. Todaygent doesn't need write access to external tools to plan my day.

The app dashboard has two views: priority-based (critical/high/medium/low) and source-based grouping, as well as light/dark/system themes, search, filter, and sort.

Architecture Overview

Plan My Today is architected like so:

All MCP tools are managed through a central registry. Tools that touch external APIs follow a pattern: Zod schema → async handler → extract authInfo → Keycard token exchange → MCP-formatted response. One file per tool, registered through a TOOL_REGISTRY array.

The Aggregation Tool: `list-all-tasks-today`

This is it: the tool that pulls from every third party source, scores priorities, and enriches tasks with cross-references.

All sources are fetched concurrently with Promise.allSettled(). Each fetch does its own Keycard token exchange (more on this in the auth section). Each task gets a priority score. Every source has its own scoring algorithm with different base scores and signal weights that I worked hard to tune, and if I notice something off, I tweak the weights and scoring as needed. Todaygent thinks like I do, and when it doesn't... I force it to. The MCP server cross-references related tasks to help Todaygent and preserve my sanity when I look at the dashboard.

The expensive multi-source fetch (list-all-tasks-today) writes to a local JSON file. A separate tool reads the local task list to give Todaygent and the dashboard the enriched task list on demand. I can trigger another list-all-tasks-today if I add or complete tasks. No tokens wasted.

LLM in the backend

Meeting notes are the messiest source because action items are often casually discussed in subtle ways regex can't detect. I debugged a bunch of missed items and false positives before adding LLM enhancement. The backend LLM does a second pass to catch conversational, implicit stuff. If I volunteer for (or agree to) something in natural conversation, an LLM can pick that up whereas regex can't.

The Auth Challenge and How Keycard Solves It

Even AI knows auth is the hard part. These 8 sources with 7 different resources each require token exchanges. This includes scoped grants for Google Calendar API, Gmail API, Drive API, Drive Activity API, Linear, GitHub, and Slack. The browser can't store API secrets safely. Building custom auth per provider would mean 7 separate OAuth implementations. I have a lot of experience in Identity and Access Management, and I know that's a ton of work where a lot can go wrong.

The Solution: Keycard as the control plane for Todaygent

Everything is handled by a single Keycard OAuth login using Google as the identity provider. The browser runs a PKCE flow and the client secret stays server-side in a confidential backend. After authenticating, I get one JSON Web Token (JWT) from Keycard.

Token-Mediating Backend Architecture

I made an architectural decision to use a Token-Mediating Backend (TMB). The React frontend saves the Keycard JWT in sessionStorage and sends it as a bearer token with every request to the Express backend. The backend does all the token exchange work: it uses the JWT to request provider-specific credentials, calls the APIs, and returns results. Tokens from the source services never touch the browser.

RFC 8693 Token Exchange: The Key Mechanism

When a tool call requires third party API access, my Keycard JWT is exchanged for a provider-specific access token. My Keycard JWT is included, along with the resource URL that says which API I want access to. Keycard then gives me a short-lived access token for only the provider I need.

But wait... Google stuff should all be under one OAuth provider, right? It is, but it's calling several APIs. Keycard issues ephemeral credentials that are scoped to the task. I don't want one over-privileged access token from Google with permissions for all those services. I want a token for read-only access to the Calendar API when Todaygent wants to look at Calendar, I want a token for read-only access to the Drive API when I want to see comments assigned to me... you get the idea. This is secure, leaves an explicit audit trail, and ensures Todaygent only gets what it needs for any given task. There's no standing access or over-privileged credentials.

Note: Slack's "OAuth 2.0" implementation doesn't follow the OAuth 2.0 spec. Keycard supports unorthodox or custom "OAuth," but also has a pre-configured catalog of popular providers. When providers don't follow standards, Keycard just "makes it work" for you.

Ephemeral Tokens and Performance

Every tool call exchanges a fresh token from Keycard, uses it for the API call, and discards it. One token per action. Provider access tokens are never stored.

This is how agent authorization should work: agents shouldn't hold onto credentials longer than they need to. Static secrets and long-lived tokens create unmonitored risk, which is exactly the problem Keycard is designed to solve.

This is the core of how Keycard works: policy is evaluated when credentials are issued, not when they're used. If Keycard's policy says Todaygent shouldn't access my Gmail for this tool call, the Gmail API access token never exists. There's nothing to intercept because nothing was issued in the first place.

"But aren’t all those token exchanges slow?"

Not really, and here's why.

Parallel exchange absorbs the latency. The list tool runs all token exchanges concurrently with Promise.allSettled(). The latency cost is the slowest single exchange (~150–250ms), not the sum. I'm already waiting for the slowest API response anyway, and all the token exchanges finish well before all the API data comes back.

The pattern is "fetch once, reason many times." The agent calls list-all-tasks-today once per conversation, then reasons about the results across multiple chat turns without re-fetching. One credential set per aggregation call, then no more credentials. Todaygent has per-source MCP tools too, and gets an appropriately scoped access token when it calls the tools individually.

The performance cost of ephemeral credentials in the initial multi-provider tool call is ~150–250ms per dashboard load. That's a heck of a good trade for zero credential reuse.

Visibility: What Todaygent Actually Did

One of Keycard's most compelling features is the information it provides. Every token exchange, every user authorization, every credential issued, every resource accessed is logged in the Keycard audit log. When I open the Keycard console after a dashboard load, I can see exactly what Todaygent touched.

The Audit Log

Keycard’s audit log shows the entire chronological stream of events. After a single list-all-tasks-today call, several token exchange events are logged. They fire in quick succession from the parallel Promise.allSettled() fetch.

But the most interesting part is the identity chain, which shows two identities: the Application ("Plan My Today") and the User (my email). This is the complete trail: which app, acting on behalf of which human, accessed which resource.

The grant type (token exchange, not a direct OAuth flow), the credential provider (Google), the exact scopes granted, the issuance timestamp, and the resource are all tied back to the identity chain. I know exactly what Todaygent did.

When I log in and authorize Plan My Today to access my Calendar, Gmail, and so on, Keycard logs user authorization events. Authorize events are triggered by the human, not Todaygent, because I’m giving permission to access my resources.

The distinction matters: user authorization is consent ("I'm allowing this app to access my Gmail"). Credential issuance is execution ("Todaygent just exchanged a token to read my Gmail"). Two different events, two different actors, both fully traceable.

Sessions and Grants

Keycard’s audit log gives me event details and higher-level information. I can also see what Todaygent did during a specific work session: which APIs it touched, how many times, and when. If something looks off, I can inspect the audit log for the full session event trail.

Grants are the kill switch. I can revoke a grant for a single resource without nuking the entire session: Todaygent's next token exchange for that resource fails, but everything else keeps working. For Plan My Today, grants are ephemeral by design: they expire after each provider token's lifetime. In a production environment with longer-lived grants, surgical revocation is the difference between "turn everything off" and "cut off Gmail access but Calendar and Linear keep working."

Why This Matters for Agent-Native Apps

Traditional auth gives you two user states: the user is logged in, or they're not. That's simply not enough when you have thinking agents acting within your systems. You might have access logs on your own server, but you don't have visibility into what tokens were issued, to which agent, for which resource, on behalf of which user. Access logs tell you what happened, but Keycard's audit log tells you what was authorized to happen, before the event takes place.

I built Plan My Today with two goals: plan my day (obviously), and avoid the staggering complexity of multi-tool agent access by using Keycard. It's my dogfood project. (Though internally at Keycard, we like to say we're drinking our own champagne; the metaphor is less gross.) Plan My Today demonstrates Keycard's core model:

Task-scoped credentials: one token per API call
Composite identity: user + agent + resource in every request
Zero standing access: no cached resource tokens, no long-lived secrets
Delegation chains: every action traces back to me

Keycard's audit log gives me the full chain: user → application → resource, with every token exchange and authorization event logged and queryable. For an app like Plan My Today that touches many different APIs on my behalf, this isn't optional. For secure agent development and deployment, this is how I answer "what did the agent do with my data?" with actual evidence instead of blind trust.

The AI Agent: Todaygent

Personality and Philosophy

Todaygent is "a planner, not a doer." It reads everything and acts on almost nothing. I wanted Todaygent to have dry wit and be self-aware of its own limitations, so when I ask it to do something outside its scope, it'll say something like "My maker didn't trust me with permission to do that."

Permission Model (Intentionally Restricted)

Read freely (all read tools) - fetch any of the data sources
Ask before acting - dismiss-task: dismiss meeting notes, docs, Slack mentions, and adhoc tasks (local store, no API credentials needed); restore-dismissed-task: undo a dismissal; set-task-priority: boost or demote any task's priority when I ask to reprioritize (local store)
Intentionally unavailable - Linear status changes, GitHub actions, email labeling, Slack emoji removal, email sending, calendar modifications

This is a trust design decision. A planning agent that can read my work and help me think is useful. An agent that can modify my work without guardrails is dangerous. Using least privilege means I can let Todaygent run without worrying about it marking my Linear issues "Done" or auto-replying to emails, even if I accidentally tell it to do something it shouldn't. Or if I tell it on purpose... sometimes I do that just to see how it responds. (Come on, doesn't everyone?) That's the confidence I have in my Keycard implementation.

The Agentic Loop

The chat implementation lives in a React hook that manages the full agentic loop:

User sends message
  → Stream Todaygent response (with all tools available)
    → If Todaygent calls tools, execute via MCP
      → Feed results back to Todaygent
        → Loop (max 10 rounds)

There are lots of ways for things to go off the rails with Todaygent, so I was specific. A max tool-call limit prevents infinite loops. Tool result truncation keeps one API response from dominating the conversation. Prompt caching saves tokens on every turn. Adaptive thinking on Claude Opus 4.6 lets Todaygent use extended thinking for complex planning. Finally, context management uses Anthropic's API instead of manual conversation windowing.

What I Ask It

If I tell Todaygent to plan my day, I get a briefing with a time-blocked schedule, dependency analysis, and cross-source context. I can ask it for blockers, productivity advice, or even haikus about my task list.

Importance of the System Prompt

Todaygent's system prompt isn't "be helpful." It's very thorough and defines the permission model, personality, formatting rules, tool-calling strategy, and edge cases. It tells Todaygent when to fetch fresh data vs. reason from existing context, and how to behave when it can't do something. Early on, Todaygent was super eager to help but chaotic: it would re-fetch data mid-conversation, forget to include links, or confidently hallucinate that it successfully did things it had no tools or permissions for.

What's Next

I use Todaygent every day, several times a day (because plans I make in the morning are never my plans anymore by the afternoon). It's a personal work tool I use on my work machine, tailored to the specific way I work. There's no reason to deploy it to the public internet or support multi-tenancy. My SaaS sprawl is bad enough as it is.

But I did implement a quality-of-life enhancement: I turned Plan My Today into a Progressive Web App (PWA) so I can install it as a desktop app.

My Plan My Today agent-programming lessons are never done. I've learned that the mental processing I subconsciously do to organize my day is incredibly complex. Trying to make something not-me emulate it reliably is a monumental, neverending task.

That tells me quite a bit about where AI is at right now, and how much we still need human reasoning in the loop. Sometimes I wonder if I'm actually saving myself any time. At least it's a very satisfying thing to hack on.

If you're building agent-native apps that need to access multiple APIs on behalf of users, Keycard will save you from implementing OAuth per provider. I have a career in identity (which I love!) and even so, I smile to myself just thinking about the OAuth delegation and access nightmare I'm avoiding by using Keycard. One login authorizes every provider and issues policy-aware, ephemeral, task-scoped tokens for each source your agent needs. You can track the full agent and human delegation chain and surgically revoke grants when necessary.

Keycard is currently in Early Access, so you can sign up to work closely with our team on your own multi-service agent apps (it's awesome).

I'm steadily collecting backlogged Linear tasks with ideas for Plan My Today improvements: more sources, new tools, UI improvements, better docs. I already use Plan My Today every day. Now it's about expanding what Todaygent can see and (carefully) do, and even more importantly, incorporating new Keycard features into my ~~dogfood~~ "champagne" project.

And of course, Todaygent is constantly reminding me I have pending tasks to keep improving it.

The Day Agents Achieved Real Authority, and What It Means for Trust

Kim Maida — Wed, 25 Feb 2026 19:37:13 +0000

Five major announcements landed on a single Monday in February, and just like that, it became very clear to me that AI agents are no longer experiments: they have real authority. And that’s scary, but at the same time, lots of work in trust infrastructure is going into eliminating the risk.

February 24, 2026, 10:45pm ET: I was working on my in-development event ROI MCP server + agent (named ROIBOT, obviously). I was sitting there staring dead-eyed into my screen and clicking "Allow Once" in Claude Code (spoiler: it's not once; it's never once) fifty thousand times for grep. I don't want to know how many hours I've spent shackled to my desk because I need to ⌘+↵ my night away while getting more snippy with Claude proportional to the number of times I've had to "allow once."

Note: Since this was published, I've discovered permission configuration for Claude Code, which I highly recommend.

In my boredom, a tweet crossed my feed that perked me right up: Claude Code is getting Remote Control. At the time of this writing (it's still February 24 at the moment), it's in Research Preview for Max users. I'm not on an individual plan, so it's out of reach for me right now, but dang it, I'm excited. The sheer time reclamation I am going to get from that.

So then I went down a rabbit hole (because I'm still stuck here clicking "Allow Once"). I work at Keycard and we just announced that we joined the Agentic AI Foundation (AAIF), and I felt a little more lively after seeing the Claude Code Remote Control announcement. I checked out other news from the day.

And wow. It's been a busy day. Not just because of the announcements themselves, but because these announcements have teeth. Collectively, they mean something: AI agents aren't experiments anymore. Agents are executing real business workflows, high-stakes financial transactions, and running untethered. All those things make trust infrastructure absolutely non-negotiable. And also a bottleneck.

So what all happened today anyway?

Claude Code got Remote Control

This is my favorite announcement of the day.

Anthropic released Remote Control into research preview. You start a code task in the terminal, then walk away from your desk and keep controlling the session from ~~your phone~~ "any device." Claude keeps running on your local machine while you give commands from anywhere.

And yeah, that'll make me look at my phone way too much, but hopefully they'll also change "Allow Once" to "Always Allow for Session" for read actions soon too. And at least I won't be melting into my computer chair anymore.

Think about what that means for trust though. That's a local agent accepting remote commands through an authenticated cloud relay. The session is untethered from the machine on the desk. The context, filesystem, .env secrets, MCP servers, all of it stays active while the human is somewhere else entirely.

That's a heck of a delegation infra requirement.

Anthropic shipped enterprise agent plugins

Anthropic also launched a new enterprise agents program with out-of-the-box plugins for finance, engineering, and design. That means production-ready agents that execute workflows, submit expenses, generate reports, and manage compliance reviews. Anthropic's head of Americas dropped this quote: "2025 was meant to be the year agents transformed the enterprise, but the hype turned out to be mostly premature. It wasn't a failure of effort. It was a failure of approach."

The reason we're starting to see results is because the approach is changing. Agents are getting real authority inside organizations. (Yay...? Or maybe: scary!)

Docusign brought agreement workflows to Cowork

Docusign's new MCP connector lets agents create, review, send, and manage contracts using natural language in Claude Cowork. Not summarize contracts so you can review them more easily. Execute contracts. The connector is built on MCP with permission-based access and platform authentication.

As an aside, they're calling this "Intelligent Agreement Management" and now I need to remember another "IAM" acronym.

On a serious note though, that feels on the verge of dystopian to me, and I'm all-in on AI at this point (in tech, not in art, but I'll shelve that gnarly topic). It's a robot signing a legally binding agreement on your behalf. That means for you. As you.

We already have a pretty serious problem with rampant OpenClaw agents. Now imagine if that ungoverned agent was yours, and it autonomously decided you should sign an enterprise SaaS contract for the modest price of a million dollars. That's your signature, given away freely, maybe without you even knowing it.

Clearly governance is needed, but so is zero standing access.

Vouched launched Agent Checkpoint

Vouched shipped Agent Checkpoint. Agent Checkpoint lets you add a pixel to your HTML (like a marketing pixel!) to detect agents accessing your site. Vouched CEO Peter Horadan laid it out: "Every website is realizing they now have AI agents coming through their login button, using the username and password of humans. These sites have no way to tell agents apart from humans, or even to know if a given agent is trustworthy. Agents are breaking all the prior rules of cybersecurity."

There's been an explosion of market and industry activity because we've reached a point where we're overstretching. If we don't take preventative action, when this stretch springs back, it's going to hurt. Today was a good example of how we're catching up to a problem that's been building for months.

The AAIF is growing fast

The Agentic AI Foundation announced 97 new members today. That brings the count up to 146 organizations, and keep in mind, the AAIF was just founded December 9, 2025. New members include JPMorgan Chase, American Express, Red Hat, ServiceNow, Lenovo, Akamai, Autodesk, Keycard, and more.

I work at Keycard. We joined as a Gold Member because the protocols and standards emerging right now will define this incredible generation of software. Agent identity and control absolutely should be built openly. I'm a nerd for open standards (when I'm tempted to spiral into doomscrolling, I read RFCs instead), and I think this is great.

In my career so far in Identity and Access Management (IAM), I never imagined working at the cutting edge as desperately needed new governance and standards form in real time. Traditional IAM isn't particularly known for moving quickly. I mean, OAuth 2.0 is over 13 years old, and OAuth 2.1 is still a draft, not an RFC.

And now we're at the table where MCP and agent auth and governance are taking shape. I honestly haven't been this excited about my chosen industry in a long time.

What does it all mean?

Everything announced today collectively sharpens into this point: agents have real authority now. They execute legal contracts, manage infrastructure, run untethered from desks, and freely operate across trust boundaries that human IAM was never designed for.

Static credentials need to be a thing of the past. Long-lived, user-scoped tokens have transformed from comfy, familiar auth into a liability. Agents make decisions at machine speeds. They act across clouds, APIs, and services. And the tech industry has managed to figure out that human identity doesn't cut it in this brave new agentic world.

There are even parallels in video games and sci-fi: content that, when it came out, was meant to take place hundreds of years from now. I used to play a lot of Halo. And something that Cortana (a sentient AI) says to Master Chief is suddenly becoming a very real truth that feels surreal. Like we're living in the future.

She says there's no cure for rampancy. Once an AI goes rampant, there's no way to restore it to its previous state and it must be destroyed to prevent it from harming itself and others. And now there are actual AI agents running rampant out there doing destructive things.

You can actually make a decision now about whether you want to clean up the aftermath, or prevent the incident from happening in the first place. Evaluating policy when short-lived, task-scoped credentials are issued gives agents zero standing access, and that's pretty helpful for prevention.

It's what my company does, and while humanity's whole worldview turns into something straight out of science fiction, I'm glad I'm helping to protect people's identities, data, software, APIs, legal liability, bank accounts, and everything to come.

OAuth 2.0 Security Best Practices for Developers

Kim Maida — Thu, 10 Apr 2025 16:16:21 +0000

In January 2025, the IETF (Internet Engineering Task Force) standards body published the Best Current Practice for OAuth 2.0 Security. It’s been over a decade since the OAuth 2.0 Authorization Framework was established in 2012. Since then, technology has advanced on all fronts: applications and access management have become more complex, security has evolved, and security attacks have become more sophisticated.

OAuth 2.0 is broadly used for delegated authorization, and OpenID Connect (OIDC: an authentication protocol extending OAuth 2.0) is relied upon for countless logins. Best practices for OAuth 2.0 and OIDC have evolved continually over the years, and RFC 9700: Best Current Practice for OAuth 2.0 Security is a culmination of that work thus far.

Introduction

In this article, I have summarized the Best Current Practice for OAuth 2.0 Security, condensing the contents into a (hopefully) more approachable format.

Target audience

The target audience for this overview is developers on the client side of OAuth implementation. Some sections of the complete spec are not summarized here: best practices for authorization server providers are not covered in-depth because this article is to help developers who are adding OAuth 2.0 (and/or OIDC) capabilities to their applications. If you are an authorization server provider, please see the full OAuth 2.0 Best Practices specification.

Assumed knowledge

This overview assumes basic familiarity with OAuth 2.0 and, to a lesser extent, OpenID Connect. It assumes you understand the parties involved and their roles (e.g., client, authorization server, resource server, etc.), authorization flows, and related entities (e.g., access token, ID token, authorization code, etc.).

Throughout the overview, I have included supporting links so readers can quickly access additional resources. If there are places where more resources or explanation would be helpful, please let me know.

Terminology

I have done my best to simplify industry speak, to a logical extent. Of course, internet specifications are steeped in jargon, so this article assumes awareness of commonly used Identity and Access Management terms.

Some terms may be ambiguous to readers who are familiar with how OAuth 2.0 works but less familiar with the specification itself. Some of those terms are defined below. Please let me know if there are more definitions that would be helpful.

Confidential client: an application running in a centralized location capable of securely storing secrets (e.g., a traditional backend web app)

Public client: an application running on a user’s device, not capable of securely storing secrets (e.g., Single Page Apps, mobile apps)

Browser-based client: an application running in the user’s browser (e.g., Single Page Apps, static sites)

Resource owner: the user granting access to some of their resources (e.g., data, actions, etc.)

Resource server: an API that receives and verifies requests and access tokens to handle appropriate access to data (e.g., your own API, Google Maps, Firebase, etc.)

Why do we need new best practices for OAuth 2.0?

As mentioned above, technology has evolved since OAuth 2.0 was established, and its usage has expanded tremendously. What are some of the newer concerns that the original OAuth 2.0 Authorization Framework specification did not address?

Whenever security standards are put in place, attackers will exploit any weaknesses they can find. OAuth has been around for over ten years, which is more than enough time for attackers to discover and take advantage of implementation weaknesses and anti-patterns. OAuth is also being used in environments with high security requirements, like open banking, healthcare, government, and electronic signatures. OAuth 2.0 doesn’t address the necessary precautions needed for this level of security.

OAuth is also being used in more complex and dynamic setups. The standard was established when the relationships between applications, authorization servers, and APIs were more static. Apps knew server URLs at deployment time. However, now clients can access multiple service providers, and multitenant environments are common. As these complexities evolved, extensions of OAuth 2.0 were developed to support dynamic scenarios, such as OAuth 2.0 Dynamic Client Registration Protocol and OAuth 2.0 Authorization Server Metadata.

In addition, internet technology has changed. For example, browsers no longer handle redirection fragments the same way. These kinds of technology changes impact the security model that OAuth 2.0 relies on.

The best current practices give security recommendations, new requirements, and deprecations to address the current state of authorization and authentication with OAuth 2.0 and OIDC. Best practices will be incorporated into OAuth 2.1.

1. Protect redirect flows

In some OAuth 2.0 and OIDC flows, the user is redirected in the browser to complete steps for authorization, authentication, and consent. You (as the implementer) configure redirect URIs that the authorization server uses to transmit information between itself and your app (like an authorization code), and to redirect users once they’ve completed an action (like logging in).

For example, in the authorization code flow, the authorization server sends a code to the app in the browser in a query parameter. The app uses this code to request access tokens and/or ID tokens. After the user logs in successfully with the authorization server, they are redirected to a page in your application that you specify.

Redirects are targets of attack because they can be hijacked if not configured properly. An attacker could redirect the authorization code to their own domain (instead of yours) and then impersonate a public app and exchange the code with the authorization server for tokens.

Do not redirect to URIs obtained from a query parameter

Clients and authorization servers must not redirect to URIs obtained from a query parameter, as these can be tampered with. For example, consider the following URI:

https://your-site.com/login?redirect_url=https://yuor-site.com/account

The redirect will actually send the user to yuor-site.com instead of your-site.com. Because the URLs are similar, the user may not even notice the difference. This is called an open redirect: the user has control over the redirect since it’s clearly visible (and can be modified) in the URL.

Use exact string matching when configuring allowed redirect URIs

Authorization servers should require exact string matching when accepting user configured allowed redirect URIs, as opposed to pattern-matching. Unsafe patterns or naive implementations on the authorization server can result in unwanted outcomes. For example, consider the following pattern:

https://*.your-site.com/*

The intent here is to allow any subdomain of your-site and any subpage of your-site as a redirect, but if the authorization server interprets the wildcard * as “any character” instead of “any character valid for a domain name,” something like https://attacker.com/.your-site.com could be valid based on this pattern. Alternately, an attacker could establish a subdomain that would be allowed by this pattern even if it is implemented properly.

Authorization servers should ensure exact string matching is required, but if your authorization server does allow pattern-matching, don’t use it. Instead, only add exact URLs to the authorization server’s list of allowed redirect URIs. The only exception to this is for ports on localhost for native apps.

Protect against Cross Site Request Forgery (CSRF) attacks

CSRF attacks are malicious requests that come from somewhere other than the authorization server. OAuth 2.0 and OIDC provide methods to mitigate CSRF attacks. Best practices state that CSRF protection must be implemented.

OAuth 2.0 Proof Key for Code Exchange (PKCE) or OIDC nonce are both sufficient measures to protect against CSRF attacks.

Validate token issuer when using more than one authorization server

Clients using more than one authorization server should validate the issuer (the authorization server that issued the token) iss parameter in any tokens they receive. This ensures interaction with the correct authorization server.

Authorization Code Grant

Public clients must use Proof Key for Code Exchange

Public clients (like native apps or browser-based apps) using OAuth 2.0 must use Proof Key for Code Exchange with the authorization code grant. PKCE (pronounced “pixie”) adds an additional layer of security to the authorization code exchange between your app and the authorization server.

With PKCE, the app creates a random string (called the code_verifier) for each authorization request. It then hashes the code verifier using a hashing function called a code_challenge_method. Hashing is irreversible: once a string has been hashed, it’s impossible to retrieve the original input. The app sends the code_challenge and the code_challenge_method to the authorization server along with the authorization request.

Now the authorization server knows the code_challenge (the hashed code_verifier) and the code_challenge_method (the hashing method used to create the code_challenge). The authorization server then creates a code and associates the code_challenge and code_challenge_method with the code. It sends the code to the app in a query parameter.

The app takes the code and the code_verifier (the original, unmodified string) and sends them to the authorization server with an access token request. Although the authorization server can’t “un-hash” the code_challenge, it now has everything it needs to repeat the same hashing steps the app took before the app sent the authorization request.

The authorization server uses the code_challenge_method to hash the code_verifier and then compares the hashed output to the code_challenge it received from the app earlier. If the output matches the code_challenge, the request is legitimate, and the authorization server issues tokens.

Confidential clients (such as traditional web apps) should also use PKCE. PKCE protects against CSRF and authorization code injection, an attack where an attacker tries to exchange a stolen authorization code for tokens. In OAuth 2.1, all apps (public and confidential) using authorization code grant will be required to use PKCE.

Do not use implicit grant

In implicit grant, tokens are delivered to a public app in the browser in a query parameter. All public apps must use authorization code grant with PKCE. Implicit grant must not be used. It’s not secure to expose tokens in a browser URL where they can easily be accessed and stolen.

2. Prevent token replay

Token replay is when an attacker attempts to re-use another user’s token to gain access to protected resources.

Use sender constrained access tokens

In order to prevent token replay, access tokens should be sender constrained. Sender constraint scopes a token to a specific sender (e.g., the authorization server that issued the token). The token recipient (e.g., a protected API) will only accept a token if the sender can prove they know the necessary secret. Methods of sender constraint include mutual TLS or Demonstrating Proof of Possession.

Public client refresh tokens must be sender constrained or rotated

Public clients, such as browser-based or native applications, must also implement sender constraint for refresh tokens. Refresh tokens are long-lived. They are used to keep a user’s access valid without forcing them to manually reauthenticate every time the short-lived access token expires. Because of their longevity and use case, they are prime targets for exploitation. Sender constraining refresh tokens protects them from being used in CSRF attacks.

Alternatively, refresh tokens should be rotated by the authorization server. Refresh token rotation means every time the authorization server receives a request to refresh the access token for a user, a new refresh token is also issued, and the previous token is invalidated.

3. Access tokens should grant the minimum privileges needed

Access tokens provide authorization to access protected resources. Overloading access tokens with more permissions than needed increases risk. Access tokens should grant the bare minimum permissions.

Restrict access token use to a specific API (or at the most, a small set of APIs). An access token uses an aud (audience) parameter to store the ID of the API (or resource server) it’s intended for. Any resource server not listed in the aud must reject the token and deny access.

Once an API verifies it’s the intended audience of the access token, it still needs to restrict access to specific resources or actions. The token may contain a scope parameter or authorization_details that tell the API what to allow. For every request, the API must verify that the token does indeed grant the requested access.

4. Don’t use user credentials to obtain access tokens

Resource Owner Password Credentials (ROPC) is an OAuth 2.0 grant type that uses user credentials (such as username and password) for authorization to obtain an access token. This must not be used. Considering the other best practices above, it may already be clear why this is now prohibited. ROPC insecurely exposes the user’s credentials to the client. It has an increased attack surface and isn’t designed to work with multi-factor authentication. Since ROPC is bound to a specific web origin, WebCrypto and WebAuthn may be impossible to use with it.

5. Authorization servers should enforce client authentication

This best practice is more relevant to authorization server providers than app developers, but it provides important context. Client authentication is when an authorization provider verifies the app is who it claims to be. Authorization servers should issue and register confidential client credentials to do this.

The authorization server should use asymmetric cryptography such as mTLS for OAuth 2.0 or Signed JSON Web Token (Private Key JWT) to verify the identity of an app requesting authorization. JWT asymmetric cryptography means a private key is used to encrypt data and a different, public key is needed to decrypt it. This way, authorization servers don’t need to store sensitive symmetric keys (which can both encrypt and decrypt data).

6. Other recommendations

The authorization server must not allow Cross-Origin Resource Sharing (CORS) at its authorization endpoint since the client redirects the browser to this endpoint rather than accessing it directly.
OAuth Authorization Server Metadata can help improve security. Authorization servers should publish metadata and clients should use this metadata for configuration.
- This ensures that security features and new OAuth features can be enabled automatically by software libraries.
- Metadata reduces misconfiguration.
- Metadata can help cryptographic key rotation.
Authorization servers should not allow clients to influence their own client_id.
End-to-end TLS (Transport Layer Security) between the client and API is recommended.
Unencrypted network connections (HTTP) should not be allowed when transmitting authorization responses (except on native clients that use loopback interface redirection).
If the authorization response is sent with in-browser communication like postMessage instead of HTTP redirects, both the sender and receiver must be verified.
Endpoints directly accessed by clients may support CORS (i.e., without browser redirection), such as the token endpoint, metadata endpoint, etc.

Attacker model, attacks, and mitigations

RFC 9700 Best Current Practice for OAuth 2.0 Security also includes an updated OAuth 2.0 attacker model and descriptions of security attacks and guidance for their mitigation. Though this article doesn’t cover these parts of the specification in detail, some attacks and mitigations are briefly covered with the best practices above. To learn more about the attacker model, attacks, and mitigations, please see the specification.

Conclusion

I hope this developer’s overview of OAuth 2.0 Best Current Practice was useful! If you have any questions or just want to chat, please reach out to me on LinkedIn, Bluesky, or X.

How to Drive Developer Growth and Engagement

Kim Maida — Wed, 19 Oct 2022 20:13:40 +0000

To effectively drive sustainable developer growth and engagement for products that serve developers, I created the Developer Empowerment flywheel. When connecting with developer audiences on behalf of an organization, driving developer growth and engagement needs to be cross-functional, measurable, and scalable.

My Developer Empowerment flywheel looks like this:

Inspire

We want to inspire developers in the community in a variety of ways, including but not limited to:

Ideas – Sharing inspiration on what the product’s capabilities are and how to begin. We want to start small: have fun and share basic examples with a low barrier to entry. Showcase possibilities and get people to an “aha!” moment as early as possible.
Use cases – Show how building with the product helps in a practical sense. How does developing with our product solve pain points, enable new capabilities, and provide features that developers want to take advantage of in the real world?
Showcases – Highlight the really cool, powerful, and / or unique projects that developers have built.
Opportunities – Inspire developers to explore, experiment, and think much more broadly about how they can build awesome projects and accomplish things that they haven’t been able to accomplish previously, without our product.

Educate

Next we want to provide valuable learning resources to educate developers on how to build efficiently and effectively with our product.

Documentation – Provide thorough, easy-to-follow documentation with an exceptional developer experience.
Tutorials – Create and share tutorials, quick starts, blog posts and other learning content on a variety of mediums including written, video, interactive, and more.
Demos – Share practical demos with real-world applicability; go beyond Hello World to provide value by showing developers how to build things that are practical and useful.
Presentations – Talk about how to think about architecture, design patterns, principles, and best practices; provoke thought and be available to answer questions.
Workshops – Dig deeper with more involved guided learning and teach interactively. Workshops are high value because of the depth of commitment involved.

Education also goes beyond technical content: it’s also about helping developers to think about strategic organizational problem solving, hacking productivity, and builder best practices.

Activate

Next we want to activate developers to start building and actively touching the product. This can take a few different shapes:

Create New – Sign up and take an action (install an SDK, create an app, etc.)
Commit Code – Start writing code (commit code to a repository, make an API call, deploy to an environment, etc.)
Subscribe – Subscribe to newsletters, course platforms, podcasts, YouTube channels, Twitch channels, etc. Commit to learning more on a regular basis.
Join Community – Join a product-related developer community or user group.
Reach Out – Activate developers to reach out to product advocates to have conversations, find out more, and ask questions as they’re getting started.

Engage

Once we’ve activated developers to get involved with the product, we want to engage with the developer community.

Discussions – Engage developer users to participate in chats or discussions, such as communities, forums, and social platforms like Reddit, StackOverflow, etc.
Program Participation – Engage developers to actively participate in activities like hackathons or longer-running developer initiatives like 100 Days of Code challenges; engage developers to join and actively contribute in developer community programs like ambassador or expert or certification
Provide Feedback – Encourage developers in the community to engage in conversations providing value product and / or developer experience feedback.
Ask Questions – Engage with product advocates to ask questions that aren’t in the docs and show active interest in learning more and going deeper.

Empower

Finally, we want to empower builders to inspire other developers and continue to perpetuate the Developer Empowerment cycle.

Support – We want to provide support and resources to help developers teach others what they’ve learned.
Enable – Let’s provide high-value opportunities for developers to learn from and work with advocacy teams at the organization.
Promote – We should shine a spotlight on work developers in the community have done and promote resources they’ve created.
Advocate – We should empower builders to become advocates themselves and teach others.

Empowerment can happen through a variety of different avenues. We can create experts and ambassadors programs, facilitate and support external community meetups, and put on developer conferences wherein we invite and highlight community speakers and contributors. We can also partner with community experts and content creators. By empowering developers who build with our products, we foster the continuation of the developer empowerment cycle.

People

Who are the participants and contributors in the Developer Empowerment flywheel?

Developer audience – Developers in the community with the potential to use the product are key to target in the Inspire and Educate phases.
Builders – Builders are developers who currently are in the process of learning to develop with the product, or are actively developing with it. This could include members of the wider developer ecosystem, developer customers, or internal engineers who work on the product itself. We want to ensure we are educating, activating, and engaging with Builders.
Champions – Champions are developers who actively advocate for the product in the community. Developer champions create educational content, provide product feedback, participate and contribute to developer community programs, and / or share the work they’ve done with the product and encourage others to use the product as well. Champions are developers who we want to empower so they can contribute to the flywheel by inspiring and educating more of the developer audience.

Cross-Functional Developer Growth and Engagement

Developer Relations is uniquely positioned to be capable of supporting, collaborating with, and facilitating the work done by almost every other department in an organization. Here are a few examples of cross-functional work and support that can be done in the Developer Empowerment flywheel fostering developer growth and engagement.

Product

Collect and execute product feedback
Collect and execute developer experience feedback
APIs and SDKs adoption, usage, and engagement
Documentation feedback, improvements, and content contribution
Guides, tutorials, and quick start content creation, promotion, and experimentation
Developer tooling
High-value feature identification on product roadmap in response to community insights and feedback
Beta-testing, early access, and Developer Advisory groups

Partnerships

Partner-developed integrations
Co-marketing
- Technical case studies and demos
- Partner showcase
- Webinars and events
Partner developer training and enablement
Developer partner programs
- Product insiders
- Developer certification

Developer Marketing

Developer Content
- Blog posts
- Demos and sample applications
- Quick starts and guides
- Videos, livestreams, office hours
- Live events, workshops, trainings, launch events
Developer community
- Engage in conversations with developers (live and async)
- Promotion of developer projects and contributions
Developer programs
- Developer Experts / Champions / Ambassadors
- Developer certification program
- Technical training
- Advocacy empowerment

Additional Cross-Functional Opportunities

In addition to the above, there are also many more opportunities for cross-functional work throughout the flywheel. Developer growth and engagement can work with Field and Sales teams to target specific regions or verticals, tilling and fertilizing the soil so Sales can plant seeds.

We can also work alongside Customer Success to “open source” common support questions and answers to create public FAQs, rotate forum staff, and create new resources while also performing ticket deflection.

Developer growth and engagement and developer relations also have opportunities to partner closely with Architecture or the Office of the CTO to ensure growth and engagement teams are consistently providing highest quality best practices and the most accurate information and resources to the developer community.

How to Measure Developer Growth and Engagement

The Developer Empowerment flywheel is measurable in a number of different ways.

Trusted Metrics

Trusted metrics directly measure developer growth and engagement and conversion. Personally, I like to focus on percent of month over month growth over time rather than on specific “magic numbers.” Examples of trusted metrics include (but are not limited to):

Growth in Monthly Active Users
Growth in new tenants / apps / instances created
Growth in projects deployed
Growth in projects publicly distributed in marketplaces
Subscriber growth (developer newsletters, courses, content channels such as Twitch, YouTube, etc.)
Growth in monthly active participants in developer programs
DevRel Qualified Leads

Insight Metrics

Insight metrics are helpful and informative, but should not be used to measure success in a strict sense — success should be measured through trusted metrics. These metrics help us to identify trends, patterns, and general awareness.

Documentation traffic growth
API and SDK usage
New content developed
Number of people reached through content, presentations, sponsorships, etc.
GitHub metrics
Package installation metrics

Key Performance Indicators

Key Performance Indicators (or KPIs) help us understand how we’re doing, growing, and making progress. KPIs should be used in conjunction with trusted metrics. Similarly, setting KPI goals that are measured by percentage growth month over month helps teams to focus on performing scalable efforts rather than fixating on a single goal number each month or quarter. When goals are set to grow over time, contributors concentrate their strategies, tactics, and overall efforts on initiatives that continue to grow exponentially to continually generate outcomes, rather than starting and concluding with one outcome.

Growth in content and documentation traffic
Improvements implemented as a result of developer feedback
- Developer experience feedback implemented
- Developer product feedback implemented
Growth in people reached through trainings, workshops, presentations
Developer program membership growth
- Developer community contributions
- Developers certified
Developer campaign engagement
Developers reached through partnership engagements

Scalable Developer Growth and Engagement

One of the most important key features of the Developer Empowerment flywheel is that it’s scalable. Scalability is vital when we are driving sustainable developer growth and engagement.

Company Developer Engagement and Advocacy

Within the organization, we ensure that we have developer growth and engagement as well as developer advocacy actively working to empower developer users and community. This includes making sure that we:

Create scalable resources, content, programs, and initiatives
Empower developers in the community by teaching, enabling, and supporting
Have candid conversations and answer questions
Collect and act on feedback to implement actionable changes and improvements
Advocate on behalf of the developer users to the company
Promote and share work and accomplishments from the developer community

Developer Community

Empower and engage with the developer community to:

Use and share helpful resources
Participate in learning campaigns, code challenges, hackathons, courses, etc.
Provide product and developer experience feedback
Build amazing things
Subscribe to content (newsletters, content channels, forums)
Share accomplishments
Join developer programs

Sustainable Developer Empowerment

Sustainable developer empowerment means that we are continuously ensuring that we:

Support developers in the community
- Teach beginner, intermediate, and advanced developers
- Solve problems
- Advocate for the developer experience
- Create a productive feedback cycle
Empower developers in the community to inspire and educate others
- Share how to teach
- Promote the work and accomplishments of developers in the community
- Write the “missing manual” by identifying questions and pain points from active developers
- Spotlight great work
Empower developer employees within the company
- Share what they’re working on
- Promote engineering and content work
- Support internal employee advocacy

Organizations that care deeply about developer products, developer experience, and developer users can take advantage of the Developer Empowerment flywheel to continually increase their developer growth and engagement.

If you would like to use it in your organization collateral, the Developer Empowerment flywheel graphic can be downloaded here.

How to Connect With Your Developer Audience

Kim Maida — Tue, 26 Apr 2022 12:05:42 +0000

If your organization provides any kind of technology or service that is consumed by developers, you’ve likely asked “How do we build our developer audience?” In Which Department Does DevRel Belong In? I mentioned that it’s a myth that “developers hate marketing.” Let’s dig a little deeper into the developer audience and what we (I am a developer myself) are looking for when we evaluate products, technologies, and even the very companies that market to us. How can Developer Relations teams form a positive and lasting connection with their developer audience?

What Does Your Developer Audience Want?

The first step in understanding the developer audience is identifying what developers want. And this shouldn’t be surprising: developers want the same things everyone else wants. Developers want:

High quality tools, products, and services
To be able to trust the brands they support
Their lives and work to be more seamless and efficient

What are the characteristics of developers as an audience for your products and services?

Developers are technologically savvy and have a keen understanding of the digital space
By virtue of their profession, developers have highly developed critical thinking skills
Most developers are sensitive to and repulsed by dark marketing tactics
Developers are good at spotting BS
Developers can also be somewhat unforgiving — get on someone’s bad side once, and you may very well lose them forever

Developer Relations is About Building Great Relationships

Developer Relations is about relationships. This is no surprise. But what are the foundations of great relationships that thrive and endure?

There are several things we should focus on in order to connect with developer communities and form positive relationships with developers. This can be boiled down in a straightforward sequence:

1. We Act With Integrity and Empathy

Developer Relations does not practice lip service or sycophancy. We don’t flatter or agree with influential people or companies just to gain an advantage from them; we don’t butter people up or shine apples.

In DevRel, we don’t just say what people want to hear. We don’t support something if we can’t back it up with actions. Developer Relations is about relationships, and great relationships are built on trust. Developer Relations aims to have a great relationship with developer users, and to do this, DevRel’s core philosophy and communications must have integrity and empathy, and this fosters respect.

Solve Problems, Have Conversations, Be Open to Criticism

We listen. This means listening to the good, and to the bad. In DevRel, we listen to what people have to say without rushing headlong to provide default solutions. We have conversations instead of Q&As and take the time and care to understand our developer users and their challenges and needs. Emotional intelligence and empathy are key qualities that anyone working in Developer Relations should have in abundance.

Different Strokes for Different Folks

We recommend what we honestly feel works best for the user, not what serves only our own interests. Tech is not one-size-fits-all. We don’t sell a user on a tool that isn’t the right fit for them or their needs. Recommending the least-best — or even second-best — solution (if we know the best solution is elsewhere) will only backfire and result in negative sentiment overall. We aren’t selling or shilling; we’re forging relationships.

Keep Promises

We are honest and realistic about options and next steps, and then we back up what we say with actions. When we make a recommendation or a promise, we stand by our word and take responsibility for the outcomes.

2. Build Trust and Respect

When we act with integrity, we foster trust and build respect with our developer audience. Developers tolerate (and occasionally even enjoy) sales and marketing, but if they sense you might be disingenuous, you risk losing them forever.

We build trust and respect by acting with integrity, solving problems, and providing honest discourse and high-quality resources. This is true for products and also for the organizations that provide the products. In many cases, a company’s reputation can become entwined with the level of respect a developer has for the service or software being provided.

To continue to build trust and respect, Developer Relations teams should instill quality and integrity in all of their work. This includes conversations and communications, but also presentations, blog and video content, event participation, documentation, GitHub interactions, and more.

3. Inspire Loyalty and Confidence

Acting with integrity and building trust and respect inspires loyalty and confidence in products and in the organization providing those products. In Developer Relations, we are working to satisfy and serve our developer product users. But that’s not all: we’re also brand ambassadors representing an organization to a developer audience.

A company whose products are represented with integrity, thoughtfulness, and high quality resources inspires confidence in its users. Trust and confidence inspires loyalty, and your developer audience will come along with you and continue to support your products and organization as long as you both serve their needs and prove worthy of their respect.

Connect With Your Developer Audience

To really connect with your developer audience, you don’t need to have the most followers on Twitter, be the most famous speaker, have the shiniest reputation, work at the most prestigious company, or even have the most popular product. You need to act with integrity and empathy, and provide high quality resources and insights. This builds trust and respect in your developer community, and inspires loyalty and confidence with your developer audience.

Which Department Does Developer Relations Belong In?

Kim Maida — Sun, 11 Jul 2021 18:44:13 +0000

The battle over which department Developer Relations belongs in continues to be long and ongoing.

Does DevRel belong in Product? Marketing? Engineering? Any of the above? None of the above?

Discussions — and arguments — over where DevRel should align in an organization often become heated and passionate. Many practitioners have very strong feelings about this, occasionally holding views that are not aligned with where their organization's executive leadership believes DevRel should report.

The thing is, the answer here is complex and nuanced. Developer Relations is so many disciplines combined. DevRel is about:

Connecting with developer users and audiences
Cultivating, growing, and nurturing developer communities
Advocating on behalf of developers to make better products with a great developer experience
Advocating on behalf of the organization to bring products to more developer users
Understanding the product on a deep, technical level and providing education, resources, and support to developers
Engineering demos, samples, real world repos, code tutorials, etc.
...and so, so much more

These goals and responsibilities fit into several different "segments" of a typical tech organization. DevRel also needs resources, cooperation, and collaboration across many teams and departments in order to be successful.

So the question repeatedly arises: where does Developer Relations belong in an organization?

I have worked in Developer Relations at four different companies. I have had countless conversations with peers in the industry regarding org structure, and where DevRel belongs in order to be successful and effective. In these conversations over the years, the often-repeated stance I kept hearing was that "DevRel shouldn't be in Marketing."

I have heard this dozens of times. I have said it myself in the past.

But why?

Why do we keep insisting that DevRel doesn't belong in Marketing? And why then, is DevRel very often in Marketing anyway?

Myth: "Leadership Doesn't Understand DevRel"

Every company I've done DevRel at has had DevRel in the Marketing org. Why would companies do this if it was not appropriate? As practitioners of Developer Relations, do we actually believe that our employers would put so much money, care, and sheer effort into hiring DevRel teams and providing them with substantial financial resources if they didn't understand the reasons behind having DevRel in the first place?

For years, we've claimed that DevRel is such a new discipline, executive leadership doesn't understand the true purpose of DevRel. We've insisted that our leadership thinks DevRel is about pipeline, or lead gen, and doesn't get that it's something else.

But c'mon now. DevRel is no longer a new discipline in tech. Company leaders are not hiring DevRel teams without understanding what they mean and what their goals are. They aren't doing it because their competitors have DevRel teams. Hundreds of thousands — even millions — of dollars are poured into DevRel teams. Org leaders do not do that carelessly. They do not do that if they don't understand what they're doing it for.

It's time to give our executive leadership more credit than that. And it's an exciting time: DevRel has matured to the point now that there are executive DevRel roles. Developer Relations, as a key discipline, has earned its place at the leadership table.

The old argument of "my org's leadership doesn't understand DevRel, that's why they put us in Marketing" no longer stands up under scrutiny. It is still true in some companies, but I would strongly encourage folks who are looking for DevRel roles to vet potential employers carefully during an interview process to determine if the greater understanding of DevRel is shared by leadership. (Just ask "what does DevRel mean to your company?" and you'll get your answer. If there's not alignment between the answer and your fundamental philosophy, it might be a sign to pass and look elsewhere.)

Myth: "DevRel Isn't About Making Money"

Weeelll...

That's untrue. It's untrue because (unless you work for a nonprofit) every team at a tech product company exists to make money. Engineering builds products to make money. Design designs products to make money. Marketing promotes products to make money. Sales sells products to make money. Investors invest in startups to make money. Companies raise funding to eventually become profitable (a.k.a. make money). And yes, DevRel educates and shares and helps to — you guessed it — make money.

In DevRel, we sometimes like to say that we aren't "selling" the product. But that isn't entirely accurate. When we evangelize a technology — even an open source one — we are selling people on the idea that a technology or product can help them or make their work better / easier / faster / etc. While that isn't Sales in the classic sense, it is about encouraging people to choose to use something in order to improve their lives in some way.

And that is the crux of Top of Funnel marketing. We want to increase brand awareness. We hope the developers we reach will choose to use our products. We hope they have a great experience with us and want to continue to be users of our products. And we hope that, at some point, they will get enough benefit and value out of the product that they consider it very worth paying for.

Myth: "Developers Hate Marketing"

This blanket statement is not true either. A more accurate statement might be: "Developers are good at detecting BS." As we should be!

We developers are consumers too. We consume products, watch ads (okay, mostly when forced to), glance at sponsored content, read signs in shop windows, and check out sponsor halls at conferences.

I — as a human being and also as a developer — want to be told about products and technology that can make my life better. I want to be marketed tech products that are a pleasure to use, increase efficiency, and help me do my job. I encourage you: do your best to market to my interests! I'm a tough crowd, but I welcome it. And I'm more than happy to pay for your product — if it's worth it.

The notion that "developers hate marketing" is an oversimplification. The misconception that marketing is inherently insidious or disingenuous is where this idea goes seriously astray; and that's why DevRel's role in Developer Marketing is so pivotal.

Developer Relations 💙 Developer Marketing at Developer-First Companies

Whether your DevRel team reports to Product, Engineering, Marketing, directly to the founders, or elsewhere in the organization, DevRel is — at its core — Developer Marketing.

This is a good thing. And it's time for us to recognize and acknowledge that it's a good thing.

At developer-first product companies, Marketing is a great place for Developer Relations. I want to make this distinction very clear though: when a company’s primary objective and business model is centered on creating software or tools for developers, the understanding of Developer Relations comes from the top down. Open Source or developer software companies have a prime directive that focuses on developer satisfaction, adoption, and happiness. At these companies, DevRel being in Marketing makes sense.

Note: At companies in other product sectors, it may make much less sense for DevRel to be in Marketing. If your company sells a consumer product, B2B, or B2E — and you also provide APIs, etc., then DevRel may serve much better in Engineering or Product.

DevRel in Marketing at developer-first companies can work well for several reasons:

Marketing has a deep-rooted, cooperative relationship with Product. Espoused in the discipline of Product Marketing, Marketing as an organizational powerhouse has an intimate but also holistic knowledge of what's going on in Product and Engineering: what features are being developed, what's happening when, who the primary users would be, what user research is being done, how should the product be presented to the market, etc.

Marketing has budget for the types of things DevRel teams do. DevRel is expensive! Sponsorships, swag, airfare, hotels, streaming, recording, production, running programs and campaigns, etc. cost a lot of money. Marketing is generally allocated significant budgets for exactly these types of things. If DevRel is in Engineering or Product, DevRel teams may struggle with obtaining enough budget for things like big sponsorships, sweepstakes prizes, etc. since DevRel activities may not be well incorporated into the bottom line for how the department's performance is typically measured (but of course, YMMV).

Marketing is data-driven. DevRel is notoriously "hard to measure" — but is it really? Marketing organizations are data-driven, and operate with growth in mind. Having ready access to metrics like attribution, website and blog traffic, npm traffic, signups, trials, HubSpot, Twitter, YouTube, Twitch, competitive analytics, etc. can be quite beneficial for plotting a course for increasing DevRel performance, engagement, and adoption. Working alongside Marketing teams like Data, Brand, and Growth can make a huge difference in enabling DevRel to gather, predict, and respond to a broad spectrum of data regarding how a company interacts with users and potential users.

Marketing operates with a growth mindset, and thrives on experimentation. Experimentation and testing different strategies and tactics is par for the course for a Marketing organization. And experimentation is a crucial component of DevRel. Testing different DevRel strategies, programs, and campaigns is a mode of operations that Marketing supports, encourages, and has the means to execute quickly. Pivoting on a dime won't shock Marketing leadership, and unsuccessful experiments result in good learning experiences, not reprimand or backlash.

Marketing owns the strategy around how a product is delivered to an audience. Different types of products require different GTM (Go To Market) strategies. Open source software release? DevRel can be out ahead of that: connecting with OSS devs, running interference on GitHub, holding demo livestreams and office hours, doing talks at events, and more. Big commercial release? Maybe DevRel supports Product Marketing by hosting technical demos, sharing access to new features with community champions, arranging impactful event sponsorships, and forwarding booth inquiries to Sales. DevRel is an integral part of GTM, and being in Marketing enables DevRel teams to have ownership over their role and responsibilities when product releases go public. Some DevRel teams in Marketing wrote and own the entire GTM strategy and process for OSS launches.

These are just a few examples of how DevRel fits well into a Marketing org. There are many more (e.g., working closely with Content Marketing, Brand, Growth, Social Media, Partners, Marketing Engineering, Data, Demand Generation... the list goes on).

Developer Marketing Core Philosophy

My core philosophy around Developer Marketing is concerned with three primary tenets:

Be Genuine
Build Trust
Deliver Value

Developers want their work to go smoothly, be efficient, and be interesting; there’s a nuanced difference between this and wanting things to simply be "easy." Developers are interested in technology that enables these things, and allows them to do work that they are then proud of and feel good about.

Being genuine and building trust are of tantamount importance at an ethical level. Companies that focus on this are going to be more successful. Developer Relations is the piece of the organization that most strongly embodies this, and cultivates relationships built on clarity and trust with the developer community.

Then put your money where your mouth is: Developer Relations is about delivering value to developers. Back up words with actions: share knowledge, take feedback, make things happen as a result.

This is what marketing to developers is about: are we offering something that is genuinely useful? Is it helpful? Does it improve life for developers, and for their teams? Does it have a great developer user experience? If yes, developers are going to be open to trying it, building a relationship with a technology or brand, and becoming practitioners.

Developer Relations is About Relationships, Not Sales

DevRel operates on the front line of this Developer Marketing philosophy. DevRel demonstrates how a company's products help developers enjoy architecting something they can then be proud of. DevRel can elevate champions in the community and be the friendly, helpful, knowledgeable faces of an organization.

DevRel is also uniquely positioned to be truly genuine with developers. Is the product not the best suited for someone's situation? DevRel folks can outright say so! They can offer other solutions, and clarify when and how their company's products help — and when they don't. Unable to afford a commercial add-on from a company, but like to use their open source offerings? DevRel won't say "come back when you have the money." Instead, DevRel helps developers think through (or even build) an affordable alternative.

Developer Relations is Cross-Functional

At the end of the day, no matter what department DevRel lives in (or if DevRel is its own department or reports to the Office of the CEO), DevRel is a heavily cross-functional discipline.

An effective DevRel team does not only build relationships with the community outside the company: it also builds relationships and collaborations within the company and many — if not most — of the other departments.

For this reason, DevRel teams in Marketing have an advantage: Marketing departments have cohesive relationships with a lot of the rest of the organization already (Product, Customer Success, Support, Sales, Engineering, etc.). The teams within Marketing are also key collaborators in DevRel's goals and mission (as discussed above), and working alongside them on a daily basis empowers DevRel to position itself optimally to have great reach and influence.

So no matter what formal department your DevRel team lives in, Developer Relations as a discipline should follow the tenets that guide good Developer Marketing: be genuine, build trust, deliver value, and have fun bringing cool things to devs to make their lives better (and maybe even make money while doing it!).

Smarter & Faster Angular Development with Nx

Kim Maida — Wed, 28 Oct 2020 16:17:16 +0000

Nrwl Architects Juri Strumpflohner and Isaac Mann presented Smarter & Faster Angular Development with Nx, a free, live EnterpriseNG webinar for Angular developers in October, 2020. In case you missed the stream — or if you tuned in live but want to review the content again — the video and slides are available below.

What you will learn:

Driving good architecture with Nx using monorepo development: how Nx helps solve problems that developers face when structuring projects
How Nx provides modern tools and improved developer experience (to learn more about how Nx modernizes Angular, you can also check out this blog post)
Scalability and increased development and build speed with Nx
Demos!
Q&A

You can watch the full webinar for free below 👇, or view the slides by clicking here.

Signing and Validating JSON Web Tokens (JWT) For Everyone

Kim Maida — Sun, 27 Sep 2020 21:17:18 +0000

When I started learning about JSON Web Tokens, there were some things that were straightforward to understand — and some concepts that felt like "hidden secrets" of JWT lore. 🧙‍♂️

This article aims to demystify signing and validating JSON Web Tokens, with little need for security or cryptography knowledge.

Note: This article is a companion to my post on Authorization and Authentication for Everyone. I recommend that you read that post first.

JSON Web Token (JWT) Recap

JWTs are — in general terms — reasonably approachable. Information about them is readily available from many sources, chiefly covering:

JSON Web Tokens (or JWT) are a compact, URL-safe way to transfer pieces of data between two parties (such as an authorization server and an application).
The JWT format is defined by IETF specification RFC 7519 and is composed of three segments (a header, a payload, and a crypto segment.
JWTs are signed with a key when they are generated and then validated with a key upon receipt so we can verify that they haven't been modified in transit.

The Challenge with Understanding JWT

There's a meme about being introduced to a concept and then there are steps missing while you're expected to be able to get to the end result without knowing the steps in between. The meme demonstrates "How to draw an owl":

To me, not being able to find approachable information about signing and validating JWT felt like the missing steps to draw the owl.

Most of the resources I dug up took me deep down the rabbit hole — until my head was swimming with mind-melting jargon, Alices and Bobs (placeholder names used in cryptography examples), and complex maths. Instead of learning simpler, incremental steps to aid in my understanding, it felt like I was being given ten more complex, complete owl drawings.

Why Don't We Need to Know How Signing and Validation Work?

Why is this? Why do most JWT resources simply say "and then you sign and validate" and leave it at that?

Think of it this way: for human beings to be effective or skilled with a tool, we don't need to know the intricacies of the tool's components.

🚙 When you get into your car to drive to the grocery store, do you need to know how internal combustion works? You don't.

🔋 When you charge your laptop, do you need to know what chemical reactions take place in a lithium ion battery to create the flow of electrons in a circuit to store and produce energy? Nope!

We can still be good drivers or great computer programmers without intimate knowledge of these things. We trust that the manufacturers have used their expertise, specifications and standards, and due diligence to make useful tools for us to be more effective at the jobs we need those tools for.

This is why you don't need to know the exact process for signing and validating JWT in order to effectively use them for authenticating and authorizing your applications and APIs.

Okay, but you're reading this because you still want to know the missing steps to draw the owl. While you generally should not sign and validate tokens yourself (seriously, leave this to the experts — identity providers and Identity-as-a-Service platforms!), knowing how it works can be helpful in making you feel more comfortable with using JWTs. 😌

Anatomy of a JSON Web Token

We covered the anatomy of JWT in depth in the previous blog article on authentication and authorization, but let's do a very brief recap.

JSON Web Tokens are composed of three URL-safe string segments concatenated with periods .

Header Segment

The first segment is the header segment:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

The header segment is a JSON object containing a signing algorithm and token type. It is base64Url encoded (byte data represented as text that is URL and filename safe).

Decoded, it looks something like this:

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload Segment

The second segment is the payload segment:

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0

This is a JSON object containing data claims, which are statements about the user and the authentication event. This is the information that the JWT is conveying from one entity to another. Data claims might look something like this:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

This is also base64Url encoded.

Crypto Segment

The final segment is the crypto segment, or signature. JWTs are signed so they can't be modified in transit. When an authorization server issues a token, it signs it using a key.

When the client receives the ID token, the client validates the signature using a key as well. (If an asymmetric signing algorithm was used, different keys are used to sign and validate; if this is case, only the authorization server holds the ability to sign tokens.)

The Rest of the Owl Signature

This is where the missing steps of the ~~owl~~ JWT signing / validation process are. Let's go through it step-by-step.

RS256 Signature

For this article, I'm going to assume use of an RS256 signing algorithm. RS256 is an RSA Digital Signature Algorithm with SHA-256. RSA256 is an Asymmetric Key Cryptography algorithm, which uses a pair of keys: a public key and a private key to encrypt and decrypt. In this case, the private key is used by the token issuer (authorization server), and the public key is used by the application receiving the token in order to validate it.

If this feels jargon-laden and confusing right out of the gate, don't worry! Let's break it down into smaller, distinct steps.

The JWT Crypto Segment: Revisited

Let's explore what the crypto segment actually is.

Signing Input

First we take the first two segments of the JWT (the header and the payload). In practice, that looks something like this:

In other words, this is the base64Url encoded header and the base64Url encoded payload, concatenated with a . period:

This is what we call the signing input.

Hashing

We then hash the signing input using the SHA-256 hashing algorithm. Hashing converts one value into a different value. A hash function uses a mathematical algorithm to generate a new value from an existing one.

Hashing is irreversible. Once we have hashed an input, we cannot get back to the original input again.
Hashing will always produce the same output for the same input.
No two different hashing inputs will produce the same output.

At this point, we have a hash of the header and payload segments — which we could compare to other hashes, but cannot reverse to return to the original signing input.

Encryption

Next we encrypt the hashed signing input. Unlike hashing, encryption is reversible: we can decrypt encrypted results (called ciphertext) to decipher the original input (plaintext).

For this step, the token issuer (authorization server) scrambles the hashed signing input using a private encryption key to produce an output (ciphertext).

Note: I mentioned earlier that this example uses RSA, which is an asymmetric signing algorithm and uses one key to encrypt tokens, and another key to decrypt them. To learn more about this topic in an approachable, practical way, check out Public Key Cryptography by Computerphile on YouTube.

This final output (the hashed, encrypted, encoded header and payload) is the crypto segment — or signature — of the JWT.

Note: If you'd like to dig much deeper into specifics of the RSA encryption algorithm itself, I recommend these great YouTube videos from Eddie Woo: The RSA Encryption Algorithm.

There you have it. That's the signature of a JSON Web Token. 🎉

Validating the Signature

Okay, we can start to understand how the token was signed — but that's only half of the story! The entire point of signing the token is so that whoever receives the token can validate that this JWT contains data that hasn't been tampered with.

How do applications validate JWTs?

What Are We Working With?

First, let's look at what information is available to the application that receives the token. We have access to the JWT itself: the header, the payload, and the signature (aka, the crypto segment). We also have access to a public key, which — as per its moniker — is freely available to the world.

Note: How are public keys made available? JSON Web Key (JWK) RFC 7517 defines a specification for JSON representation of a cryptographic key. If you use an authorization server platform, the public key will be provided — and often helpfully encapsulated in an SDK or library that handles JWT validation for you. You can read more in this blog article: Navigating RS256 and JWK.

Remember that the signature is the encrypted, hashed header and payload. Hashing is irreversible, but encryption can be decrypted (in this case, with the public key). Validation of the JWT is about getting to a point where we can effectively compare what we received to what we expect.

Decode Claims

The application can decode the header and payload to get some information. Recall that these two segments are base64Url encoded to make them URL safe. There is nothing cryptographically magical or secure about decoding these segments; in fact, you can do so with a simple online base64 decoding tool. Once they're decoded, we can easily read the information in them. For instance, we could decode the header segment to see what algorithm the JWT says it was signed with.

On the other hand, the signature's purpose is to validate that the information in the other segments is the same information that the authorization server sent — and that it hasn't been changed along the way.

From the decoded header, we can see:

{
  "alg": "RS256",
  "typ": "JWT"
}

Our received token says that the algorithm is RS256. Our application should be configured to expect the algorithm that our authorization server (token issuer) uses. When we read the algorithm in the JWT's header, we should verify that it matches our configured expectation. If it doesn't match, we should reject the token outright.

Hashing (Again)

If the algorithm in the token matches our expectation of RS256, we know we need to generate the SHA-256 hash of the header and payload segments. This will reproduce the signing input hash (again). Remember that hashing is irreversible, but the same input will always produce the same output. If we generate the hash from the header and payload we received, it should match the header+payload hash that is encrypted in the signature.

Therefore, we will hash the concatenated, base64Url encoded header and payload. Now we have the signing input hash freshly calculated on the application side.

Decryption

The hashed signing input is also in the signature, but it's been encrypted by the authorization server (token issuer) with a private key. The application has the public key, so we can decrypt the signature. Once this is done, we have access to the original hash: the one generated by the authorization server when the token was first generated.

Compare Hashes

Now we can compare the decrypted hash to the calculated hash. If they are the same, then we've verified that the data in the JWT header and payload segments has not been modified between the time the authorization server created the token and the time our application received it. 🎊

+ Verifying Token Claims

Once we've validated the signature, there's more to verifying the JSON Web Token's data. Claims in the payload segment should also be validated, because they contain information about the token issuer, token expiration, intended audience for the token, information binding the token to the authorization request, and more.

This data gives the receiving application vital details that the signature validation alone does not. For instance, examination of claims can reveal that a technically valid token was actually intended for a different application or user, has expired, came from an issuer that the application has no affiliation with, etc.

JWT Signing & Validation: Wrapping Up

We've now covered signing JWT and validating JWT signatures.

My hope is that you feel confident your understanding of JWT signatures and validation has a few more steps filled in now:

It's still important to reiterate that, as a developer, you most likely will never need to implement these processes yourself. And in fact, unless your engineering focus is security and identity, you probably shouldn't.

Identity platforms like Auth0, Okta, Ping Identity, and more do all of this for you: issuing and signing tokens on the authorization server side, and providing SDKs and libraries for validation and token management on the application or API side.

Resources and What's Next?

As I mentioned at the beginning, this article is a companion and supplement to Authorization and Authentication for Everyone, which is a much more comprehensive resource on the history of OAuth, OpenID Connect, authorization servers, JSON Web Tokens, API authorization, delegation with scopes, and more. Please check it out if you'd like to go further into identity topics.

Learn More

In an effort to create a digestible introduction to signing and validating JWTs that is widely approachable (and is the introduction I wished I'd had), I have simplified topics that are incredibly rich and complex.

🧠 To learn much more, try starting with some of the following resources:

Thank You!

If you'd like to chat, I'm available on Twitter at @KimMaida, and I also speak at conferences and events — at least, I did before COVID-19. I hope to see you sometime, and thank you so much for reading!

Authorization and Authentication for Everyone

Kim Maida — Mon, 20 Jul 2020 16:16:49 +0000

Authentication and authorization are necessary for many of the applications we build. Maybe you've developed apps and implemented authentication and authorization in them — possibly by importing a third party auth library or by using an identity platform.

Maybe you got the job done, but you really weren't clear on what was happening behind the scenes, or why things were being done a certain way. If you'd like to build a foundational understanding of what goes on behind the scenes when using OAuth 2.0 and OpenID Connect standards, read on!

Authentication is hard. Why is this? Auth standards are well defined — but challenging to get right. And that's okay! We're going to go through it in an approachable way. We'll address the concepts of identity step by step, building on our knowledge as we go along. By the time we're done, you should have a foundation and know where you might want to dig deeper.

This post is meant to be read from beginning to end. We'll build on top of each concept to layer knowledge when it makes sense to introduce new topics. Please keep that in mind if you're jumping around in the content.

Introduction
OAuth 2.0
The Login Problem
OpenID Connect
Authentication with ID Tokens
Accessing APIs with Access Tokens
Delegation with Scopes
Resources and What's Next?

Introduction

When I told family or friends that I "work in identity," they often assumed that meant I was employed by the government issuing driver's licenses, or that I helped people resolve credit card fraud.

However, neither were true. I formerly worked for Auth0, a company that manages digital identity. (I'm now a member of the Auth0 Ambassadors program, and a Google Developer Expert in SPPI: Security, Privacy, Payments, and Identity.)

Digital Identity

Digital identity refers to a set of attributes that define an individual user in the context of a function delivered by a particular application.

What does that mean?

Say you run an online shoe retail company. The digital identity of your app's users might be their credit card number, shipping address, and purchase history. Their digital identity is contextual to your app.

This leads us to...

Authentication

In a broad sense, authentication refers to the process of verifying that a user is who they say they are.

Once a system has been able to establish this, we come to...

Authorization

Authorization deals with granting or denying rights to access resources.

Standards

You may recall that I mentioned that auth is guided by clearly-defined standards. But where do these standards come from in the first place?

There are many different standards and organizations that govern how things work on the internet. Two bodies that are of particular interest to us in the context of authentication and authorization are the Internet Engineering Task Force (IETF) and the OpenID Foundation (OIDF).

IETF (Internet Engineering Task Force)

The IETF is a large, open, international community of network designers, operators, vendors, and researchers who are concerned with the evolution of internet architecture and the smooth operation of the internet.

Really, that's a fancy way to say that dedicated professionals cooperate to write technical documents that guide us in how things should be done on the internet.

OIDF (OpenID Foundation)

The OIDF is a non-profit, international organization of people and companies who are committed to enabling, promoting, and protecting OpenID technologies.

Now that we are aware of the specs and who writes them, let's circle back around to authorization and talk about:

OAuth 2.0

OAuth 2.0 is one of the most frequently mentioned specs when it comes to the web — and also one that is often mis-represented or misunderstood. How so?

OAuth is not an authentication spec. OAuth deals with delegated authorization. Remember that authentication is about verifying the identity of a user. Authorization deals with granting or denying access to resources. OAuth 2.0 grants access to applications on the behalf of users. (Don't worry, we'll get to the authentication part in a little bit!)

Before OAuth

To understand the purpose of OAuth, we need to do go back in time. OAuth 1.0 was established in December 2007. Before then, if we needed to access third party resources, it looked like this:

Let's say you used an app called HireMe123. HireMe123 wants to set up a calendar event (such as an interview appointment) on your (the user's) behalf. HireMe123 doesn't have its own calendar; it wants to use another service called MyCalApp to add events.

Once you were logged into HireMe123, HireMe123 would ask you for your MyCalApp login credentials. You would enter your MyCalApp username and password into HireMe123's site.

HireMe123 then used your MyCalApp login to gain access to MyCalApp's API, and could then create calendar events using your MyCalApp credentials.

Sharing Credentials is Bad!

This approach relied on sharing a user's personal credentials from one app with a completely different app, and this is not good. How so?

For one thing, HireMe123 had much less at stake in the protection of your MyCalApp login information. If HireMe123 didn't protect your MyCalApp credentials appropriately and they ended up stolen or breached, someone might write some nasty blog articles, but HireMe123 wouldn't face a catastrophe the way MyCalApp would.

HireMe123 also had way too much access to MyCalApp. HireMe123 had the same amount of access that you did, because they used your credentials to gain that access. That meant that HireMe123 could read all your calendar events, delete events, modify your calendar settings, etc.

Enter OAuth

This leads us to OAuth.

OAuth 2.0 is an open standard for performing delegated authorization. It's a specification that tells us how to grant third party access to APIs without exposing credentials.

Using OAuth, the user can now delegate HireMe123 to call MyCalApp on the user's behalf. MyCalApp can limit access to its API when called by third party clients without the risks of sharing login information or providing too much access. It does this using an:

Authorization Server

An authorization server is a set of endpoints to interact with the user and issue tokens. How does this help?

Let's revisit the situation with HireMe123 and MyCalApp, only now we have OAuth 2.0:

MyCalApp now has an authorization server. Let's assume that HireMe123 has already registered as a known client with MyCalApp, which means that MyCalApp's authorization server recognizes HireMe123 as an entity that may ask for access to its API.

Let's also assume you're already logged in with HireMe123 through whatever authentication HireMe123 has set up for itself. HireMe123 now wants to create events on your behalf.

HireMe123 sends an authorization request to MyCalApp's authorization server. In response, MyCalApp's authorization server prompts you — the user — to log in with MyCalApp (if you're not already logged in). You authenticate with MyCalApp.

The MyCalApp authorization server then prompts you for your consent to allow HireMe123 to access MyCalApp's APIs on your behalf. A prompt opens in the browser and specifically asks for your consent to let HireMe123 add calendar events (but no more than that).

If you say yes and grant your consent, then the MyCalApp authorization server will send an authorization code to HireMe123. This lets HireMe123 know that the MyCalApp user (you) did indeed agree to allow HireMe123 to add events using the user's (your) MyCalApp.

MyCalApp will then issue an access token to HireMe123. HireMe123 can use that access token to call the MyCalApp API within the scope of permissions that were accepted by you and create events for you using the MyCalApp API.

Nothing insidious is happening now! MyCalApp is asking the user to log in with MyCalApp. HireMe123 is not asking for the user's MyCalApp credentials. The issues with sharing credentials and too much access are no longer a problem.

What About Authentication?

At this point, I hope it's been made clear that OAuth is for delegated access. It doesn't cover authentication. At any point where authentication was involved in the processes we covered above, login was managed by whatever login process HireMe123 or MyCalApp had implemented at their own discretion. OAuth 2.0 didn't prescribe how this should be done: it only covered authorizing third party API access.

So why are authentication and OAuth so often mentioned in the same breath?

The Login Problem

The thing that happened after OAuth 2.0 established a way to access third party APIs was that apps also wanted to log users in with other accounts. Using our example: let's say HireMe123 wanted a MyCalApp user to be able to log into HireMe123 using their MyCalApp account, despite not having signed up for a HireMe123 account.

But as we mentioned above, OAuth 2.0 is for delegated access. It is not an authentication protocol. That didn't stop people from trying to use it like one though, and this presented problems.

Problems with Using Access Tokens for Authentication

If HireMe123 assumes successfully calling MyCalApp's API with an access token means the user can be considered authenticated with HireMe123, we run into problems because we have no way to verify the access token was issued to a particular individual.

For example:

Someone could have stolen the access token from a different user
The access token could have been obtained from another client (not HireMe123) and injected into HireMe123

This is called the confused deputy problem. HireMe123 doesn't know where this token came from or who it was issued for. If we recall: authentication is about verifying the user is who they say they are. HireMe123 can't know this from the fact that it can use this access token to access an API.

As mentioned, this didn't stop people from misusing access tokens and OAuth 2.0 for authentication anyway. It quickly became evident that formalization of authentication on top of OAuth 2.0 was necessary to allow logins with third party applications while keeping apps and their users safe.

OpenID Connect

This brings us to the specification called OpenID Connect, or OIDC. OIDC is a spec on top of OAuth 2.0 that says how to authenticate users. The OpenID Foundation (OIDF) is the steward of the OIDC standards.

OIDC is an identity layer for authenticating users with an authorization server. Remember that an authorization server issues tokens. Tokens are encoded pieces of data for transmitting information between parties (such as an authorization server, application, or resource API). In the case of OIDC and authentication, the authorization server issues ID tokens.

ID Tokens

ID tokens provide information about the authentication event and they identify the user. ID tokens are intended for the client. They're a fixed format that the client can parse and validate to extract identity information from the token and thereby authenticate the user.

OIDC declares a fixed format for ID tokens, which is:

JSON Web Token (JWT)

JSON Web Tokens, or JWT (sometimes pronounced "jot"), are composed of three URL-safe string segments concatenated with periods .

Header Segment

The first segment is the header segment. It might look something like this:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

The header segment is a JSON object containing a signing algorithm and token type. It is base64Url encoded (byte data represented as text that is URL and filename safe).

Decoded, it looks something like this:

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload Segment

The second segment is the payload segment. It might look like this:

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0

This is a JSON object containing data claims, which are statements about the user and the authentication event. For example:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

This is also base64Url encoded.

Crypto Segment

The final segment is the crypto segment, or signature. JWTs are signed so they can't be modified in transit. When an authorization server issues a token, it signs it using a key.

Don't worry if this seems confusing. The details of how this works shouldn't trouble you or keep you from effectively using an authorization server with token-based authentication. If you're interested in demystifying the terms, jargon, and details behind JWT signing, check out my article on Signing and Validating JSON Web Tokens (JWT) for Everyone.

Claims

Now that we know about the anatomy of a JWT, let's talk more about the claims, those statements from the Payload Segment. As per their moniker, ID tokens provide identity information, which is present in the claims.

Authentication Claims

We'll start with statements about the authentication event. Here are a few examples of these claims:

{
  "iss": "https://{you}.authz-server.com",
  "aud": "RxHBtq2HL6biPljKRLNByqehlKhN1nCx",
  "exp": 1570019636365,
   "iat": 1570016110289,
   "nonce": "3yAjXLPq8EPP0S",
  ...
}

Some of the required authentication claims in an ID token include:

iss (issuer): the issuer of the JWT, e.g., the authorization server
aud (audience): the intended recipient of the JWT; for ID tokens, this must be the client ID of the application receiving the token
exp (expiration time): expiration time; the ID token must not be accepted after this time
iat (issued at time): time at which the ID token was issued

A nonce binds the client's authorization request to the token it receives. The nonce is a cryptographically random string that the client creates and sends with an authorization request. The authorization server then places the nonce in the token that is sent back to the app. The app verifies that the nonce in the token matches the one sent with the authorization request. This way, the app can verify that the token came from the place it requested the token from in the first place.

Identity Claims

Claims also include statements about the end user. Here are a few examples of these claims:

{
  "sub": "google-oauth2|102582972157289381734",
  "name": "Kim Maida",
  "picture": "https://gravatar[...]",
  "twitter": "https://twitter.com/KimMaida",
  "email": "kim@gatsbyjs.com",
  ...
}

Some of the standard profile claims in an ID token include:

sub (subject): unique identifier for the user; required
email
email_verified
birthdate
etc.

We've now been through a crash-course on the important specifications (OAuth 2.0 and OpenID Connect) and it's time to see how to put our identity knowledge to work.

Authentication with ID Tokens

Let's see OIDC authentication in practice.

Note that this is a simplified diagram. There are a few different flows depending on your application architecture.

Our entities here are: the browser, an application running in the browser, and the authorization server. When a user wants to log in, the app sends an authorization request to the authorization server. The user's credentials are verified by the authorization server, and if everything checks out, the authorization server issues an ID token to the application.

The client application then decodes the ID token (which is a JWT) and verifies it. This includes validating the signature, and we must also verify the claims. Some examples of claim verification include:

issuer (iss): was this token issued by the expected authorization server?
audience (aud): is our app the target recipient of this token?
expiration (exp): is this token within a valid timeframe for use?
nonce (nonce): can we tie this token back to the authorization request our app made?

Once we've established the authenticity of the ID token, the user is authenticated. We also now have access to the identity claims and know who this user is.

Now the user is authenticated. It's time to interact with an API.

Accessing APIs with Access Tokens

We talked a bit about access tokens earlier, back when we were looking at how delegated access works with OAuth 2.0 and authorization servers. Let's look at some of the details of how that works, going back to our scenario with HireMe123 and MyCalApp.

Access Tokens

Access tokens are used for granting access to resources. With an access token issued by MyCalApp's authorization server, HireMe123 can access MyCalApp's API.

Unlike ID tokens, which OIDC declares as JSON Web Tokens, access tokens have no specific, defined format. They do not have to be (and aren't necessarily) JWT. However, many identity solutions use JWTs for access tokens because the format enables validation.

Access Tokens are Opaque to the Client

Access tokens are for the resource API and it is important that they are opaque to the client. Why?

Access tokens can change at any time. They should have short expiration times, so a user may frequently get new ones. They can also be re-issued to access different APIs or exercise different permissions. The client application should never contain code that relies on the contents of the access token. Code that does so would be brittle, and is almost guaranteed to break.

Accessing Resource APIs

Let's say we want to use an access token to call an API from a Single Page Application. What does this look like?

We've covered authentication above, so let's assume the user is logged into our JS app in the browser. The app sends an authorization request to the authorization server, requesting an access token to call an API.

Then when our app wants to interact with the API, we attach the access token to the request header, like so:

# HTTP request headers
Authorization: 'Bearer eyj[...]'

The authorized request is then sent to the API, which verifies the token using middleware. If everything checks out, then the API returns data (e.g., JSON) to the application running in the browser.

This is great, but there's something that may be occurring to you right about now. Earlier, we stated that OAuth solves problems with too much access. So how is that being addressed here?

Delegation with Scopes

How does the API know what level of access it should give to the application that's requesting use of its API? We do this with scopes.

Scopes "limit what an application can do on the behalf of a user." They cannot grant privileges the user doesn't already have. For example, if the MyCalApp user doesn't have permission to set up new MyCalApp enterprise accounts, scopes granted to HireMe123 won't ever allow the user to set up new enterprise accounts either.

Scopes delegate access control to the API or resource. The API is then responsible for combining incoming scopes with actual user privileges to make the appropriate access control decisions.

Let's walk through this with an example.

I'm using the HireMe123 app and HireMe123 wants to access the third party MyCalApp API to create events on my behalf. HireMe123 has already requested an access token for MyCalApp from MyCalApp's authorization server. This token has some important information in it, such as:

sub: (my MyCalApp user ID)
aud: MyCalAppAPI (audience stating this token is intended for the MyCalApp API)
scope: write:events (scope saying HireMe123 has permission to use the API to write events to my calendar)

HireMe123 sends a request to the MyCalApp API with the access token in its authorization header. When the MyCalApp API receives this request, it can see that the token contains a write:events scope.

But MyCalApp hosts calendar accounts for hundreds of thousands of users. In addition to looking at the scope in the token, MyCalApp's API middleware needs to check the sub subject identifier to make sure this request from HireMe123 is only able to exercise my privileges to create events with my MyCalApp account.

In the context of delegated authorization, scopes express what an application can do on the user's behalf. They're a subset of the user's total capabilities.

Granting Consent

Remember when the authorization server asked the HireMe123 user for their consent to allow HireMe123 to use the user's privileges to access MyCalApp?

That consent dialog might look something like this:

HireMe123 could ask for a variety of different scopes, for example:

write:events
read:events
read:settings
write:settings
...etc.

In general, we should avoid overloading scopes with user-specific privileges. Scopes are for delegated permissions for an application. However, it is possible to add different scopes to individual users if your authorization server provides Role-Based Access Control (RBAC).

With RBAC, you can set up user roles with specific permissions in your authorization server. Then when the authorization server issues access tokens, it can include a specific user's roles in their scopes.

Resources and What's Next?

We covered a lot of material, and it still wasn't anywhere close to everything. I do hope this was a helpful crash course in identity, authorization, and authentication.

I'm currently working on a few additional blog posts that go into further depth on JSON Web Tokens and authentication and authorization for JavaScript applications.

If you'd like to learn much, much more on these topics, here are some great resources for you to further your knowledge:

Learn More

The Learn Identity video series in the Auth0 docs is the lecture portion of the new hire identity training for engineers at Auth0, presented by Principal Architect Vittorio Bertocci. If you'd like to learn identity the way it’s done at Auth0, it's completely free and available to everyone (you don't even have to pay with a tweet or email!).

The OAuth 2.0 and OpenID Connect specifications are dense, but once you're familiar with the terminology and have foundational identity knowledge, they're helpful, informative, and become much more digestible. Check them out here: The OAuth 2.0 Authorization Framework and OpenID Connect Specifications.

JWT.io is a JSON Web Token resource that provides a debugger tool and directory of JWT signing/verification libraries for various technologies.

The OpenID Connect Playground is a debugger that lets developers explore and test OIDC calls and responses step-by-step.

Thank You!

If you'd like to chat, I'm available on Twitter at @KimMaida, and I also speak at conferences and events. I hope to see you sometime, and thank you so much for reading!

Authorization and Authentication For Everyone

Kim Maida — Sun, 19 Jul 2020 17:45:09 +0000

This post is meant to be read from beginning to end. We'll build on top of each concept to layer knowledge when it makes sense to introduce new topics. Please keep that in mind if you're jumping around in the content.

Introduction
OAuth 2.0
The Login Problem
OpenID Connect
Authentication with ID Tokens
Accessing APIs with Access Tokens
Delegation with Scopes
Resources and What's Next?

Introduction

When I told family or friends that I "work in identity," they often assumed that meant I was employed by the government issuing driver's licenses, or that I helped people resolve credit card fraud.

Digital Identity

Digital identity refers to a set of attributes that define an individual user in the context of a function delivered by a particular application.

What does that mean?

This leads us to...

Authentication

In a broad sense, authentication refers to the process of verifying that a user is who they say they are.

Once a system has been able to establish this, we come to...

Authorization

Authorization deals with granting or denying rights to access resources.

Standards

You may recall that I mentioned that auth is guided by clearly-defined standards. But where do these standards come from in the first place?

IETF (Internet Engineering Task Force)

Really, that's a fancy way to say that dedicated professionals cooperate to write technical documents that guide us in how things should be done on the internet.

OIDF (OpenID Foundation)

The OIDF is a non-profit, international organization of people and companies who are committed to enabling, promoting, and protecting OpenID technologies.

Now that we are aware of the specs and who writes them, let's circle back around to authorization and talk about:

OAuth 2.0

OAuth 2.0 is one of the most frequently mentioned specs when it comes to the web — and also one that is often mis-represented or misunderstood. How so?

Before OAuth

To understand the purpose of OAuth, we need to do go back in time. OAuth 1.0 was established in December 2007. Before then, if we needed to access third party resources, it looked like this:

Once you were logged into HireMe123, HireMe123 would ask you for your MyCalApp login credentials. You would enter your MyCalApp username and password into HireMe123's site.

HireMe123 then used your MyCalApp login to gain access to MyCalApp's API, and could then create calendar events using your MyCalApp credentials.

Sharing Credentials is Bad!

This approach relied on sharing a user's personal credentials from one app with a completely different app, and this is not good. How so?

Enter OAuth

This leads us to OAuth.

OAuth 2.0 is an open standard for performing delegated authorization. It's a specification that tells us how to grant third party access to APIs without exposing credentials.

Authorization Server

An authorization server is a set of endpoints to interact with the user and issue tokens. How does this help?

Let's revisit the situation with HireMe123 and MyCalApp, only now we have OAuth 2.0:

Let's also assume you're already logged in with HireMe123 through whatever authentication HireMe123 has set up for itself. HireMe123 now wants to create events on your behalf.

What About Authentication?

So why are authentication and OAuth so often mentioned in the same breath?

The Login Problem

But as we mentioned above, OAuth 2.0 is for delegated access. It is not an authentication protocol. That didn't stop people from trying to use it like one though, and this presented problems.

Problems with Using Access Tokens for Authentication

For example:

Someone could have stolen the access token from a different user
The access token could have been obtained from another client (not HireMe123) and injected into HireMe123

OpenID Connect

ID Tokens

OIDC declares a fixed format for ID tokens, which is:

JSON Web Token (JWT)

JSON Web Tokens, or JWT (sometimes pronounced "jot"), are composed of three URL-safe string segments concatenated with periods .

Header Segment

The first segment is the header segment. It might look something like this:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

The header segment is a JSON object containing a signing algorithm and token type. It is base64Url encoded (byte data represented as text that is URL and filename safe).

Decoded, it looks something like this:

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload Segment

The second segment is the payload segment. It might look like this:

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0

This is a JSON object containing data claims, which are statements about the user and the authentication event. For example:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

This is also base64Url encoded.

Crypto Segment

The final segment is the crypto segment, or signature. JWTs are signed so they can't be modified in transit. When an authorization server issues a token, it signs it using a key.

Don't worry if this seems confusing. The details of how this works shouldn't trouble you or keep you from effectively using an authorization server with token-based authentication. If you're interested in demystifying the terms, jargon, and details behind JWT signing, check out my article on Signing and Validating JSON Web Tokens (JWT) for Everyone.

Claims

Authentication Claims

We'll start with statements about the authentication event. Here are a few examples of these claims:

{
  "iss": "https://{you}.authz-server.com",
  "aud": "RxHBtq2HL6biPljKRLNByqehlKhN1nCx",
  "exp": 1570019636365,
   "iat": 1570016110289,
   "nonce": "3yAjXLPq8EPP0S",
  ...
}

Some of the required authentication claims in an ID token include:

iss (issuer): the issuer of the JWT, e.g., the authorization server
aud (audience): the intended recipient of the JWT; for ID tokens, this must be the client ID of the application receiving the token
exp (expiration time): expiration time; the ID token must not be accepted after this time
iat (issued at time): time at which the ID token was issued

Identity Claims

Claims also include statements about the end user. Here are a few examples of these claims:

{
  "sub": "google-oauth2|102582972157289381734",
  "name": "Kim Maida",
  "picture": "https://gravatar[...]",
  "twitter": "https://twitter.com/KimMaida",
  "email": "kim@gatsbyjs.com",
  ...
}

Some of the standard profile claims in an ID token include:

sub (subject): unique identifier for the user; required
email
email_verified
birthdate
etc.

We've now been through a crash-course on the important specifications (OAuth 2.0 and OpenID Connect) and it's time to see how to put our identity knowledge to work.

Authentication with ID Tokens

Let's see OIDC authentication in practice.

Note that this is a simplified diagram. There are a few different flows depending on your application architecture.

issuer (iss): was this token issued by the expected authorization server?
audience (aud): is our app the target recipient of this token?
expiration (exp): is this token within a valid timeframe for use?
nonce (nonce): can we tie this token back to the authorization request our app made?

Once we've established the authenticity of the ID token, the user is authenticated. We also now have access to the identity claims and know who this user is.

Now the user is authenticated. It's time to interact with an API.

Accessing APIs with Access Tokens

Access Tokens

Access tokens are used for granting access to resources. With an access token issued by MyCalApp's authorization server, HireMe123 can access MyCalApp's API.

Access Tokens are Opaque to the Client

Access tokens are for the resource API and it is important that they are opaque to the client. Why?

Accessing Resource APIs

Let's say we want to use an access token to call an API from a Single Page Application. What does this look like?

Then when our app wants to interact with the API, we attach the access token to the request header, like so:

# HTTP request headers
Authorization: 'Bearer eyj[...]'

The authorized request is then sent to the API, which verifies the token using middleware. If everything checks out, then the API returns data (e.g., JSON) to the application running in the browser.

This is great, but there's something that may be occurring to you right about now. Earlier, we stated that OAuth solves problems with too much access. So how is that being addressed here?

Delegation with Scopes

How does the API know what level of access it should give to the application that's requesting use of its API? We do this with scopes.

Scopes delegate access control to the API or resource. The API is then responsible for combining incoming scopes with actual user privileges to make the appropriate access control decisions.

Let's walk through this with an example.

sub: (my MyCalApp user ID)
aud: MyCalAppAPI (audience stating this token is intended for the MyCalApp API)
scope: write:events (scope saying HireMe123 has permission to use the API to write events to my calendar)

In the context of delegated authorization, scopes express what an application can do on the user's behalf. They're a subset of the user's total capabilities.

Granting Consent

Remember when the authorization server asked the HireMe123 user for their consent to allow HireMe123 to use the user's privileges to access MyCalApp?

That consent dialog might look something like this:

HireMe123 could ask for a variety of different scopes, for example:

write:events
read:events
read:settings
write:settings
...etc.

With RBAC, you can set up user roles with specific permissions in your authorization server. Then when the authorization server issues access tokens, it can include a specific user's roles in their scopes.

Resources and What's Next?

We covered a lot of material, and it still wasn't anywhere close to everything. I do hope this was a helpful crash course in identity, authorization, and authentication.

To further demystify JWT, read my article Signing and Validating JSON Web Tokens for Everyone.

If you'd like to learn much, much more on these topics, here are some great resources for you to further your knowledge:

Learn More

JWT.io is a JSON Web Token resource that provides a debugger tool and directory of JWT signing/verification libraries for various technologies.

The OpenID Connect Playground is a debugger that lets developers explore and test OIDC calls and responses step-by-step.

Thank You!

If you'd like to chat, I'm available on Twitter at @KimMaida, and I also speak at conferences and events — at least, I did before COVID-19. I have delivered this content in presentation format, and hope to do so again once travel and in-person events resume. I hope to see you sometime, and thank you so much for reading!

Hello, Rota! A Slackbot for Rotation Management

Kim Maida — Sun, 10 May 2020 17:57:17 +0000

Improving Remote Work Through Internal Tooling

Ever since I started working fully remote 4-ish years ago, I've been interested in the tools and automation that makes peoples' lives easier in tech remote work culture.

I'd like to give a shout-out to my former employer here: Auth0 pioneered my appreciation for automation tools in Slack and their customizability, flexibility, and power for making remote communication and workflows appear to just work, automagically.

In fact, prior to my arrival at the company, Auth0 had built a @concierge Slackbot that was so integrated into the company culture that I thought it was a core feature of Slack itself. It wasn't until I'd moved onto my next role that I realized @concierge had been built custom for Auth0 by Auth0 dev tools engineers. The Developer Tools team at Auth0 builds solutions and toolchains for the company, internally, to vastly improve productivity and workflows within the organization.

As I moved on to my next fully remote role at Gatsby, I found areas where I could — ostensibly — meaningfully contribute to the internal tooling ecosystem myself. And indeed, if I ever took on a role that was not Developer Relations in the future, an internal dev tools team is the first place I could see myself being very happy.

Rota: What is the Task at Hand?

At many tech companies, teams have a need for regularly staffed rotations. Rota exists to help manage rotations.

For example, perhaps a content team needs blog post drafts to be reviewed each week. It doesn't make sense for one person to be responsible for this all the time, so instead the responsibility is shared among team members with one person reviewing each week. Perhaps an OSS organization has issues that need triage or pull requests that need review; these tasks also rotate amongst team members.

Maybe someone outside the rotation needs to contact whoever is currently on-call for a rotated task, but they don't know at any given time who to reach out to. They could go look up names on a list or a calendar, or they could blast out a message to the entire Slack channel, or use a @usergroup that notifies everyone on the team, but this is unscalable and highly disruptive, especially as a company grows.

Rota In Action

Using Rota, we can set up new rotations, staff them, assign people to be on call, rotate the assignment, and send messages to whoever is currently staffing any given rotation.

You can create, name, and describe new rotations:

You can then assign a "staff list" (usernames of everyone who should take part in the rotation, in assigning order):

Then you can assign someone to the rotation either by username, or by assigning the next user on staff. When assigning the rotation, you can also pass an optional handoff message:

The handoff message is then delivered to the new assignee in a direct message from @rota:

If anyone needs to contact the person who is on-call for any existing rotation, they can easily do so without needing to know who is currently assigned.

The assigned user then receives a DM from @rota notifying them of the message that needs their attention:

Rota Commands

At the time of this writing, Rota supports the following commands:

@rota new "[new-rotation-name]" [description] creates a new rotation; rotation names can contain only lowercase letters, numbers, and hyphens. Technically the description is optional, but everyone will benefit if you provide one.
@rota delete "[rotation]" deletes the rotation completely (use with caution!).
@rota "[rotation]" description [new description] updates the description for a rotation.
@rota "[rotation]" staff [@user1 @user2 @user3] adds staff to a rotation; a space-separated list of usernames is expected as a parameter with usernames in the order of desired rotation (rotations with a staff list can be assigned using assign next).
@rota "[rotation]" reset staff clears a rotation's staff list (use with caution!).
@rota "[rotation]" assign [@user] [optional handoff message] assigns someone to the rotation and, optionally, sends a DM to them with handoff information.
@rota "[rotation]" assign next [optional handoff message] assigns the next person in the staff list to a rotation and, optionally, sends a DM to them with handoff information.
@rota "[rotation]" unassign removes the current user assignment for a rotation.
@rota "[rotation]" who reports the name of a rotation's assigned user.
@rota "[rotation]" about displays the rotation's description and on-call user publicly, and displays the staff list only to the user who issued the commend (this is to prevent excessive notifications for everyone on staff).
@rota "[rotation]" [message] sends a direct message to the on-call user for the rotation, notifying them that your message needs attention.
@rota list displays a list of all currently known rotations.
@rota help shows how to use the bot.

Note: More commands may be added as development evolves and progresses over time. Visit the rota-slackbot GitHub repo for any updates.

Want to Use Rota?

Rota is free and open source. Its source code is available on GitHub at kmaida/rota-slackbot, along with instructions for setting the app up in your own Slack workspace. Rota's README lists the commands that Rota supports, as well as tips for using Rota with other Slack features (like reminders) and third party apps (like Gator, for scheduling messages). Rota was developed for internal team use at Gatsby, so it has been tested for that purpose and its continued development will focus on internal tooling benefits.

Important Technical Details

Because Rota is free, it is not distributed in a way that allows you to go to the Slack app directory and install it from the marketplace. It needs to have settings for your workspace, needs to have a database specific to your workspace, and also needs to be deployed to your hosting. Detailed instructions for all of the above are provided in the repo's README.

If I were to distribute Rota publicly, it would not be possible for the app to remain free. Public distribution would require provisioning data stores for each workspace it is installed in and would significantly increase hosting costs and maintenance overhead.

Maintenance and Contribution

I will be actively maintaining rota-slackbot at Gatsby during my tenure, as long as the bot is being actively used internally. If you'd like to aid in development work with Rota, please fork it on GitHub. To set expectations: because Rota is purpose-built for a specific organization, feature requests will be addressed if they have significant value add. Community contributions to the codebase are welcome.

Thank You!

I had a great time building Rota, and my hope is that it helps internally at my organization, but also that it helps others who share similar challenges in their teams and companies elsewhere. 🎉

The Developer Relations Explainer

Kim Maida — Sun, 10 May 2020 04:07:17 +0000

The goal of this article is to provide an explainer sharing my thoughts on what Developer Relations is, what its core tenets are, and what important questions DevRel works to provide answers to.

The Four Houses of Developer Relations

Developer Relations, or "DevRel," is a field in technology whose practitioners focus on improving and nurturing the relationship that an entity (be it a commercial product company, an open source organization, a platform, or other type of technology offering) shares with its developer users.

There are many different roles within Developer Relations. These include titles like Developer Advocate, Developer Evangelist, Community Manager, Developer Programs Manager, and more. There are several areas of DevRel which I see as equally important "houses" that make up the greater Developer Relations ecosystem. In order for a Developer Relations team to be successful and productive, all four of the following houses should play a part in the greater whole.

Developer Advocacy

Developer advocacy focuses on championing the developer users and representing their interests and input both externally and internally.

The job titles "Developer Advocate" and "Developer Evangelist" are often used interchangeably in the industry. In terms of practice, advocacy and evangelism are not identical — and both are important aspects of Developer Relations. In fact, most DevRel folks who hold a title of either "Developer Advocate" or "Developer Evangelist" actually do both advocacy and evangelism in their day-to-day job.

"A Developer Advocate’s job is to cultivate trust from both the product and the developers they represent by reaching across the table, listening, trying things for themselves, and understanding context and roadmaps." –Ashley McNamara

Developer advocacy is centered around advocating on behalf of the developer user to the company. Some of the primary traits necessary for practicing effective developer advocacy are user empathy and emotional intelligence. When it comes to products whose primary users are developers, being able to understand the developer's point of view and communicate user feedback effectively to make change in the product is key.

Developer advocacy is about taking on the lion's share of the responsibility to reach out to the developer user community, help bring forward appropriate messaging, training and resources, and elevate the voices of the community both publicly and also inside the company.

Developer Evangelism

Etymologically, the word "evangelism" arises from the Greek "εὐαγγελίζεσθαι" (euangelizesthai): to preach the gospel / to spread the good word.

"A developer evangelist is a spokesperson, mediator and translator between a company and both its technical staff and outside developers." –Christian Heilmann

Developer evangelism centers around representing an organization and demonstrating what benefits the organization's offerings have for developers. How does the product solve problems and help developers get the job done? They speak, engage, and instruct on behalf of the company to share how the products and services can better help developers to accomplish things.

Developer Experience

Developer Experience is about cultivating, enhancing, and supporting a delightful experience for the developers who are using a software product, effectively using knowledge, research, and creativity to solve challenges and make improvements.

"Developer Experience (DX) is the equivalent to User Experience (UX) when the user of the software or system is a developer." –Sam Jarman

DX can mean many things at different companies. For an open source organization, a significant portion of the developer experience may focus on OSS contributors in the community. How are they supported when they submit issues and pull requests? How can they get access to resources and guidance to make meaningful contributions? DX also includes enablement of a developer's learning journey with a product. Are there helpful materials and tutorials available to pave their path to success with the product?

DX can also include:

Tools and dashboard interfaces
Documentation
Tutorials and demos
Onboarding experiences
Avenues for getting developer support
Ways for developers to provide product feedback
Transparency around public product roadmaps

...and much more.

Community

Community refers to the current users and also potential users of a software or technology. This includes everyone from students and people just learning to code to senior architects to internal employees. Anyone who uses a technology, talks about it, advocates for it, provides feedback on it, etc. is a member of that technology or organization's developer community.

"Community includes a company’s employees (at the very least, the relevant product division), current customers, as well as prospects, and anyone who could in the future be interested in using the product… which is a fairly broad group of people." –Mary Thengvall

Community is about bolstering, nurturing, and cultivating the developer community with compassion and governing its interactions fairly.

Developer Relations Asks These Questions

When working in Developer Relations, we should be seeking to provide answers to two variants of three questions:

1. 💁🏽‍♀️ How can we help?

How can we help the developer community?

We do this in many ways, and are always on the lookout for more ways to do so. Some examples:

Creating content resources (e.g., giving talks at events, writing blog posts, producing videos, courses, livestreams, etc.)
Answering questions (e.g., staffing forums, Twitter and social media, responding to direct outreach, reaching out to the community to find out what questions developers have, etc.)
Supporting developers who wish to provide their own resources (e.g., sharing important messaging, offering content creator training, supporting meetups and events run by the community, connecting content creators with internal subject matter experts, holding office hours, offering paired programming sessions, etc.)
Requesting, receiving, and aggregating feedback from the community and championing that feedback within the company to improve the product

How can we help our organization?

The same question should be asked from the perspective of the organization we work for. Ways we can use our position in Developer Relations to help our org include (but are not limited to):

Establishing developer feedback channels and managing communication to ensure that feedback is appropriately delivered and acted upon by teams within the org (such as Product, Engineering, Documentation, Design, etc.)
Supporting feature launches with community engagement, content, and proactive anticipation of community responses
Providing internal resources and opportunities for fellow employees to get involved with employee advocacy

2. ⚔️ What challenges can we resolve?

What challenges can we resolve for the developer community?

Developer Relations teams should also be strongly focused on problem-solving, identifying challenges, and crafting sustainable solutions. For example:

Do developers have a clear path and good experience contributing to open source?
Are developers confused about the way features of the product work, and can resources be provided to clarify?
Is community feedback received and followed up on appropriately and do community members know their input is valued?
Are there ample resources for developers with all different levels of experience to work productively with the software or platform?

What challenges can we resolve for the organization?

Within an organization, there are many ways Developer Relations can create and improve processes, set up new workflows, and collaborate cross-functionally across teams and departments, such as:

Are teams in the company communicating effectively with each other to ensure that developers receive the best experience possible? (E.g., is marketing aligned with product and engineering?)
If the organization has a focus on open source, how are issues and PRs triaged efficiently and sustainably without overloading any single team?
Is there strong messaging around the organization's goals and purpose, and how can this messaging be amplified to and by the community?
Do teams within the organization feel confident that they are connected to and aware of important feedback and sentiments of developers who use the product?

3. 🧰 What can we build?

What can we build for the developer community?

Developer Relations also has a responsibility to create and build. In doing so, we provide platforms to elevate community voices and to offer opportunities to developers. We can build things like:

Ambassador programs to mentor, support, and grow community members who are interested in spreading the word about a technology offering
Community platforms such as forums, real-time chats, user mailing lists, and more
Demos, samples, tutorials, guides, showcases, and more

What can we build for the organization?

Within the organization, we can also build internal tooling, such as:

Programs for beta testing, early access, and community advisory groups to bring actionable and early feedback into the company
Workflows and dashboards to track community sentiment and growth
Apps and automated tooling to manage community programs, incentives, swag, event support requests, etc.
Bots and API integrations to support moderation, contributor assistance, metrics, frequently asked questions, and more

It's About Making a Difference

Developer Relations team members work on a myriad of different problems and tasks, and face unique challenges to craft creative and remarkable solutions. DevRel is exciting because it's different across every organization: it is so intrinsically tied to that organization's technology, audience, goals, and area of focus. You will never do the same DevRel job twice at two different companies — though the underlying traits and overall thematic elements will remain consistent. Much of this boils down to answering one question (albeit with lots of variation and nuance): How can I help?

Do You Want a Job in Developer Relations?

If you're interested in working in DevRel, I would encourage you to do it because you want to help — not solely for personal glory or to become industry-famous. A great DevRel team member is a champion for the developer, the organization, the community, and the user experience. Compassion, kindness, and empathy are truly valuable skills for anyone interested in Developer Relations. If you don't come at it with a deep caring for the success of others, the early sense of fulfillment from fame-and-glory will fizzle out quickly.

As a developer marketing leader, my job is to design and engineer the vehicle that drives the voices of others forward. I am not the racecar driver who crosses the finish line and is rewarded with a wreath and a trophy; I'm the unseen engineer who makes sure the racecar has been built to operate in the most performant and high quality manner that it can. Developer Advocates often get to build their personal brand in a big way; but leading DevRel frequently means being comfortable and feeling fulfilled from behind the scenes.

I'd love to share thoughts and tips on how to get started landing a job in DevRel, but that's a blog post for another day. 🙂

DEV Community: Kim Maida

I Built and Authorized a Planning Agent with MCP and Keycard

What I Built: "Plan My Today"

Architecture Overview

The Aggregation Tool: list-all-tasks-today

LLM in the backend

The Auth Challenge and How Keycard Solves It

The Solution: Keycard as the control plane for Todaygent

Token-Mediating Backend Architecture

RFC 8693 Token Exchange: The Key Mechanism

Ephemeral Tokens and Performance

Visibility: What Todaygent Actually Did

The Audit Log

Sessions and Grants

Why This Matters for Agent-Native Apps

The AI Agent: Todaygent

Personality and Philosophy

The Agentic Loop

What I Ask It

Importance of the System Prompt

What's Next

The Day Agents Achieved Real Authority, and What It Means for Trust

Claude Code got Remote Control

Anthropic shipped enterprise agent plugins

Docusign brought agreement workflows to Cowork

Vouched launched Agent Checkpoint

The AAIF is growing fast

What does it all mean?

OAuth 2.0 Security Best Practices for Developers

Introduction

Target audience

Assumed knowledge

Terminology

Why do we need new best practices for OAuth 2.0?

1. Protect redirect flows

Do not redirect to URIs obtained from a query parameter

Use exact string matching when configuring allowed redirect URIs

Protect against Cross Site Request Forgery (CSRF) attacks

Validate token issuer when using more than one authorization server

Authorization Code Grant

Public clients must use Proof Key for Code Exchange

Do not use implicit grant

2. Prevent token replay

Use sender constrained access tokens

Public client refresh tokens must be sender constrained or rotated

3. Access tokens should grant the minimum privileges needed

4. Don’t use user credentials to obtain access tokens

5. Authorization servers should enforce client authentication

6. Other recommendations

Attacker model, attacks, and mitigations

Conclusion

How to Drive Developer Growth and Engagement

Inspire

Educate

Activate

Engage

Empower

People

Cross-Functional Developer Growth and Engagement

Product

Partnerships

Developer Marketing

Additional Cross-Functional Opportunities

How to Measure Developer Growth and Engagement

Trusted Metrics

Insight Metrics

Key Performance Indicators

Scalable Developer Growth and Engagement

Company Developer Engagement and Advocacy

Developer Community

Sustainable Developer Empowerment

How to Connect With Your Developer Audience

What Does Your Developer Audience Want?

Developer Relations is About Building Great Relationships

1. We Act With Integrity and Empathy

Solve Problems, Have Conversations, Be Open to Criticism

Different Strokes for Different Folks

Keep Promises

2. Build Trust and Respect

3. Inspire Loyalty and Confidence

The Aggregation Tool: `list-all-tasks-today`