Internet-Draft OAuth Userinfo Response November 2026
Parecki Expires 23 May 2027 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-parecki-oauth-userinfo-response-latest
Published:
Intended Status:
Informational
Expires:
Author:
A. Parecki
Okta

OAuth Userinfo Response

Abstract

This specification defines an extension to the OAuth 2.0 Token Endpoint Response to allow the authorization server to return an identifier for the user who authorized the request, and optionally additional information about that user, directly in the token response as plain JSON.

About This Document

This note is to be removed before publishing as an RFC.

The latest revision of this draft can be found at https://drafts.aaronpk.com/oauth-userinfo-response/draft-parecki-oauth-userinfo-response.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-parecki-oauth-userinfo-response/.

Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/.

Source for this draft and an issue tracker can be found at https://github.com/aaronpk/oauth-userinfo-response.

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 23 May 2027.

▲

Table of Contents

1. Introduction

This specification defines an extension to the OAuth 2.0 [RFC6749] Token Endpoint Response to allow the authorization server to return an identifier for the user who authorized the request, and optionally additional information about that user, directly in the token response.

OAuth 2.0 does not define a way for the authorization server to tell the client which user authorized the request. Many clients only need to know a user identifier, for example to associate the authorization with a local account, and do not require a signed statement about the user or their authentication from the authorization server. Returning this information as plain JSON in the token response avoids an additional request, as well as the overhead, complexity, and dependency management associated with parsing and validating a JSON Web Token (JWT).

This specification provides two different ways the authorization server can return info in the Token Response:

This specification only gives the authorization server a way to return a user identifier to the client. It does not prove the identity of the user, and the identifier says nothing about a real person: it is the authorization server's own identifier for the account that authorized the request.

This mechanism MUST NOT be used when the client requires a signed statement about the user, such as when the client needs non-repudiation of the claims.

2. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This specification uses the terms "authorization server", "client", "resource owner", "authorization request", "token endpoint", and "scope" defined by OAuth 2.0 [RFC6749]. The term "user" refers to the resource owner who authorized the request.

3. Subject Response

To signal its intent to receive the user identifier in the Token Response, the client uses a new scope value in the Authorization Request.

3.1. Requesting the Subject Response

This specification defines a new scope value: subject

subject

Requests that the authorization server return the user identifier (sub) directly in the Token Response.

3.2. Authorization Request

The client SHOULD include the subject scope along with any other required scopes in the Authorization Request.

Example request:

GET /authorize?
  response_type=code
  &client_id=e69b14fe3fdcf1b432deb0c
  &scope=subject
  &state=9e6d47801c833bfc8
  &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
  &code_challenge=dy57vyachQ...&code_challenge_method=S256

Note: This is not limited to the [RFC6749] Authorization Code flow and applies the same to extensions such as Pushed Authorization Request [RFC9126].

3.3. Token Endpoint Response

This specification defines a new field to be returned in the Token Endpoint response: sub.

In the Authorization Code flow, upon successful validation of the Authorization Code, the PKCE Code Verifier, and optional client authentication, the authorization server constructs a Token Response including the new field sub.

The value of sub is a string containing the authorization server's identifier for the user who authorized the request. It has the same meaning as the sub claim defined in Section 4.1.2 of [RFC7519]. The value MUST be unique within the authorization server and MUST NOT be reassigned to a different user. The value is an opaque identifier that is only meaningful in the context of the authorization server that issued it.

3.4. Response Rules

  • If the client included the subject scope in the initial Authorization Request, the authorization server MUST include the sub parameter in the Token Response. The authorization server MAY also return the sub parameter if the client did not include the subject scope in the initial Authorization Request.

  • No change is made to the requirements of the standard OAuth 2.0 [RFC6749] parameters in the response or any additional parameters defined by extensions.

Example successful token response

{
  "access_token": "a5c64fbb3e03d973d3c7ef",
  "token_type": "Bearer",
  "expires_in": 3600,
  "sub": "b46b2f1f2b7686d"
}

4. Userinfo Response

To signal its intent to receive information about the user in the Token Response, the client uses a new scope value in the Authorization Request.

4.1. Requesting the Userinfo Response

This specification defines a new scope value: userinfo

userinfo

Requests that the authorization server return information about the user directly in the Token Response.

4.2. Authorization Request

The client SHOULD include the userinfo scope along with any other required scopes in the Authorization Request.

Example request:

GET /authorize?
  response_type=code
  &client_id=e69b14fe3fdcf1b432deb0c
  &scope=userinfo
  &state=9e6d47801c833bfc8
  &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
  &code_challenge=dy57vyachQ...&code_challenge_method=S256

Note: This is not limited to the [RFC6749] Authorization Code flow and applies the same to extensions such as Pushed Authorization Request [RFC9126].

4.3. Token Endpoint Response

This specification defines a new field to be returned in the Token Endpoint response: userinfo.

In the Authorization Code flow, upon successful validation of the Authorization Code, the PKCE Code Verifier, and optional client authentication, the authorization server constructs a Token Response including the new field userinfo.

The value of userinfo is a JSON object containing the user identifier and any additional claims the authorization server chooses to return. The claim names and their meanings are those registered in the IANA "JSON Web Token Claims" registry established by [RFC7519]. The object MUST contain the sub claim, as described in Section 3.3. Which additional claims are returned is at the discretion of the authorization server, and may depend on the scopes granted.

4.4. Response Rules

  • If the client included the userinfo scope in the initial Authorization Request, the authorization server MUST include the userinfo parameter in the Token Response. The authorization server MAY also return the userinfo parameter if the client did not include the userinfo scope in the initial Authorization Request.

  • No change is made to the requirements of the standard OAuth 2.0 [RFC6749] parameters in the response or any additional parameters defined by extensions.

Example successful token response

{
  "access_token": "a5c64fbb3e03d973d3c7ef",
  "token_type": "Bearer",
  "expires_in": 3600,
  "userinfo": {
    "sub": "b46b2f1f2b7686d",
    "name": "Alice Example",
    "preferred_username": "alice",
    "picture": "https://as.example.com/u/b46b2f1f2b7686d.jpg"
  }
}

5. Security Considerations

5.1. Not a Proof of Identity

The sub and userinfo values are not an assertion of the user's identity. They tell the client which identifier the authorization server associates with the user who authorized the request, and nothing more. In particular, they do not establish that the user is a particular real person. Clients MUST treat the user identifier as scoped to the authorization server that returned it, and MUST NOT assume that the same value returned by a different authorization server refers to the same user.

5.2. Token Endpoint

The sub and userinfo response fields MUST only be returned from the token endpoint.

The sub and userinfo values MUST NOT be returned in the Authorization Response (the URL redirect back to the client), as this passes through the front channel and provides no mechanism for the client to validate the legitimacy of the value in the response.

5.3. Authorization Code Flow

If using the Authorization Code flow, or any flow that utilizes a browser redirect, the flow MUST be secured with PKCE as defined in [RFC7636] to prevent authorization code injection attacks.

5.4. Tamper Resistance

The response defined here provides no cryptographic signature over the sub or userinfo values. Their integrity and authenticity are solely reliant on the security of the transport layer of the Token Endpoint and the preceding Authorization Code + PKCE exchange.

6. IANA Considerations

6.1. OAuth Parameters Registration

IANA is requested to register the following values in the "OAuth Parameters" registry of the "OAuth Parameters" registry group established by Section 11.2 of [RFC6749].

Name:

sub

Parameter Usage Location:

token response

Change Controller:

IETF

Reference:

Section 3.3 of this document

Name:

userinfo

Parameter Usage Location:

token response

Change Controller:

IETF

Reference:

Section 4.3 of this document

7. References

7.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/rfc/rfc6749>.
[RFC7519]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/rfc/rfc7519>.
[RFC7636]
Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, , <https://www.rfc-editor.org/rfc/rfc7636>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.

7.2. Informative References

[RFC9126]
Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, , <https://www.rfc-editor.org/rfc/rfc9126>.

Acknowledgments

The authors would like to thank the following people for their review and contributions to this draft: Brian Campbell.

Author's Address

Aaron Parecki
Okta