OAuth

What OAuth is and which problem it solves

Before OAuth, the usual way to give a third-party application access to an account was to hand over the username and password. The third-party application thus got full access, could store the password and could not be locked out again in a targeted way. OAuth replaces this pattern with delegation: the user consents to a specific access at the service that holds the data, and the third-party application receives a token for it.

The token is bound to a scope, such as "read orders", and expires after a short time. The user can revoke the authorisation at any time without changing their password. For operators of shops, ERP systems and customer portals, OAuth is therefore the standard basis as soon as external applications, apps or AI agents are connected to a REST API.

Important for classification: OAuth governs authorisation, the question "What may this client do?". It does not answer the question "Who is this user?". That is what OpenID Connect, which builds on OAuth, is for. More on this below.

The four roles in the OAuth model

RFC 6749 defines four roles that occur in every OAuth flow. If you keep them clearly apart, you will also understand the grant types and the security rules without effort.

Authorization server and resource server can be the same software but do not have to be. In larger architectures a central identity provider handles token issuance, while dozens of microservices only verify the tokens as resource servers.

Access token, refresh token and scope

The access token is the key that the client sends with every request in the HTTP header Authorization: Bearer …. It is deliberately short-lived. The refresh token serves exclusively to obtain a new access token from the authorization server without involving the user again. The scope describes which rights the token covers. The principle of least privilege applies here: a client should only request the scopes it really needs.

OAuth 2.0 and OAuth 2.1: what changes

OAuth 2.0 was published in 2012 as RFC 6749. In the years that followed, numerous additions were made, including PKCE (RFC 7636), the best-practice recommendations for native apps (RFC 8252) and the Security Best Current Practice. Anyone who wanted to implement the protocol correctly had to read these documents together.

OAuth 2.1 is an IETF draft (draft-ietf-oauth-v2-1) that delivers exactly this consolidation. It introduces no new concepts but removes insecure variants and makes proven safeguards mandatory. The most important changes compared with OAuth 2.0:

• PKCE is mandatory for all clients in the authorization code flow, not just for mobile or public clients.
• Redirect URIs must be checked by exact string comparison; partial or pattern matching is no longer allowed.
• The implicit grant (response_type=token) has been removed.
• The resource owner password credentials grant has been removed.
• Bearer tokens may no longer be transmitted as URL query parameters.
• Refresh tokens for public clients must either be sender-constrained or rotated on every use.

In practice this means: if you build a new OAuth system or implement an integration today, you should work directly according to the rules of OAuth 2.1. Every modern authorization server supports them, and protocols such as MCP already require them.

Grant types: which flows exist

A grant describes the route by which the client obtains its access token. At its core, OAuth 2.1 knows two flows for everyday use, plus the refresh token grant and extensions such as the device authorization grant for devices without a browser.

Authorization code flow with PKCE

This is the standard flow as soon as a person is involved. The client redirects the user via the browser to the authorization server. There the user signs in and confirms the access. The authorization server sends the browser back to the registered redirect URI with a short-lived authorization code. The client then exchanges this code for the access token via a direct server call.

PKCE (Proof Key for Code Exchange, pronounced "pixie") protects the exchange of the code. Before starting, the client generates a random code_verifier, creates a SHA-256 hash from it (code_challenge, method S256) and sends only the hash with the authorisation request. In the token request it presents the original verifier. An attacker who intercepts the authorization code cannot redeem it without the verifier.

GET /authorize?response_type=code
  &client_id=shop-frontend
  &redirect_uri=https://shop.example/callback
  &scope=orders:read
  &state=af0ifjsldkj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

POST /token
grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://shop.example/callback
&client_id=shop-frontend
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

The state parameter binds the response to the original request and protects against cross-site request forgery. The client must check it on the return and discard responses with a different value.

Client credentials grant

If no user is involved, for example in a nightly synchronisation between ERP and shop, the client authenticates itself directly at the token endpoint with its own ID and secret. The issued token then represents the application itself, not a person. This grant is only suitable for confidential clients, servers that can keep a secret safe. A client secret has no place in a single-page app or a mobile app.

POST /token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=products:write

Removed grants: implicit and password

The implicit grant returned the access token directly to the browser in the URL fragment. The token therefore ended up in browser history, referrer headers and logs. Since single-page apps can now use the authorization code flow with PKCE, there is no longer any reason for this flow.

The password grant let the client collect the username and password and exchange them for a token. This undermines the basic idea of OAuth, because the client sees the password. In addition, multi-factor authentication and single sign-on do not work in this model. OAuth 2.1 has therefore removed both grants. Existing systems that still use them should be migrated.

Public and confidential clients

OAuth distinguishes clients by whether they can keep a secret safe. A back-end service is a confidential client. A browser app, a mobile app or a CLI tool on a user's computer is a public client. Stricter rules apply to public clients: PKCE is mandatory, refresh tokens must be rotated, and redirect URIs should be restricted to localhost or HTTPS.

OAuth vs. OpenID Connect: authorisation and authentication

OAuth and OpenID Connect (OIDC) are often confused because they use the same flow. The difference lies in the purpose. OAuth delivers an access token that describes what a client may access. It says nothing binding about who has signed in. An access token is intended for the resource server and is usually opaque to the client.

OpenID Connect is an identity layer on top of OAuth 2.0. It adds an ID token, a signed JSON Web Token with details of the user's identity (subject, issuer, expiry time, optionally name and email). The ID token is intended for the client and answers the question "Who is this?". On top of this come a standardised UserInfo endpoint and discovery via /.well-known/openid-configuration.

As a rule of thumb: if your application is supposed to sign a user in, you need OpenID Connect. If your application is supposed to access an API on behalf of a user or system, you need OAuth. In practice the two usually run together in one request by additionally requesting the openid scope.

Real-world example: "Sign in with Google" and the Shopware Admin API

With the "Sign in with Google" button, Google is the authorization server and at the same time the OpenID provider. Your shop is the client. The user is redirected to Google, signs in there and sees which data the shop is requesting, for example email and profile name. After consent, the shop exchanges the authorization code server-side for an ID token and access token. The shop never sees the password of the Google account.

A second example from e-commerce is the Admin API of Shopware 6. It uses OAuth 2.0 for all access. For system integrations you create an integration in the administration under "Settings, System, Integrations". Shopware generates an access key ID and a secret access key, which are used as client_id and client_secret in the client credentials grant. The token endpoint is /api/oauth/token; the access token is valid for one hour.

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "SWIAXXXXXXXXXXXXXXXXXXXXXX",
  "client_secret": "…"
}

The Shopware administration itself, on the other hand, signs users in with username and password at the same token endpoint, via the password grant with refresh token. This route is not intended for new integrations from outside; here the standard is an integration with client credentials and a role restricted to the necessary rights.

OAuth for AI agents and MCP

With AI agents, OAuth takes on a new role. An agent that checks orders or reads CRM data on behalf of an employee needs exactly what OAuth offers: delegated, limited and revocable access rights. The Model Context Protocol (MCP) has therefore firmly incorporated OAuth into its specification.

The MCP specification defines OAuth 2.1 as the authorisation framework for HTTP-based MCP servers. A protected MCP server is an OAuth 2.1 resource server, the MCP client an OAuth 2.1 client. Authorization servers must implement OAuth 2.1, MCP servers must provide protected resource metadata (RFC 9728), and clients must use PKCE with S256 and the resource parameter according to RFC 8707 so that tokens are bound to the respective server. The specification does not apply to STDIO transports; there, credentials come from the environment.

The specification version of 28 July 2026 rebuilt client registration. Dynamic client registration according to RFC 7591 is deprecated and is only retained for compatibility reasons. It is replaced by client ID metadata documents: the client uses an HTTPS URL as its client_id, behind which there is a JSON document with name and redirect URIs. The authorization server loads this document when needed. This solves the typical MCP problem that client and server do not know each other beforehand.

In addition, the same version requires a check of the iss parameter in the authorisation response according to RFC 9207. Before the redirect, the client remembers the issuer of the authorization server and compares it on the return. This prevents mix-up attacks, in which a compromised authorization server intercepts a code from another server. How this works together in practice is explained in our post MCP server explained.

Vendors are following suit. HubSpot made its remote MCP server generally available on 13 April 2026 and requires OAuth 2.1 with PKCE for every connection. For agencies and development teams this means: anyone who connects AI agents to a shop, ERP or CRM cannot get around a clean OAuth 2.1 implementation.

Typical implementation mistakes

Most security problems with OAuth arise not in the protocol but in the implementation. You should check these points in every integration:

• Redirect URIs are only checked by prefix or wildcard. An attacker can then redirect codes to a domain of their own.
• Access tokens are stored in URLs, logs or the browser's localStorage, where they can be read out via XSS.
• The resource server does not check the token's audience and accepts tokens issued for another service.
• Scopes are set to "everything" across the board instead of granting only the necessary rights per integration.
• Client secrets end up in front-end code, mobile apps or public repositories.
• Long-lived tokens without rotation, so that a token once stolen remains valid permanently.

A proven route is not to write an authorization server yourself but to use a tested component such as Keycloak, Microsoft Entra ID or a comparable identity provider and to run your own services only as resource servers.

Frequently asked questions about OAuth

Is OAuth a login method? No. OAuth governs authorisation, which rights a client receives. For signing a user in, OpenID Connect is used, which builds on OAuth 2.0 and adds an ID token with identity details.

Do I need PKCE for server applications too? Yes. OAuth 2.1 requires PKCE for all clients in the authorization code flow, regardless of whether they have a client secret. PKCE protects against the interception and injection of authorization codes and only takes a few lines to implement.

What is the difference between an access token and a refresh token? The access token is sent with every API call and is short-lived. The refresh token only serves to obtain a new access token from the authorization server. It is never sent to the resource server and must be particularly well protected.

Which OAuth version do I need for MCP servers? The MCP specification requires OAuth 2.1, including PKCE with S256, protected resource metadata according to RFC 9728 and the resource parameter according to RFC 8707. Since the version of 28 July 2026, clients should also support client ID metadata documents and check the iss parameter according to RFC 9207.