Dev.to Security πŸ” Cybersecurity πŸ‘ 0 πŸ“– 4 min read

OpenAPI OAuth2 Security Flows

Quick answer: OpenAPI describes OAuth2 in a reusable security scheme under components, then applies it with a security requirement. The scheme lists one or more of the four flows, authorization code, client credentials,

Quick answer: OpenAPI describes OAuth2 in a reusable security scheme under components, then applies it with a security requirement. The scheme lists one or more of the four flows, authorization code, client credentials, password, and implicit, each with its endpoint URLs and scopes. Defining the scheme does not protect anything by itself; an operation only requires OAuth2 once a security entry references it, and the spec documents the contract rather than issuing tokens.

Where OAuth2 fits in the spec

OAuth2 lives in two places. The first is components/securitySchemes, where you declare a reusable scheme with type: oauth2 and a flows object describing how a token is obtained. The second is the security array, at the root or on an operation, which references that scheme and states the scopes the caller needs. Keeping definition and application separate lets one scheme protect many operations without repeating endpoint URLs.

A scheme that sits in components but is never referenced has no effect. The document may show an OAuth2 panel, yet every operation stays open because no security requirement names it. So a spec can look protected in the editor but behave differently when requests are sent.

The four flows and when to use each

Each flow obtains a token differently, and they do not all take the same endpoint fields.

Flow Endpoints Typical use
Authorization code authorizationUrl and tokenUrl Apps with a backend and a logged-in user
Client credentials tokenUrl only Server-to-server calls with no user
Password tokenUrl only Trusted first-party apps, discouraged
Implicit authorizationUrl only Legacy browser apps, largely replaced

Authorization code is the default for user-facing apps and pairs well with PKCE for public clients. Client credentials suit machine-to-machine work where the service is the identity. The password flow asks users to hand credentials directly to the app and should be reserved for trusted first-party clients. Implicit was built for browser apps without a backend, now superseded by authorization code with PKCE, so new specs rarely need it.

How scopes are declared and applied

Inside each flow, the scopes object maps every scope name to a short description. Scopes are the unit of permission, so names such as orders:read and orders:write should be specific and consistent across the flows that expose them. A typo creates a second scope that looks almost identical and is hard to spot in a long list.

When a security requirement references the scheme, it lists the scopes that operation needs. Requiring only the scopes an endpoint uses follows least privilege, and an empty array means the caller must present a token but no particular scope. Scopes named in a security entry must already exist in the flow, or the spec references a permission that was never defined.

Applying a scheme with security

A root-level security requirement sets the default for every operation, and an operation can override it with its own security array. Within one requirement object, listing several schemes means all are required together, while separate array entries offer alternatives where any one satisfies it. Getting this AND versus OR distinction wrong either locks an operation behind tokens it does not need or leaves it reachable through a weaker scheme.

The OpenAPI guide keeps this in one place: the scheme describes how authorization works, and security declares where it is enforced. After wiring the requirement, send a real request with a token in Powerduck and confirm the protected result, then repeat it without a token to check the 401 path rather than assume the panel is enough.

Common mistakes

The first is defining the scheme and forgetting the security requirement, so no operation is protected. The second is filling the wrong endpoint fields, such as adding an authorization URL to client credentials, which only exchanges at the token endpoint. The third is using a scope in security that the flow never declares, which validation tools flag but hand-written specs miss.

A fourth is treating the spec as a token issuer. OpenAPI documents where the endpoints are and what scopes mean, but the application or gateway still performs the real handshake and validation. A rendered OAuth2 section describes the contract, not proof that a request without the right token will be rejected.

Frequently asked questions

Do I have to declare all four flows? No, list only the flows your server supports. Most APIs expose one or two, and unused flows mislead callers.

What is the difference between the scheme and security? The scheme defines the OAuth2 endpoints and scopes, while security references it and states which scopes an operation requires.

Can I use OAuth2 for service-to-service calls? Yes, the client credentials flow is designed for that, exchanging the service's own identity at the token endpoint without a user.

Does OpenAPI obtain tokens for me? No, it documents the endpoints and requirements. The client or gateway handles the actual token request and validation.

The bottom line

Declare OAuth2 once as a reusable scheme with the specific flows your server supports, then reference it through a security requirement naming the scopes each operation needs. Choose authorization code for user-facing apps, client credentials for machine-to-machine calls, and avoid password and implicit in new work. A defined scheme protects nothing until referenced, and the spec describes the contract while real token handling belongs to the application and gateway.

πŸ“° Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.