]> Raiffeisen Bank International

yaron.zehavi@rbinternational.com

Okta

aaron@parecki.com

Security Web Authorization Protocol native apps first-party oauth OAuth 2.0 for First-Party Applications (FiPA) defined a native OAuth 2.0 direct interaction, whereby clients call authorization server's Native Authorization Endpoint as an HTTP REST API, whose response instructs client what information to collect from end-user to satisfy authorization server's policies and requirements. While FiPA focused on a one-to-one relationship between client and authorization server, this document is an extension profile adding support for authorization servers to federate the interaction to a downstream authorization server, instruct collection of additional information from users to guide request routing or instruct the usage of another native app for user interaction. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction This document, OAuth 2.0 direct interaction for native clients using federation, extends FiPA to enable federation based flows, while retaining client's direct interaction with end-user. The client calls the Native Authorization Endpoint as an HTTP REST API, and receives instructions via the protocol established by FiPA, guiding client to interact with downstream authorization servers. This establishes a multi authorization server federated flow, whose user interactions are driven by the client app. This document extends FiPA with new error responses: federate, redirect_to_app, insufficient_information and native_authorization_federate_unsupported. It also adds additional response parameters: federation_uri, federation_body, response_uri, deep_link. And adds the native_callback_uri request parameter.

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 when, and only when, they appear in all capitals, as shown here.

Protocol Overview There are three primary ways this specification extends FiPA:

• federate response: Sends the client to interact with a downstream authorization server.
• insufficient_information response: Instructs the client to collect information from end-user required to decide where to federate to. For example this could be an email address which identifies the trust domain.
• redirect_to_app: Instructs the client to natively invoke an app to interact with end user.

Representative flow: Native client federated and redirected to app || Native || Starts| | | || Authorization || Flow +-->| Client |<----------------------|| Endpoint || | | (C)Federate Error |+------------------+| | | Response +--------------------+ | | : | | : +--------------------+ | | : | Authorization | | | (D)Native | Server 2 | | | Authorization Request |+------------------+| | |---------------------->|| Native || | | || Authorization || | |<----------------------|| Endpoint || | | (E) Redirect to |+------------------+| | | App Response +--------------------+ | | : | | : +--------------------+ | | (F) Invoke App | | | |---------------------->| Native App of | | | | Auth Server 2 | | |<----------------------| | | | (G)Authorization code +--------------------+ | | For Auth Server 1 | | : +--------------------+ | | : | Authorization | | | (H)Authorization Code | Server 1 | | | For Auth Server 1 |+------------------+| | |---------------------->|| Response || | | || Uri || | |<----------------------|| Endpoint || | | (I) Authorization |+------------------+| | | Code Response | | | | : | | | | : | | | | (J) Token Request |+------------------+| | |---------------------->|| Token || | | || Endpoint || | |<----------------------|| || | | (K) Access Token |+------------------+| | | +--------------------+ | | +----------+ ]]> Figure: Native client federated, then redirected to app

• (A) The client starts the flow.
• (B) The client initiates the authorization request by making a POST request to the Native Authorization Endpoint of Authorization Server 1.
• (C) Authorization Server 1 decides to federate the user to Authorization Server 2. To do so it contacts Authorization Server 2's PAR endpoint, then returns the federate error code together with the federation_uri, federation_body, response_uri and auth_session response attributes.
• (D) The client calls Authorization Server 2's Native Authorization Endpoint, as instructed by Authorization Server 1.
• (E) Authorization Server 2 decides to use a native app, and therefore responds with the redirect_to_app error code together with the deep_link response attribute.
• (F) The client invokes the app using the deep_link.
• (G) The app interacts with user and if satisifed, returns an authorization code, regarded as Authorization Server 2's response to Authorization Server 1's federation to it.
• (H) The client provides the authorization code to Authorization Server 1.
• (I) Authorization Server 1 returns an authorization code.
• (J) The client sends the authorization code received in step (I) to obtain a token from the Token Endpoint.
• (K) Authorization Server 1 returns an Access Token from the Token Endpoint.

Protocol Endpoints

Native Authorization Endpoint The native authorization endpoint defined by FiPA is used by this document. This document adds the native_callback_uri parameter to the native authorization endpoint, to support native user navigation across apps. Before an authorization server instructs a client to federate to a downstream authorization server, it SHALL ensure the federated authorization server offers a native_authorization_endpoint, otherwise return the error native_authorization_federate_unsupported. When federating to downstream authorization servers, the usage of PAR with client authentication is REQUIRED, because when the client interacting with end-user calls the federated authorization server, it is not its OAuth client and therefore has no other means of authenticating. When using PAR with client authentication, the request_uri provided to the Native Authorization Endpoint attests that client authentication (by the federating authorization server) took place.

Native Authorization Request The native authorization endpoint is called as defined by FiPA . This document adds the following request parameter:

"native_callback_uri":

OPTIONAL. Native client app's redirect_uri, claimed as deep link. native_callback_uri SHALL be natively invoked by authorization server's user-interacting app to provide its response to the client app. If native_callback_uri is included in a native authorization request, authorization server MUST include the native_callback_uri when federating to another authorization server.

Native Authorization Response This document extends FiPA's error response, by adding the following error codes:

"error":

REQUIRED. A single ASCII error code from the following:

"insufficient_information":

the Authorization Server requires additional user input, other than an authentication challenge, to determine the target authorization server to federate to. See for details.

"federate":

The Authorization Server wishes to federate to another authorization server, which it is a client of. This response MUST include the federation_uri response parameter. See for details.

"redirect_to_app":

The Authorization Server wishes to fulfill the user interaction using another native app. This response MUST include the federation_uri response parameter. See for details.

"native_authorization_federate_unsupported":

The authorization server intended to federate to a downstream authorization server, but it does not support the native authorization endpoint.

And adds the following response attributes:

"federation_uri":

OPTIONAL. The Native Authorization Endpoint of a downstream authorization server to federate to.

"deep_link":

OPTIONAL. A URI of native app to be invoked to handle the request.

"federation_body":

OPTIONAL. A string of application/x-www-form-urlencoded request parameters according to this specification for the downstream authorization server's Native Authorization Endpoint.

"response_uri":

OPTIONAL. A URI of an endpoint of federating authorization server which shall receive the response from the federated authorization server.

Federating Response If the authorization server decides to federate to another authorization server, it responds with error code federate and MUST return the federation_uri, federation_body, response_uri and auth_session response attributes. When federating to another authorization server:

• Federating authorization server MUST use PAR and include request_uri in federation_body.
• If native_callback_uri was included in the native authorization request, it MUST be included when calling federated authorization server's Native Authorization Endpoint.

Example federating response: Client MUST call the federation_uri using HTTP POST, and provide it federation_body as application/x-www-form-urlencoded request body. Example: The client MUST provide any response obtained from the federated authorization server, as application/x-www-form-urlencoded request body for the response_uri of the respective federating authorization server which SHALL be invoked using HTTP POST. However, when federated authorization server returns the following error codes: federate, insufficient_authorization, insufficient_information, redirect_to_app, redirect_to_web, client MUST handle these errors according to FiPA and this specification. Example client calling receiving an authorization code response from the federated authorization server: And providing it to the federating authorization server's response_uri, adding previously obtained auth_session:

Redirect to app response If the authorization server decides to nominate another native app to interact with end user, it responds with error code redirect_to_app and MUST return the deep_link response attribute. Example redirect_to_app response: Client MUST use OS mechanisms to invoke the obtained deep_link. If no app claiming deep_link is found on the device, client MUST terminate the flow and MAY attempt a normal non-native OAuth flow. The invoked app handles the native authorization request:

• Validates the request and ensures it contains a native_callback_uri, Otherwise terminates the flow.
• Establishes trust in native_callback_uri and validates that an app claiming it is on the device. Otherwise terminates the flow.
• Authenticates end-user and authorizes the request.
• Uses OS mechanisms to natively invoke native_callback_uri and return to the client, providing it a response according to this specification's response from a Native Authorization Endpoint, as url-encoded query parameters.

Note - trust establishment mechanisms in native_callback_uri are out of scope of this specification. However we assume closed ecosystems could employ an allowList, and open ecosystems could leverage :

• Extract native_callback_uri's DNS domain.
• Add the path /.well-known/openid-federation and perform trust chain resolution.
• Inspect client's metadata for redirect_uri's and validate native_callback_uri is included among them.

When the client is invoked on its native_callback_uri, it shall regard the invocation as a response from the authorization server which instructed redirect_to_app. Therefore, obtained response's audience is the authorization server which federated the client to the authorization server which redirected the client to the app. See for details. Example URI used to invoke of client app on its claimed native_callback_uri: Example client invoking the response_uri of the authorization server which federated it to the authorization server, which redirected it to the app:

Additional Information Required Response If additional user input is required, for example to determine where to federate to, the response body shall contain the following additional properties:

logo:

OPTIONAL. URL or base64-encoded logo of Authorization Server, for branding purposes.

userPrompt:

REQUIRED. A JSON object containing the prompt definition. The following parameters MAY be used:

• options: OPTIONAL. A JSON object that defines a dropdown/select input with various options to choose from. Each key is the parameter name to be sent in the response and each value defines the option:
  • title: OPTIONAL. A string holding the input's title.
  • description: OPTIONAL. A string holding the input's description.
  • values: REQUIRED. A JSON object where each key is the selection value and each value holds display data for that value:
    • name: REQUIRED. A string holding the display name of the selection value.
    • logo: OPTIONAL. A string holding a URL or base64-encoded image for that selection value.
• inputs: OPTIONAL. A JSON object that defines an input field. Each key is the parameter name to be sent in the response and each value defines the input field:
  • title: OPTIONAL. A string holding the input's title.
  • hint: OPTIONAL. A string holding the input's hint that is displayed if the input is empty.
  • description: OPTIONAL. A string holding the input's description.

Example of requesting end-user for 2 multiple-choice inputs: Example of requesting end-user for text input entry (email): The client gathers the required additional information and makes a POST request to the Native Authorization Endpoint. Example of response following end-user multiple-choice: Example of Client App response following end-user input entry:

Security Considerations

Non First-Party applications of federated authorization servers A federated authorization server should consider end-user's privacy and security to determine if it should present authorization challenges in federation scenarios. For example, it can label federating clients as such and avoid serving them (i.e: client's interacting on their behalf) authorization challenges involving sensitive data, as these are not first party clients.

IANA Considerations

OAuth Parameters Registration IANA has (TBD) registered the following values in the IANA "OAuth Parameters" registry of established by . Parameter name: native_callback_uri Parameter usage location: Native Authorization Endpoint Change Controller: IETF Specification Document: Section 5.4 of this specification

Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This document defines the pushed authorization request (PAR) endpoint, which allows clients to push the payload of an OAuth 2.0 authorization request to the authorization server via a direct request and provides them with a request URI that is used as reference to the data in a subsequent call to the authorization endpoint. Okta Capital One Financial Defakto Security This document defines the Authorization Challenge Endpoint, which supports a first-party 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. IANA In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Example User Experiences This section provides non-normative examples of how this specification may be used to support specific use cases.

Native client federated and redirected to app

Diagram || Native || Starts| | | || Authorization || Flow +-->| Client |<----------------------|| Endpoint || | | (C)Federate Error |+------------------+| | | Response +--------------------+ | | : | | : +--------------------+ | | : | Authorization | | | (D)Native | Server 2 | | | Authorization Request |+------------------+| | |---------------------->|| Native || | | || Authorization || | |<----------------------|| Endpoint || | | (E) Redirect to |+------------------+| | | App Response +--------------------+ | | : | | : +--------------------+ | | (F) Invoke App | | | |---------------------->| Native App of | | | | Auth Server 2 | | |<----------------------| | | | (G)Authorization code +--------------------+ | | For Auth Server 1 | | : +--------------------+ | | : | Authorization | | | (H)Authorization Code | Server 1 | | | For Auth Server 1 |+------------------+| | |---------------------->|| Response || | | || Uri || | |<----------------------|| Endpoint || | | (I) Authorization |+------------------+| | | Code Response | | | | : | | | | : | | | | (J) Token Request |+------------------+| | |---------------------->|| Token || | | || Endpoint || | |<----------------------|| || | | (K) Access Token |+------------------+| | | +--------------------+ | | +----------+ ]]> Figure: Native client federated, then redirected to app

Client makes initial request and receives "federate" error Client calls the native authorization endpoint and includes the native_callback_uri parameter: The first authorization server, as-1.com, decides to federate to as-2.com after validating it supports the native authorization endpoint. If it does not, as-1.com returns: If native authorization endpoint is supported by the federated authorization server, as-1.com performs a PAR request to as-2.com's pushed authorization endpoint, including the original native_callback_uri: as-1.com receives a request_uri from as-2.com's PAR endpoint, which it includes in its response to client, in the federation_body attribute: See for more details.

Client calls federated authorization server and is redirected to app Client calls the federation_uri it got from as-1.com using HTTP POST with federation_body as application/x-www-form-urlencoded request body: as-2.com decides to use its native app to interact with end-user and responds: Client locates an app claiming the obtained deep_link and invokes it. See for more details. The invoked app handles the native authorization request and then natively invokes native_callback_uri:

Client calls federating authorization server Client invokes the response_uri of as-1.com as it is the authorization server which federated it to as-2.com and the app's response is regarded as the response of as-2.com: And receives in response an authorization code, which it is the audience of (no further federations) to resolve: Client proceeds to exchange code for tokens.

Document History -00

• Document creation

Acknowledgments The authors would like to thank the attendees of IETFs 123 & 124 in which this was discussed, as well as the following individuals who contributed ideas, feedback, and wording that shaped and formed the final specification: George Fletcher, Arndt Schwenkshuster, Filip Skokan.