HTTP Bearer Auth Method Extensions

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 6 June 2026.¶

Copyright Notice

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

HTTP [HTTP] has a number of authentication methods available, including Bearer [BEARER] that uses OAuth 2.0 [OAUTH2], which is the subject of this document. Some HTTP authentication methods, like Negotiate [NEGOTIATE], allow the user-agent to automatically respond to a 401 or 407 status response when possible by creating a token locally using the GSS-API [GSSAPI], typically using Kerberos [KERBEROS]. However, the Bearer method effectively requires that the client application respond to the 401/407 authentication request rather than the HTTP user-agent, and it provides little metadata that either can use to figure out how to obtain a Bearer token. Today an OAuth application just has to know how to obtain the Bearer token, and has to be configured appropriately, and this greatly limits the applicability of the 401/407 flows.¶

Note that we will mostly refer to 401 flows here, but everything that applies to 401 flows also applies to 407 flows.¶

Here we specify extension auth-params to the 401 WWW-Authenticate: Bearer HTTP response so that either the client application or the user-agent can figure out how to obtain the requested token after applying local policy.¶

As well we provide a way to improve the OIDC redirect flow to make use of this extension where possible, and this provides a migration path to a world where URI q-param camping and PKCE [PKCE] and code-to-token conversions are no-longer needed just to use OAuth 2.x.¶

The extended Bearer 401 flow presented here is a glorified redirect that avoids the need for camping on the application's URI q-params.¶

2. Extended 401 WWW-Authenticate: Bearer Flow

Currently the following auth-params are supported in a 401 response with WWW-Authenticate=Bearer:¶

• realm¶

• scope¶

• error¶

• error_description¶

• error_uri¶

We add the following additional, OPTIONAL auth-params:¶

• issuer with a URI as a value¶

• server_token_type with a token type Universal Resource Name (URN) as a value¶

• server_token with a token to be forwarded to the issuer by the user-agent or client application¶

• state with a "state" value -- this corresponds to the OIDC state q-param in a redirect to the OpenID provider¶

The issuer parameter allows the user-agent or client application to discover the URI of a Security Token Service (STS) to visit to get a token. Though of course a user-agent or client application could map a realm auth-param value to an STS URI, or even the realm could consist of an issuer URI, however by having an auth-param intended to carry an issuer URI we avoid ambiguities about the meaning of "realm".¶

The server_token auth-param allows the server to pass a cryptographic token to the issuer via the user-agent's or client application's subsequent request to the issuer. The user-agent or client application will set a new requested header Token-Request-Pref to the value in the 401 response's server_token auth-param.¶

Essentially this functions like a redirect response, but with a 401 status code and with the Server-Token and Server-Token-Type carrying the token and token type from the server_token and server_token_type auth-params respectively, if present.¶

The user-agent and/or client application MUST apply local policy, where any is set, as to whether to execute a token request against the requrested issuer.¶

When making the token request to the issuer the user-agent or client application MUST also set the following fields:¶

• Referer, as if the 401 response had been a redirect¶

• a new Token-Request header to indicate that the request is in response to an extended Bearer token request by the server¶

• Token-Request-Token, set to the token from the server_token auth-param, if present¶

When making the token request to the issuer the user-agent or client application SHOULD also set the following fields:¶

• Token-Request-Auth-Params, with all auth-params other than the issuer and server_token parameters.¶

When the STS supports this feature then a successful response MUST be a 200 status code response if successful rather than a 3xx redirect response, with a field Location field set to the value of the Token-Request-URI field (if present) from the request to the STS and with the issued token in the response body.¶

The value forms of these headers are specified below (Section 6).¶

GET /some/resource HTTP/1.1
Host: some.origin.example

HTTP/1.1 401 Authentication required
WWW-Authenticate: Negotiate
WWW-Authenticate: Bearer issuer=https://iam.foo.example/v1/token
        scope=read:some/resource
        server_token=Bearer:<some-JWT>

POST /v1/token
Host: iam.foo.example
Token-Request-Auth-Params: scope=read:some/resource
Token-Request-Token: Bearer:<some-JWT>
Token-Request-URI: https://some.origin.example/some/resource

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
audience=some.origin.example&
scope=read:some/resource&
...

HTTP/1.1 200 Ok
Location: https://some.origin.example/some/resource

<token>

HTTP/1.1 302 Found
Location: https://some.origin.example/some/resource?code=..&state=..

3. Extended Redirect Flow

The extended redirect flow has a normal 3xx response from the server but with the WWW-Authenticate field present, possibly including new auth-params.¶

Note well that some user-agents terminate 3xx response processing as soon as they see the expected Location field, and thus may not see a WWW-Authenticate field if it comes after, and note that proxies are allowed to reorder fields (but not field values for multi-valued fields), therefore it is not possible for a server to reliably count on the WWW-Authenticate field being seen by the client.¶

Still, when a client sees the WWW-Authenticate field then it SHOULD act as though the response was a 401 response engaging in an extended OAuth 401 flow.¶

4. Negotiation of 401 vs Redirect Flows

A server may only support redirect flows, only 401 flows, or it may support negotiation as described here. Ideally all servers will eventually support negotiation, and/or all user-agents will support the extended Bearer 401 flow.¶

The Token-Request-Pref field has two values: 401 and redirect. When present the server SHOULD use the expressed preference if it needs a new token.¶

When this field is absent the server must choose a response type using configuration and user-agent fingerprinting.¶

5. Local Policy

Local policy is OPTIONAL. When present, local policy expresses:¶

• whether to enable automatic token request handling when using the extended Bearer 401 flow¶

• allow lists for issuers and/or realms¶

• mappings of realms to issuers¶

• authentication methods to allow at each issuer, if any¶

• global and site-specific flow type preferences, and whether to express those flow type preferences via the Token-Request-Pref field¶

• for each allowed issuer optionally record its authentication method preferences so that the user-agent or client application may pre-flight an Authorization field in the token requests to that issuer¶

6. New fields

• Token-Request-Pref is a structured field of kind Item with a value of "401" or "redirect"¶

• Token-Request is a structured field of kind Item with a value of "true" if present¶

• Token-Request-Token is a structured field of kind Item with a token as its value¶

• Token-Request-Auth-Params is a structured field of kind List with the 401 response's auth-params from the WWW-Authenticate: Bearer field¶

• Token-Request-URI is a field of kind Item containing the URI that requested the token¶

7. New auth-params

• issuer¶

• server_token_type¶

• server_token¶

• state¶

See section 2 (Section 2) for details.¶

8. Wider Applicability: Negotiate Auth w/o GSS or Kerberos Implementations!

This section is INFORMATIONAL.¶

A similar extension design can be applied to the Negotiate HTTP auth method that would allow user-agents to support Negotiate without having a local implementation of the GSS-API [GSSAPI], Kerberos [KERBEROS], or other GSS mechanisms. All that would be needed is an STS-like service that itself can issue Kerberos tickets or can impersonate users to a Kerberos Key Distribution Center (KDC) and thus obtain tickets on their behalf, then the STS can mint GSS-API tokens for the Kerberos mechanism [GSSKRB5]. The rest of the flow would be remarkably similar to the extended Bearer 401 flow.¶

An implementation of such an Negotiate token issuer could have a certification authority credential to mint user certificates for use with PKINIT [PKINIT] to impersonate users to a Kerberos KDC. Thus such a service would not need intimate access to the KDC's key database, and can be interoperate with any KDC implementation that supports PKINIT. In all cases such a service would be as security-sensitive as a KDC, and would best be seen as part of the KDC, and for discovery purposes should probably be co-located with the KDC.¶

As in the case of Bearer an issuer URI auth-param for Negotiate might be useful, though perhaps the user will have to have selected an issuer from a server-provided list of choices. In the case of Kerberos, for example, the choice of token issuer will be dependent on the user's credentials' issuer, thus local configuration at the user-agent will be the best source of an issuer value for a Negotiate 401 flow that resembles the extended Bearer 401 flow. But even in the case of Kerberos if the user-agent can help the server include the correct issuer auth-param value then the flow can work in spite of the lack of local configuration.¶

9. Single Sign-On

This section is INFORMATIVE.¶

When engaging in an OIDC or SAML redirect flow, or an extended 401/407 flow as in this document, ultimately the user-agent, the client, and/or the user will have to authenticate the user to an issuer. How that is done initially (e.g., with passwords, smartcards and PINs, etc.) is out of scope here, but for Single Sign-On (SSO) one will want to distinguish between "initial authentication" and non-initial authentication (i.e., not passwords, smartcards, PINs, etc.), much like Kerberos [KERBEROS] does. A user-agent could use cookies, or a "token-granting token" (similar to a Kerbero ticket-granting ticket, both sharing the same acronym of 'TGT') to repeatedly authenticate to an issuer for a limited time after which the user has to once again engage in "initial authentication".¶

10. IANA Considerations

As there is no registry of HTTP auth method auth-params, we do not register any of the new auth-params created here. However, it might be desirable to create such a registry before this document's publication as an RFC.¶

This document registers several new HTTP fields listed below.¶

11. Security Considerations

Existing user-agents that support redirect flows usually trust all redirects. As a result we make local policy OPTIONAL for use in the automatic the extended Bearer 401 flow. The specification of an "abstract schema" for local policy is an improvement.¶

User-agents such as browsers MUST NOT allow scripts embedded or injected into web pages to access to the STS responses from extended Bearer 401 flow. This is already the case, thus this requirement is not a new requirement and does not impose on other working groups or standards development organizations.¶

Apart from the above this document does not add new security considerations beyond those of OAuth and OIDC, but it does remove the need for "codes" and PKCE [PKCE] by not abusing URI q-params to carry tokens or token-like "codes", instead carrying tokens only in the Authorization field and in the STS response body invisible to scripts on web pages. As well by not abusing URI q-params no sensitive cryptographic material such as "codes" and tokens can end up in user-agent history nor in client- or server-side logs.¶

Thus this extended Bearer 401 flow is strictly an improvement in security for OAuth.¶

But note that when the server does not implement the extended Bearer 401 flow then a fallback to a redirect flow may happen, thus user-agents and/or clients still need to implement PKCE [PKCE].¶

Appendix A. Acknowledgements

Author's Address