OAuth 2.0 for First-Party Native Applications

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.¶

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.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.1. Initial Authorization Request

                                                +-------------------+
                                                |   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)¶
• (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.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.¶

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.¶

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.¶

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "authorization_code": "uY29tL2F1dGhlbnRpY"
}

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.¶

The client MUST include the device session in future requests to the authorization challenge endpoint for the particular 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"
}

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.¶

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.¶

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.¶

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.¶
• 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.¶

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-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 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.¶

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.¶
• 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.¶

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.¶

"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.¶

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"
}