Internet DRAFT - draft-parecki-oauth-first-party-native-apps
draft-parecki-oauth-first-party-native-apps
Web Authorization Protocol A. Parecki
Internet-Draft Okta
Intended status: Standards Track G. Fletcher
Expires: 8 January 2024 Capital One Financial
P. Kasselman
Microsoft
7 July 2023
OAuth 2.0 for First-Party Native Applications
draft-parecki-oauth-first-party-native-apps-00
Abstract
This document defines the Authorization Challenge Endpoint, which
supports a first-party native client that wants to control the
process of obtaining authorization from the user using a native
experience.
In many cases, this can provide an entirely browserless OAuth 2.0
experience suited for native applications, only delegating to the
browser in unexpected, high risk, or error conditions.
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://aaronpk.github.io/oauth-first-party-native-apps/draft-
parecki-oauth-first-party-native-apps.html. Status information for
this document may be found at https://datatracker.ietf.org/doc/draft-
parecki-oauth-first-party-native-apps/.
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-first-party-native-apps.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Parecki, et al. Expires 8 January 2024 [Page 1]
Internet-Draft OAuth for First-Party Native Apps July 2023
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 8 January 2024.
Copyright Notice
Copyright (c) 2023 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 . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Usage and Applicability . . . . . . . . . . . . . . . . . 4
1.2. Limitations of this specification . . . . . . . . . . . . 5
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 5
2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Initial Authorization Request . . . . . . . . . . . . . . 5
3.2. Refresh Token Request . . . . . . . . . . . . . . . . . . 7
3.3. Resource Request . . . . . . . . . . . . . . . . . . . . 7
4. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 7
4.1. Authorization Challenge Endpoint . . . . . . . . . . . . 7
4.2. Token endpoint . . . . . . . . . . . . . . . . . . . . . 8
5. Authorization Initiation . . . . . . . . . . . . . . . . . . 9
5.1. Authorization Challenge Request . . . . . . . . . . . . . 9
5.2. Authorization Challenge Response . . . . . . . . . . . . 9
5.2.1. Authorization Code Response . . . . . . . . . . . . . 10
5.2.2. Error Response . . . . . . . . . . . . . . . . . . . 10
5.3. Device Session . . . . . . . . . . . . . . . . . . . . . 11
6. Token Request . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Token Endpoint Error Response . . . . . . . . . . . . . . 12
Parecki, et al. Expires 8 January 2024 [Page 2]
Internet-Draft OAuth for First-Party Native Apps July 2023
7. Resource Server Error Response . . . . . . . . . . . . . . . 13
8. Authorization Server Metadata . . . . . . . . . . . . . . . . 13
9. Security Considerations . . . . . . . . . . . . . . . . . . . 13
9.1. First-Party Applications . . . . . . . . . . . . . . . . 13
9.2. Phishing . . . . . . . . . . . . . . . . . . . . . . . . 13
9.3. Client Authentication . . . . . . . . . . . . . . . . . . 14
9.4. Sender Constrained Tokens . . . . . . . . . . . . . . . . 14
9.4.1. Demonstrating Proof-of-Possession . . . . . . . . . . 15
9.4.2. Other Proof of Possession Mechanisms . . . . . . . . 15
9.4.3. Device Session . . . . . . . . . . . . . . . . . . . 15
9.5. Multiple Applications . . . . . . . . . . . . . . . . . . 15
9.5.1. Experience Risk . . . . . . . . . . . . . . . . . . . 16
9.5.2. Technical Risk . . . . . . . . . . . . . . . . . . . 16
9.5.3. Mitigation . . . . . . . . . . . . . . . . . . . . . 16
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
11.1. Normative References . . . . . . . . . . . . . . . . . . 17
11.2. Informative References . . . . . . . . . . . . . . . . . 18
Appendix A. Example User Experiences . . . . . . . . . . . . . . 18
A.1. Passwordless One-Time Passwork (OTP) . . . . . . . . . . 18
A.2. E-Mail Confirmation Code . . . . . . . . . . . . . . . . 19
A.3. SMS Confirmation Code . . . . . . . . . . . . . . . . . . 20
A.4. Re-authenticating to an app a week later using OTP . . . 20
A.5. Step-up Authentication using Confirmation SMS . . . . . . 21
A.6. Registration . . . . . . . . . . . . . . . . . . . . . . 23
Appendix B. Example Implementation . . . . . . . . . . . . . . . 24
B.1. Authorization Challenge Request Parameters . . . . . . . 24
B.2. Authorization Challenge Response Parameters . . . . . . . 25
B.3. Example Sequence . . . . . . . . . . . . . . . . . . . . 25
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
1. Introduction
This document extends the OAuth 2.0 Authorization Framework [RFC6749]
with a new endpoint, authorization_challenge_endpoint, to support
first-party native applications that want to control the process of
obtaining authorization from the user using a native experience.
The client collects any initial information from the user and POSTs
that information as well as information about the client's request to
the Authorization Challenge Endpoint, and receives either an
authorization code or an error code in response. The error code may
indicate that the client can continue to prompt the user for more
information, or can indicate that the client needs to launch a
browser to have the user complete the flow in a browser.
Parecki, et al. Expires 8 January 2024 [Page 3]
Internet-Draft OAuth for First-Party Native Apps July 2023
The Authorization Challenge Endpoint is used to initiate the OAuth
flow in place of redirecting or launching a browser to the
authorization endpoint.
While a fully-delegated approach using the redirect-based
Authorization Code grant is generally preferred, this draft provides
a mechanism for the client to directly interact with the user. This
requires a high degree of trust between the authorization server and
the client, as there typically is for first-party applications. It
should only be considered when there are usability concerns with a
redirect-based approach, such as for native mobile or desktop
applications.
This draft also extends the token response (typically for use in
response to a refresh token request) and resource server response to
allow the authorization server or resource server to indicate that
the client should re-request authorization from the user. This can
include requesting step-up authentication by including parameters
defined in [I-D.ietf-oauth-step-up-authn-challenge] as well.
1.1. Usage and Applicability
This specification MUST only be used by first-party applications,
which is when the authorization server and application are operated
by the same entity and the user understands them both as the same
entity.
This specification MUST NOT be used by third party applications, and
the authorization server SHOULD take measures to prevent use by third
party applications. (e.g. only enable this grant for certain client
IDs, and take measures to authenticate first-party apps when
possible.)
Using this specification in scenarios other than those described will
lead to unintended security and privacy problems for users and
service providers.
This specification is designed to be used by native applications,
which includes both mobile and desktop applications.
If you provide multiple apps and expect users to use multiple apps on
the same device, there may be better ways of sharing a user's login
between the apps other than each app implementing this specification
or using an SDK that implements this specification. For example,
[OpenID.Native-SSO] provides a mechanism for one app to obtain new
tokens by exchanging tokens from another app, without any user
interaction. See Section 9.5 for more details.
Parecki, et al. Expires 8 January 2024 [Page 4]
Internet-Draft OAuth for First-Party Native Apps July 2023
1.2. Limitations of this specification
The scope of this specification is limited to first-party native
applications. Please review the entirety of Section 9, and when more
than one first-party native application is supported, Section 9.5.
While this draft provides the framework for a native OAuth
experience, each implementation will need to define the specific
behavior that it expects from OAuth clients interacting with the
authorization server. While this lack of clearly defining the
details would typically lead to less interoperability, it is
acceptable in this case since we intend this specification to be
deployed in a tightly coupled environment since it is only applicable
to first-party applications.
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.
2.1. Terminology
This specification uses the terms "Access Token", "Authorization
Code", "Authorization Endpoint", "Authorization Server" (AS),
"Client", "Client Authentication", "Client Identifier", "Client
Secret", "Grant Type", "Protected Resource", "Redirection URI",
"Refresh Token", "Resource Owner", "Resource Server" (RS) and "Token
Endpoint" defined by [RFC6749].
TODO: Replace RFC6749 references with OAuth 2.1
3. Protocol Overview
There are three primary ways this specification extends various parts
of an OAuth system.
3.1. Initial Authorization Request
Parecki, et al. Expires 8 January 2024 [Page 5]
Internet-Draft OAuth for First-Party Native Apps July 2023
+-------------------+
| Authorization |
(B)Authorization | Server |
+----------+ Challenge Request |+-----------------+|
(A)Client+---| Native |---------------------->|| Authorization ||
Starts| | Client | || Challenge ||
Flow +-->| |<----------------------|| Endpoint ||
| | (C)Authorization || ||
| | Error Response || ||
| | : || ||
| | : || ||
| | (D)Authorization || ||
| | Challenge Request || ||
| |---------------------->|| ||
| | || ||
| |<----------------------|| ||
| | (E) Authorization |+-----------------+|
| | Code Response | |
| | | |
| | | |
| | | |
| | (F) Token | |
| | Request |+-----------------+|
| |---------------------->|| Token ||
| | || Endpoint ||
| |<----------------------|| ||
| | (G) Access Token |+-----------------+|
| | | |
+----------+ +-------------------+
Figure: Native Client Authorization Code Request
* (A) The native client starts the flow, by presenting the user with
a "sign in" button, or collecting information from the user, such
as their email address or username.
* (B) The client initiates the authorization request by making a
POST request to the Authorization Challenge Endpoint, optionally
with information collected from the user (e.g. email or username)
Parecki, et al. Expires 8 January 2024 [Page 6]
Internet-Draft OAuth for First-Party Native Apps July 2023
* (C) The authorization server determines whether the information
provided to the Authorization Challenge Endpoint is sufficient to
grant authorization, and either responds with an authorization
code or responds with an error. In this example, it determines
that additional information is needed and responds with an error.
The error may contain additional information to guide the Client
on what information to collect next. This pattern of collecting
information, submitting it to the Authorization Challenge Endpoint
and then receing an error or authorization code may repeat several
times.
* (D) The client gathers additional information (e.g. passkey, or
one-time code from email) and makes a POST request to the
Authorization Challenge Endpoint.
* (E) The Authorization Challenge Endpoint returns an authorization
code.
* (F) The native client sends the authorization code received in
step (E) to obtain a token from the Token Endpoint.
* (G) The Authorization Server returns an Access Token from the
Token Endpoint.
3.2. Refresh Token Request
When the client uses a refresh token to obtain a new access token,
the authorization server MAY respond with an error to indicate that
re-authorization of the user is required.
3.3. Resource Request
When making a resource request to a resource server, the resource
server MAY respond with an error according to OAuth 2.0 Step-Up
Authentication Challenge Protocol
[I-D.ietf-oauth-step-up-authn-challenge], indicating that re-
authorization of the user is required.
4. Protocol Endpoints
4.1. Authorization Challenge Endpoint
The authorization challenge endpoint is a new endpoint defined by
this specification which the native application uses to obtain an
authorization code.
Parecki, et al. Expires 8 January 2024 [Page 7]
Internet-Draft OAuth for First-Party Native Apps July 2023
The authorization challenge endpoint is an HTTP API at the
authorization server that accepts HTTP POST requests with parameters
in the HTTP request message body using the application/x-www-form-
urlencoded format. This format has a character encoding of UTF-8, as
described in Appendix B of [RFC6749]. The authorization challenge
endpoint URL MUST use the "https" scheme.
Authorization servers supporting this specification SHOULD include
the URL of their authorization challenge endpoint in their
authorization server metadata document [RFC8414] using the
authorization_challenge_request_endpoint parameter as defined in
Section 8.
The endpoint accepts the authorization request parameters defined in
[RFC6749] for the authorization endpoint as well as all applicable
extensions defined for the authorization endpoint. Some examples of
such extensions include Proof Key for Code Exchange (PKCE) [RFC7636],
Resource Indicators [RFC8707], and OpenID Connect [OpenID]. It is
important to note that some extension parameters have meaning in a
web context but don't have meaning in a native mechanism (e.g.
response_mode=query). It is out of scope as to what the AS does in
the case that an extension defines a parameter that is has no meaning
in this use case.
The client initiates the authorization flow with or without
information collected from the user (e.g. a passkey or MFA code).
The authorization challenge endpoint response is either an
authorization code or an error code, and may also contain a
device_session which the client uses on subsequent requests to the
authorization challenge endpoint.
4.2. Token endpoint
The token endpoint is used by the client to obtain an access token by
presenting its authorization grant or refresh token, as described in
Section 3.2 of OAuth 2.0 [RFC6749].
This specification extends the token endpoint response to allow the
authorization server to indicate that further authentication of the
user is required.
Parecki, et al. Expires 8 January 2024 [Page 8]
Internet-Draft OAuth for First-Party Native Apps July 2023
5. Authorization Initiation
A client may wish to initiate an authorization flow by first
prompting the user for their user identifier or other account
information. The authorization challenge endpoint is a new endpoint
to collect this login hint and direct the client with the next steps,
whether that is to do an MFA flow, or perform an OAuth redirect-based
flow.
5.1. Authorization Challenge Request
The client makes a request to the authorization challenge endpoint by
adding the following parameters, as well as parameters from any
extensions, using the application/x-www-form-urlencoded format with a
character encoding of UTF-8 in the HTTP request body:
"client_id": REQUIRED if the client is not authenticating with the
authorization server and if no device_session is included.
"scope": OPTIONAL. The OAuth scope defined in [RFC6749].
"acr_values": OPTIONAL. The acr_values requested by the client.
"device_session": OPTIONAL. If the client has previously obtained a
device session, described in Section 5.3.
Specific implementations as well as extensions to this specification
MAY define additional parameters to be used at this endpoint.
For example, the client makes the following request to initiate a
flow given the user's phone number, line breaks shown for
illustration purposes only:
POST /authorize HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
login_hint=%2B1-310-123-4567&scope=profile
&client_id=bb16c14c73415
5.2. Authorization Challenge Response
The authorization server determines whether the information provided
up to this point is sufficient to issue an authorization code, and
responds with an authorization code or an error message.
Parecki, et al. Expires 8 January 2024 [Page 9]
Internet-Draft OAuth for First-Party Native Apps July 2023
5.2.1. Authorization Code Response
The authorization server issues an authorization code by creating an
HTTP response content using the application/json media type as
defined by [RFC8259] with the following parameters and an HTTP 200
(OK) status code:
"authorization_code": REQUIRED. The authorization code issued by
the authorization server.
For example,
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
{
"authorization_code": "uY29tL2F1dGhlbnRpY"
}
5.2.2. Error Response
If the request contains invalid parameters or incorrect data, the
authorization server responds with an HTTP 400 (Bad Request) status
code (unless specified otherwise) and includes the following
parameters with the response:
"error": REQUIRED. A single ASCII [USASCII] error code from the
following:
"invalid_request": The request is missing a required parameter,
includes an unsupported parameter value, repeats a parameter,
includes multiple credentials, utilizes more than one mechanism
for authenticating the client, or is otherwise malformed.
"invalid_client": Client authentication failed (e.g., unknown
client, no client authentication included, or unsupported
authentication method). The authorization server MAY return an
HTTP 401 (Unauthorized) status code to indicate which HTTP
authentication schemes are supported. If the client attempted
to authenticate via the Authorization request header field, the
authorization server MUST respond with an HTTP 401
(Unauthorized) status code and include the WWW-Authenticate
response header field matching the authentication scheme used
by the client.
"unauthorized_client": The authenticated client is not authorized
to use this authorization grant type.
Parecki, et al. Expires 8 January 2024 [Page 10]
Internet-Draft OAuth for First-Party Native Apps July 2023
"invalid_scope": The requested scope is invalid, unknown,
malformed, or exceeds the scope granted by the resource owner.
Values for the error parameter MUST NOT include characters outside
the set %x20-21 / %x23-5B / %x5D-7E.
The authorization server MAY extend these error codes with custom
messages based on the requirements of the authorization server.
"error_description": OPTIONAL. Human-readable ASCII [USASCII] text
providing additional information, used to assist the client
developer in understanding the error that occurred. Values for
the error_description parameter MUST NOT include characters
outside the set %x20-21 / %x23-5B / %x5D-7E.
"error_uri": OPTIONAL. A URI identifying a human-readable web page
with information about the error, used to provide the client
developer with additional information about the error. Values for
the error_uri parameter MUST conform to the URI-reference syntax
and thus MUST NOT include characters outside the set %x21 /
%x23-5B / %x5D-7E.
"device_session": OPTIONAL. The device session allows the
authorization server to associate subsequent requests by this
client with an ongoing authorization request sequence. The client
MUST include the device_session in follow-up requests to the
challenge endpoint if it receives one along with the error
response.
The parameters are included in the content of the HTTP response using
the application/json media type as defined by [RFC7159]. The
parameters are serialized into a JSON structure by adding each
parameter at the highest structure level. Parameter names and string
values are included as JSON strings. Numerical values are included
as JSON numbers. The order of parameters does not matter and can
vary.
The authorization server MAY define additional parameters in the
response depending on the implmentation.
5.3. Device Session
The device session is completely opaque to the client, and as such
the AS MUST adequately protect the value from inspection by the
client, for example by using a JWE if the AS is not maintaining state
on the backend.
Parecki, et al. Expires 8 January 2024 [Page 11]
Internet-Draft OAuth for First-Party Native Apps July 2023
The client MUST include the device session in future requests to the
authorization challenge endpoint for the particular authorization
request.
6. Token Request
The client makes a request to the token endpoint using the
authorization code it obtained from the authorization challenge
endpoint.
This specification does not define any additional parameters beyond
the token request parameters defined in Section 4.1.3 of [RFC6749].
However, notably the redirect_uri parameter will not be included in
this request, because no redirect_uri parameter was included in the
authorization request.
6.1. Token Endpoint Error Response
Upon any request to the token endpoint, including a request with a
valid refresh token, the authorization server can respond with an
authorization challenge instead of a successful access token
response.
An authorization challenge error response is a particular type of
error response as defined in Section 5.2 of OAuth 2.0 [RFC6749] where
the error code is set to the following value:
"error": "authorization_required": The authorization grant is
insufficiently authorized, but another access token request may
succeed if an additional authorization grant is presented.
"device_session": OPTIONAL. The optional device session value
allows the authorization server to associate subsequent requests
by this client with an ongoing authorization request sequence.
The client MUST include the device_session in follow-up requests
to the challenge endpoint if it receives one along with the error
response.
For example:
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
{
"error": "authorization_required",
"device_session": "uY29tL2F1dGhlbnRpY"
}
Parecki, et al. Expires 8 January 2024 [Page 12]
Internet-Draft OAuth for First-Party Native Apps July 2023
7. Resource Server Error Response
Step-Up Authentication [I-D.ietf-oauth-step-up-authn-challenge]
defines a mechanism for resource servers to tell the client to start
a new authorization request, including acr_values and max_age, and
scope from RFC6750. Upon receiving this request, the client starts a
new authorization request according to this specification, and
includes the acr_values, max_age and scope returned in the error
response.
This specification does not define any new parameters for the
resource server error response beyond those defined in
[I-D.ietf-oauth-step-up-authn-challenge].
8. Authorization Server Metadata
The following authorization server metadata parameters [RFC8414] are
introduced to signal the server's capability and policy with respect
to 1st Party Native Applications.
"authorization_challenge_endpoint": The URL of the authorization
challenge endpoint at which a client can initiate an authorization
request and eventually obtain an authorization code.
9. Security Considerations
9.1. First-Party Applications
Because this specification enables a client application to interact
directly with the end user, and the application handles sending any
information collected from the user to the authorization server, it
is expected to be used only for first-party applications when the
authorization server also has a high degree of trust of the client.
First-party applications are applications that the user recognizes as
belonging to the same brand as the authorization server. For
example, a bank publishing their own mobile application.
9.2. Phishing
There are two ways using this specification increases the risk of
phishing.
With this specification, the client interacts directly with the end
user, collecting information provided by the user and sending it to
the authorization server. If an attacker impersonates the client and
successfully tricks a user into using it, they may not realize they
are giving their credentials to the malicious application.
Parecki, et al. Expires 8 January 2024 [Page 13]
Internet-Draft OAuth for First-Party Native Apps July 2023
In a traditional OAuth deployment using the redirect-based
authorization code flow, the user will only ever enter their
credentials at the authorization server, and it is straightforward to
explain to avoid entering credentials in other "fake" websites. By
introducing a new place the user is expected to enter their
credentials using this specification, it is more complicated to teach
users how to recognize other fake login prompts that might be
attempting to steal their credentials.
Because of these risks, the authorization server MAY decide to
require that the user go through a redirect-based flow at any stage
of the process based on its own risk assessment.
9.3. Client Authentication
Typically, mobile and desktop applications are considered "public
clients" in OAuth, since they cannot be shipped with a statically
configured set of client credentials [RFC8252]. Because of this,
client impersonation should be a concern of anyone deploying this
pattern. Without client authentication, a malicious user or attacker
can mimick the requests the application makes to the authorization
server, pretending to be the legitimate client.
Because this specification is intended for first-party applications,
it is likely that the intent is to also avoid prompting the user with
a consent screen as recommended by [RFC6749].
Implementers SHOULD consider additional measures to limit the risk of
client impersonation, such as using attestation APIs available from
the operating system.
9.4. Sender Constrained Tokens
Tokens issued to native apps SHOULD be sender constrained to mitigate
the risk of token theft and replay.
Proof-of-Possession techniques constrain tokens by binding them to a
cryptographic key. Whenever the token is presented, it should be
accompanied by a proof that the client presenting the token also
controls the cryptographic key bound to the token. If a proof-of-
possession sender constrained token is presented without valid proof
of possession of the cryptographic key, it MUST be rejected.
Parecki, et al. Expires 8 January 2024 [Page 14]
Internet-Draft OAuth for First-Party Native Apps July 2023
9.4.1. Demonstrating Proof-of-Possession
DPoP is an application-level mechanism for sender-constraining OAuth
[RFC6749] access and refresh tokens [I-D.ietf-oauth-dpop]. If DPoP
is used to sender constrain tokens, the native client SHOULD use DPoP
for every token request to the authorization Server and interaction
with the Resource Server.
DPoP includes an optional capability to bind the authorization code
to the DPoP key to enable end-to-end binding of the entire
authorization flow. If an attacker can access the Authorization Code
and PKCE code verifier as described in Section 11.9 of
[I-D.ietf-oauth-dpop], Authorization Code binding SHOULD be used.
To bind the authorization code using the Authorization Challenge
Endpoint, the JWK Thumbprint of the DPoP key MUST be communicated to
the Authorization Server by including the dpop_jkt parameter defined
in section 10 of [I-D.ietf-oauth-dpop] alongside other authorization
request parameters in the POST body of the first Authorization
Challenge Request. If it is included in subsequent Authorization
Challenge Requests, the value of this parameter must be the same as
in the initial request. If the JWK Thumbprint in the dpop_jkt differ
at any point, the Authorization Server MUST reject the request. If
the dpop_jkt parameter is not included in the first request, but
added in subsequent requests, the Authorization Server MUST reject
the request (do we need to define a specific error code for that?).
9.4.2. Other Proof of Possession Mechanisms
It may be possible to use other proof of possession mechanisms to
sender constrain access and refresh tokens. Defining these
mechanisms are out of scope for this specification.
9.4.3. Device Session
* PoP binding of device session parameter
9.5. Multiple Applications
When there there is more than one 1st-party native applications
supported by the AS, then it is important to consider a number of
additional risks. These risks fall into two main categories:
Experience Risk and Technical Risk which are described below.
Parecki, et al. Expires 8 January 2024 [Page 15]
Internet-Draft OAuth for First-Party Native Apps July 2023
9.5.1. Experience Risk
Any time a user is asked to provide the authentication credentials in
user experiences that differ, it has the effect of increasing the
likelihood that the user will fall prey to a phishing attack because
they are used to entering credentials in different looking
experiences. When multiple native applications are support, the
implementation MUST ensure the native experience is identical across
all the 1st party native applications.
Another experience risk is user confusion caused by different looking
experiences and behaviors. This can increase the likelihood the user
will not complete the authentication experience for the 1st party
native application.
9.5.2. Technical Risk
In addition to the experience risks, multiple implementations in 1st
party native applications increases the risk of an incorrect
implementation as well as increasing the attack surface as each
implementation may expose it's own weaknesses.
9.5.3. Mitigation
To address these risk, when multiple 1st party native applications
must be supported, and other methods such as [OpenID.Native-SSO] are
not applicable, it is RECOMMENDED that a client-side SDK be used to
ensure the implementation is consistent across the different native
apps and to ensure the user experience is identical for all 1st party
apps.
10. IANA Considerations
IANA has (TBD) registered the following values in the IANA "OAuth
Authorization Server Metadata" registry of [IANA.OAuth.Parameters]
established by [RFC8414].
*Metadata Name*: authorization_challenge_endpoint
*Metadata Description*: URL of the authorization server's
authorization challenge endpoint.
*Change Controller*: IESG
*Specification Document*: Section 4.1 of [[ this specification ]]
11. References
Parecki, et al. Expires 8 January 2024 [Page 16]
Internet-Draft OAuth for First-Party Native Apps July 2023
11.1. Normative References
[I-D.ietf-oauth-dpop]
Fett, D., Campbell, B., Bradley, J., Lodderstedt, T.,
Jones, M. B., and D. Waite, "OAuth 2.0 Demonstrating
Proof-of-Possession at the Application Layer (DPoP)", Work
in Progress, Internet-Draft, draft-ietf-oauth-dpop-16, 13
April 2023, <https://datatracker.ietf.org/doc/html/draft-
ietf-oauth-dpop-16>.
[I-D.ietf-oauth-step-up-authn-challenge]
Bertocci, V. and B. Campbell, "OAuth 2.0 Step-up
Authentication Challenge Protocol", Work in Progress,
Internet-Draft, draft-ietf-oauth-step-up-authn-challenge-
17, 26 June 2023, <https://datatracker.ietf.org/doc/html/
draft-ietf-oauth-step-up-authn-challenge-17>.
[IANA.OAuth.Parameters]
"*** BROKEN REFERENCE ***".
[OpenID] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0", November 2014,
<https://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Native-SSO]
Fletcher, G., "OpenID Connect Native SSO for Mobile Apps",
November 2022, <https://openid.net/specs/openid-connect-
native-sso-1_0.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/rfc/rfc6749>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <https://www.rfc-editor.org/rfc/rfc7159>.
[RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
for Code Exchange by OAuth Public Clients", RFC 7636,
DOI 10.17487/RFC7636, September 2015,
<https://www.rfc-editor.org/rfc/rfc7636>.
Parecki, et al. Expires 8 January 2024 [Page 17]
Internet-Draft OAuth for First-Party Native Apps July 2023
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/rfc/rfc8259>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/rfc/rfc8414>.
[RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource
Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707,
February 2020, <https://www.rfc-editor.org/rfc/rfc8707>.
[USASCII] Institute, A. N. S., "Coded Character Set -- 7-bit
American Standard Code for Information Interchange, ANSI
X3.4", 1986.
11.2. Informative References
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/rfc/rfc8252>.
Appendix A. Example User Experiences
This section provides non-normative examples of how this
specification may be used to support specific use cases.
A.1. Passwordless One-Time Passwork (OTP)
In a passwordless One-Time Password (OTP) scheme, the user is in
possession of a one-time password generator. This generator may be a
hardware device, or implemented as an app on a mobile phone. The
user provides a user identifier and one-time password, which is
verified by the Authorization Server before it issues an
Authorization Code, which can be exchanged for an Access and Refresh
Token.
* The Client collects username and OTP from user.
* The Client sends an Authorization Challenge Request (Section 5.1)
to the Authorization Challenge Endpoint (Section 4.1) including
the username and OTP.
Parecki, et al. Expires 8 January 2024 [Page 18]
Internet-Draft OAuth for First-Party Native Apps July 2023
* The Authorization Server verifies the username and OTP and returns
an Authorization Code.
* The Client requests an Access Token and Refresh Token by issuing a
Token Request (Section 6) to the Token Endpoint.
* The Authorization Server verifies the Authorization Code and
issues the requested tokens.
A.2. E-Mail Confirmation Code
A user may be required to provide an e-mail confirmation code as part
of an authentication ceremony to prove they control an e-mail
address. The user provides an e-mail address and is then requried to
enter a verification code sent to the e-mail address. If the correct
verification code is returned to the Authorization Server, it issues
Access and Refresh Tokens.
* The Client collects an e-mail address from the user.
* The Client sends the e-mail address in an Authorization Challenge
Request (Section 5.1) to the Authorization Challenge Endpoint
(Section 4.1).
* The Authorization Server sends a verification code to the e-mail
address and returns an Error Response (Section 5.2.2) including
"error": "authorization_required", "device_session" and a custom
error code indicating that an e-mail verification code must be
entered.
* The Client presents a user experience guiding the user to copy the
e-mail verification code to the Client. Once the e-mail
verification code is entered, the Client sends an Authorization
Challenge Request to the Authorization Challenge Endpoint,
including the e-mail verification code as well as the
device_session parameter returned in the previous Error Response.
* The Authorization Server uses the device_session to maintain the
session and verifies the e-mail verification code before issuing
an Authorization Code to the Client.
* The Client sends the Authorization Code in a Token Request
(Section 6) to the Token Endpoint.
* The Authorization Server verifies the Authorization Code and
issues the Access Token and Refresh Token.
Parecki, et al. Expires 8 January 2024 [Page 19]
Internet-Draft OAuth for First-Party Native Apps July 2023
A.3. SMS Confirmation Code
A user may be required to provide an SMS confirmation code as part of
an authentication ceremony to prove they control a mobile phone
number. The user provides a phone number and is then requried to
enter a SMS confirmation code sent to the phone. If the correct
confirmation code is returned to the Authorization Server, it issues
Access and Refresh Tokens.
* The Client collects a mobile phone number from the user.
* The Client sends the phone number in an Authorization Challenge
Request (Section 5.1) to the Authorization Challenge Endpoint
(Section 4.1).
* The Authorization Server sends a confirmation code to the phone
number and returns an Error Response (Section 5.2.2) including
"error": "authorization_required", "device_session" and a custom
error code indicating that a SMS confirmation code must be
entered.
* The Client presents a user experience guiding the user to enter
the SMS confirmation code. Once the SMS verification code is
entered, the Client sends an Authorization Challenge Request to
the Authorization Challenge Endpoint, including the confirmation
code as well as the device_session parameter returned in the
previous Error Response.
* The Authorization Server uses the device_session to maintain the
session context and verifies the SMS code before issuing an
Authorization Code to the Client.
* The Client sends the Authorization Code in a Token Request
(Section 6) to the Token Endpoint.
* The Authorization Server verifies the Authorization Code and
issues the Access Token and Refresh Token.
A.4. Re-authenticating to an app a week later using OTP
A client may be in possession of an Access and Refresh Token as the
result of a previous succesful user authentication. The user returns
to the app a week later and accesses the app. The Client presents
the Access Token, but receives an error indicating the Access Token
is no longer valid. The Client presents a Refresh Token to the
Authorization Server to obtain a new Access Token. If the
Authorization Server requires user interaction for reasons based on
its own policies, it rejects the Refresh Token and the Client re-
Parecki, et al. Expires 8 January 2024 [Page 20]
Internet-Draft OAuth for First-Party Native Apps July 2023
starts the user authentication flow to obtain new Access and Refresh
Tokens.
* The Client has a short-lived access token and long-lived refresh
token following a previous completion of an Authorization Grant
Flow which included user authentication.
* A week later, the user launches the app and tries to access a
protected resource at the Resource Server.
* The Resource Server responds with an error code indicating an
invalid access token since it has expired.
* The Client presents the refresh token to the Authorization Server
to obtain a new access token (section 6 [RFC6749])
* The Authorization Server responds with an error code indicating
that an OTP from the user is required, as well as a
device_session.
* The Client prompts the user to enter an OTP.
* The Client sends the OTP and device_session in an Authorization
Challenge Request (Section 5.1) to the Authorization Challenge
Endpoint (Section 4.1).
* The Authorization Server verifies the device_session and OTP, and
returns an Authorization Code.
* The Client sends the Authorization Code in a Token Request
(Section 6) to the Token Endpoint.
* The Authorization Server verifies the Authorization Code and
issues the requested tokens.
* The Client presents the new Access Token to the Resource Server in
order to access the protected resource.
A.5. Step-up Authentication using Confirmation SMS
A Client previously obtained an Access and Refresh Token after the
user authenticated with an OTP. When the user attempts to access a
protected resource, the Resource Server determines that it needs an
additional level of authentication and triggers a step-up
authentication, indicating the desired level of authentication using
acr_values and max_age as defined in the Step-up Authentication
specification. The Client initiates an authorization request with
the Authorization Server indicating the acr_values and max_age
Parecki, et al. Expires 8 January 2024 [Page 21]
Internet-Draft OAuth for First-Party Native Apps July 2023
parameters. The Authorization Server responds with error messages
promptng for additional authentication until the acr_values and
max_age values are satisfied before issuing fresh Access and Refresh
Tokens.
* The Client has a short-lived access token and long-lived refresh
token following the completion of an Authorization Grant Flow
which included user authentication.
* When the Client presents the Access token to the Resource Server,
the Resource Server determines that the acr claim in the Access
Token is insufficient given the resource the user wants to access
and responds with an insufficient_user_authentication error code,
along with the desired acr_values and desired max_age.
* The Client sends an Authorization Challenge Request (Section 5.1)
to the Authorization Challenge Endpoint (Section 4.1) including
the device_session, acr_values and max_age parameters.
* The Authorization Server verifies the device_session and
determines which authentication methods must be satisfied based on
the acr_values, and responds with an Error Response
(Section 5.2.2) including "error": "authorization_required" and a
custom error code indicating that an OTP must be entered.
* The Client prompts the user for an OTP, which the user obtains and
enters.
* The Client sends an Authorization Challenge Request to the
Authorization Challenge Endpoint including the device_session and
OTP.
* The Authorization Server verifies the OTP and returns an
Authorization Code.
* The Client sends the Authorization Code in a Token Request
(Section 6) to the Token Endpoint.
* The Authorization Server verifies the Authorization Code and
issues an Access Token with the updated acr value along with the
Refresh Token.
* The Client presents the Access Token to the Resources Server,
which verifies that the acr value meets its requirements before
granting access to the prtoected resource.
Parecki, et al. Expires 8 January 2024 [Page 22]
Internet-Draft OAuth for First-Party Native Apps July 2023
A.6. Registration
This example describes how to use the mechanisms defined in this
draft to create a complete user registration flow starting with an
email address. In this example, it is the Authorization Server's
policy to allow these challenges to be sent to email and phone number
that were previously unrecognized, and creating the user account on
the fly.
* The Client collects a username from the user.
* The Client sends an Authorization Challenge Request (Section 5.1)
to the Authorization Challenge Endpoint (Section 4.1) including
the username.
* The Authorization Server returns an Error Response (Section 5.2.2)
including "error": "authorization_required", "device_session", and
a custom error code indicating that an e-mail address must be
collected.
* The Client collects an e-mail address from the user.
* The Client sends the e-mail address as part of a second
Authorization Challenge Request to the Authorization Challenge
Endpoint, along with the device_session parameter.
* The Authorization Server sends a verification code to the e-mail
address and returns an Error Response including "error":
"authorization_required", "device_session" and a custom error code
indicating that an e-mail verification code must be entered.
* The Client presents a user experience guiding the user to copy the
e-mail verification code to the Client. Once the e-mail
verification code is entered, the Client sends an Authorization
Challenge Request to the Authorization Challenge Endpoint,
including the e-mail verification code as well as the
device_session parameter returned in the previous Error Response.
* The Authorization Server uses the device_session to maintain the
session context, and verifies the e-mail verification code. It
determines that it also needs a phone number for account recovery
purposes and returns an Error Response including "error":
"authorization_required", "device_session" and a custom error code
indicating that a phone number must be collected.
* The Client collects a mobile phone number from the user.
Parecki, et al. Expires 8 January 2024 [Page 23]
Internet-Draft OAuth for First-Party Native Apps July 2023
* The Client sends the phone number in an Authorization Challenge
Request to the Authorization Challenge Endpoint, along with the
device_session.
* The Authorization Server uses the device_session parameter to link
the previous requests. It sends a confirmation code to the phone
number and returns an Error Response including "error":
"authorization_required", "device_session" and a custom error code
indicating that a SMS confirmation code must be entered.
* The Client presents a user experience guiding the user to enter
the SMS confirmation code. Once the SMS verification code is
entered, the Client sends an Authorization Challenge Request to
the Authorization Challenge Endpoint, including the confirmation
code as well as the device_session parameter returned in the
previous Error Response.
* The Authorization Server uses the device_session to maintain the
session context, and verifies the SMS verification code before
issuing an Authorization Code to the Client.
* The Client sends the Authorization Code in a Token Request
(Section 6) to the Token Endpoint.
* The Authorization Server verifies the Authorization Code and
issues the requested tokens.
Appendix B. Example Implementation
In order to successfully implement this specification, the
Authorization Server will need to define its own specific
requirements for what values clients are expected to send in the
Authorization Challenge Request (Section 5.1), as well as its own
specific error codes in the Authorization Challenge Response
(Section 5.2).
Below is an example of parameters required for a complete
implementation that enables the user to log in with a username and
OTP.
B.1. Authorization Challenge Request Parameters
In addition to the request parameters defined in Section 5.1, the
authorization server defines the additional parameters below.
"username": REQUIRED for the initial Authorization Challenge
Request.
Parecki, et al. Expires 8 January 2024 [Page 24]
Internet-Draft OAuth for First-Party Native Apps July 2023
"otp": The OTP collected from the user. REQUIRED when re-trying an
Authorization Challenge Request in response to the otp_required
error defined below.
B.2. Authorization Challenge Response Parameters
In addition to the response parameters defined in Section 5.2, the
authorization server defines the additional value for the error
response below.
"otp_required": The client should collect an OTP from the user and
send the OTP in a second request to the Authorization Challenge
Endpoint. The HTTP response code to use with this error value is
401 Unauthorized.
B.3. Example Sequence
The client prompts the user to enter their username, and sends the
username in an initial Authorization Challenge Request.
POST /authorize HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
username=alice
&scope=photos
&client_id=bb16c14c73415
The Authorization Server sends an error response indicating that an
OTP is required.
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store
{
"error": "otp_required",
"device_session": "ce6772f5e07bc8361572f"
}
The client prompts the user for an OTP, and sends a new Authorization
Challenge Request.
Parecki, et al. Expires 8 January 2024 [Page 25]
Internet-Draft OAuth for First-Party Native Apps July 2023
POST /authorize HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
device_session=ce6772f5e07bc8361572f
&otp=555121
The Authorization Server validates the device_session to find the
expected user, then validates the OTP for that user, and responds
with an authorization code.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"authorization_code": "uY29tL2F1dGhlbnRpY"
}
The client sends the authorization code to the token endpoint.
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=bb16c14c73415
&code=uY29tL2F1dGhlbnRpY
The Authorization Server responds with an access token and refresh
token.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "d41c0692f1187fd9b326c63d",
"refresh_token": "e090366ac1c448b8aed84cbc07"
}
Acknowledgments
TODO acknowledge.
Parecki, et al. Expires 8 January 2024 [Page 26]
Internet-Draft OAuth for First-Party Native Apps July 2023
Authors' Addresses
Aaron Parecki
Okta
Email: aaron@parecki.com
George Fletcher
Capital One Financial
Email: george.fletcher@capitalone.com
Pieter Kasselman
Microsoft
Email: pieter.kasselman@microsoft.com
Parecki, et al. Expires 8 January 2024 [Page 27]
