Skip to content

Latest commit

 

History

History
327 lines (201 loc) · 10.1 KB

draft-parecki-oauth-direct-interaction-grant.md

File metadata and controls

327 lines (201 loc) · 10.1 KB

title: "OAuth 2.0 Direct Interaction Grant" category: std

docname: draft-parecki-oauth-direct-interaction-grant-latest submissiontype: IETF number: date: consensus: true v: 3 area: AREA workgroup: OAuth Working Group keyword:

author:

normative: RFC6749: RFC6755: RFC7636: IANA.OAuth.Parameters:

informative:

--- abstract

This document extends the OAuth 2.0 Authorization Framework {{RFC6749}} with a new grant type, the "Direct Interaction Grant", which can be used by applications that want to control the user experience of the process of obtaining authorization from the user.

In many cases, this can provide an entirely browserless experience suited for native applications, only delegating to the browser in unexpected or error conditions.

While a fully-delegated approach using the 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 well as should only be considered when there are usability concerns with a browser-based approach, such as for native mobile or desktop applications.

--- middle

Introduction

TODO

Usage and Applicability

TODO: Mention the trust prerequisites for this to be useful. Absolutely not allowed for third-party apps. Designed for native apps, specifically first-party, when the AS and app are operated by the same entity, and the user understands them both as the same entity...

Conventions and Definitions

{::boilerplate bcp14-tagged}

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

Protocol Overview

  1. The client prompts the user and collects their user identifier (e.g. email address)
  2. The client sends the identifier to the AS
  3. The AS replies with the supported authentication mechanisms based on the user ID provided
  4. The client requests an authentication challenge from the AS
  5. The AS delivers a challenge to the user (e.g. one-time code via email, SMS, or a push notification in an app)
  6. The client collects the necessary authentication details from the user and sends them back to the AS
  7. The AS decides if additional requirements need to be met, repeating steps 3 through 6 as needed
  8. The AS replies with the token response

Protocol

Client collects user identifier

TODO: User identifier can be an email, phone number, or username, at the discretion of the AS.

Client initiates direct interaction request

The client makes a request to the interaction request endpoint providing the client ID and user identifer hint in the request.

POST /interaction
Host: authorization-server.com
Content-type: application/x-www-form-urlencoded

&client_id=XXXXXXX
&username=user@example.com
&scope=contacts+openid+profile

Authorization Server returns challenge types

The AS returns an interaction code, as well as a list of challenge types supported.

HTTP/1.1 403 Forbidden
Content-type: application/json

{
  "error": "...?",
  "interaction_code": "b135ac938e3e84",
  "challenge_type": [
    "password+totp", "email_otp", "redirect"
  ]
}

One-Time code

  • email_otp
  • sms_otp

One-time codes sent via email or SMS

TOTP

  • totp

TOTP codes generated by an authenticator app

Password

  • password

Legacy password authentication

Push notification

  • push_notification

A push notification delivered to a native application

Redirect

  • redirect

In the case where the authorization server wishes to interact with the user itself, limiting the client's interaction with the user, it can return the redirect challenge type. In this case, no interaction_code is returned. Instead, the client is expected to initiate a traditional OAuth Authorization Code flow with PKCE according to {{RFC6749}} and {{RFC7636}}.

TODO: Instead of no interaction code, should this require the client include the interaction code in the authorization request so the AS can link it to an app-initiated session? Alternatively, if we make the first request require a PKCE code challenge, we could require the same PKCE code challenge be used in the authorization request.

This can be used to:

  • offer the client a fallback mechanism at the client's perogative (by returning the redirect type as the last item in the challenge_type list)
  • force the client to use a browser-redirect-based flow (by returning only the redirect type)
  • enable authentication with social providers or third party IdPs which require a browser flow

Combinations

The AS MAY combine challenge types by concatenating strings with a +, which indicates that all the combined types are required to complete the challenge.

Defining additional methods

Extensibility...

Client requests an authentication challenge

Optional.

For methods that require the AS to deliver a code to the user, e.g. via email or SMS, the client needs to signal to the AS that it should deliver this code. (Without this step, the AS may not know which of the available options the client will be communicating to the user, and may not want to send a code via both email and SMS.)

POST /challenge
Host: authorization-server.com
Content-type: application/x-www-form-urlencoded

challenge_type=email_otp
&interaction_code=b135ac938e3e84

The authorization server sends a challenge code to the user via the selected platform.

The authorization server responds with an authentication challenge code and other information such as timeouts.

HTTP/1.1 200 OK
Content-type: application/json

{
  "challenge_type": "email_otp",
  "challenge_code": "a6f4463ad1d8e3f",
  "expires_in": 600,
  "interval": 5
}
  • challenge_type -
  • challenge_code -
  • expires_in - Optional
  • interval - Optional

Client provides authentication details

The client prompts the user to enter the challenge.

  • One-time code
  • Password
  • Out-of-band interaction

Some methods such as acknowledging a push notification may not require the user to interact further with the client. The client instead presents a screen to the user explaining that they should acknowledge the challenge on another device.

Token request

The client makes a request to the token endpoint with the grant_type value of urn:ietf:params:oauth:grant-type:direct, providing the information collected from the user as well as the previous interaction code and optional challenge code.

POST /token

Host: authorization-server.com
Content-type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:direct
&client_id=XXXXXXX
&interaction_code=b135ac938e3e84
&challenge_code=a6f4463ad1d8e3f
&challenge_value=512512
  • challenge_value - The value that was sent to the user. Should this be different depending on the challenge type?

TODO: What happens if more than one code is requested? Maybe make it so only one can be collected at a time? It would be weird to ask the user to enter two codes at the same time anyway

Checking for additional requirements

If the initial set of information provided by the client is correct, the AS MAY choose to either respond immetiately with a successful token request, or prompt the client with an additional challenge.

For example, the AS could first require the client prompt the user for a one-time-code they received via email, and then in a second step, ask the client to prompt the user

Refresh Token Grant

TODO: Describe how the AS could return a challenge to the client on the normal refresh token request that tells the client they need to get the user to re-authenticate or provide an MFA token.

Security Considerations

TODO Security

Phishing

TODO: Describe the phishing risk this opens up.

Client Authentication

TODO: Describe the lack of client authentication possible because this is expected to be deployed by native apps. Maybe mention alternatives to client authentication such as App Attestation, or using a risk engine to analyze other aspects of the request from the client.

Leaking Information

TODO: Attackers may be able to query the AS with user IDs to learn whether an identifier corresponds to an active account and which types of authentication a particular account has configured. What mitigations needed here? Possibly avoiding returning an error for unrecognized identifiers.

Notification fatigue

TODO: A client may be able to cause repeated notifications to any user given their user ID. Mitigations?

IANA Considerations

OAuth Parameter Registration

TODO

OAuth URI Registration

This specification registers the following values in the IANA "OAuth URI" registry {{IANA.OAuth.Parameters}} established by {{RFC6755}}.

URN: `urn:ietf:params:oauth:grant-type:direct`
Common Name: Direct Interaction Grant Type for OAuth 2.0
Change Controller: IESG
Specification Document:

OAuth Extensions Error Registration

This specification registers the following values in the IANA "OAuth Extensions Error Registry" registry {{IANA.OAuth.Parameters}} established by {{RFC6749}}.

Name: ...

Authorization Server Metadata

This specification defines two new endpoints at the authorization server. TODO: Need to register these in the Authorization Server Metadata document too.

  • interaction endpoint
  • challenge endpoint

--- back

Acknowledgments

{:numbered="false"}

TODO acknowledge.